Listing schema

A listing is one provider with one or more services (endpoints). The catalog is an array of these entries. Below is the exact shape the marketplace validates.

Provider entry

Field	Type	Required	Notes
id	string	✓	Stable, unique provider id (slug).
name	string	✓	Human-readable provider name.
description	string	✓	What you offer. Plain description only — see security.
mcpUrl	url	✓	Your MCP server URL (for MCP-based discovery).
services	array	✓	One or more service entries (below), at least one.
tags	string[]	—	Discovery tags. Defaults to [].
active	boolean	—	Defaults to true. Only active providers are ingested.
payTo	0x address	—	Optional. Pins the recipient; see pricing & payTo.

Service entry

Field	Type	Required	Notes
url	url	✓	The x402-payable endpoint. HTTPS required.
method	"GET" | "POST"	✓	HTTP method agents call.
priceUSDC	string	✓	Decimal string, e.g. "0.01". Must match your 402 challenge.
capability	string	✓	Short capability label, e.g. xdc.defi.rates.summary.

Example

[
  {
    "id": "acme-data",
    "name": "Acme Data",
    "description": "Real-time DeFi lending rates and USDC metrics on XDC.",
    "mcpUrl": "https://api.acme.example/mcp",
    "tags": ["defi", "rates", "usdc", "xdc"],
    "active": true,
    "services": [
      {
        "url": "https://api.acme.example/x402/rates/summary",
        "method": "GET",
        "priceUSDC": "0.01",
        "capability": "xdc.defi.rates.summary"
      },
      {
        "url": "https://api.acme.example/x402/usdc/metrics",
        "method": "GET",
        "priceUSDC": "0.02",
        "capability": "xdc.usdc.metrics"
      }
    ]
  }
]

Rules & tips

• payTo is not part of a service — it's attached at the provider level (derived or pinned). See pricing & payTo.
• Keep capability values namespaced and specific (xdc.<domain>.<thing>) so ranking and filtering work well.
• Rich, accurate tags improve how often agents find you for relevant tasks.
• The schema is permissive about extra keys, so you may annotate freely — unknown fields are ignored.
• priceUSDC must be a plain decimal string like "0.01" (no $, no units).

Next: Make an x402 endpoint →