Bazaar Discovery

​

How listing works

1. Your server declares. Your 402 response includes a bazaar discovery declaration describing the endpoint (method, input/output shape, service metadata).
2. The buyer’s client echoes. The client copies your declaration from the 402 response into the payment payload it sends to the facilitator. This is required client behavior in x402 v2 — the client must include at least the extension info it received.
3. The facilitator catalogs. On /verify and /settle, the facilitator extracts the declaration from the payment payload and upserts your catalog entry asynchronously.
4. The catalog worker admits the resource. Before a resource is listed for the first time, the worker checks the URL against the host policy below and sends one read-only probe (HEAD, then GET on 404/405; the probe never sends POST, PUT, PATCH or DELETE). A resource is listed when either proof holds: the indexing payment was a settlement (a buyer only pays after receiving your 402), or the read-only probe itself answers 402 Payment Required. A verify-only first listing of a POST/PUT/PATCH/DELETE or MCP resource (or one with no declared method) is deferred with resource_needs_settlement until its first settled payment; a GET resource answering something other than 402 unpaid is refused as resource_not_x402. Unreachable hosts, GET paths answering 404/405/410, and hosts resolving to private address space are refused regardless. Existing entries are refreshed without a probe.

​

Declaring your resource

{
  "x402Version": 2,
  "resource": {
    "url": "https://api.example.com/convert",
    "description": "Convert PDFs to markdown",
    "mimeType": "application/json",
    "serviceName": "Example Converter",
    "tags": ["pdf", "markdown"],
    "iconUrl": "https://api.example.com/icon.png"
  },
  "accepts": [ ... ],
  "extensions": {
    "bazaar": {
      "info": {
        "input": { "type": "http", "method": "POST", "bodyType": "json", "body": { ... } },
        "output": { "type": "json", "example": { ... } }
      },
      "schema": { ... }
    }
  }
}

​

Host policy

​

Reading EXTENSION-RESPONSES

EXTENSION-RESPONSES: eyJiYXphYXIiOnsic3RhdHVzIjoicHJvY2Vzc2luZyJ9fQ==
                     → {"bazaar":{"status":"processing"}}

​

Rejection reasons

​

What gets catalogued

​

Refresh semantics

• Entries are upserted from every payment that carries the extension — accepts, schemas, metadata, and lastUpdated all refresh. Identical repeats of an unchanged listing are collapsed so a busy endpoint does not rewrite its row on every payment; a payment whose declaration, accepts, or service metadata changed is written straight away.
• Refresh is forward-only. Correcting your declaration does not rewrite the catalog until the next extension-carrying payment arrives.
• Listed resources are probed on an ongoing basis with read-only HEAD/GET requests (every listed row at least once a day; recently settling resources more often). A resource that fails three consecutive probes spanning at least 48 hours — connection failures, timeouts, 5xx, or 404/405/410 on a GET/HEAD resource — is hidden from /discovery/resources and /discovery/search; the first healthy probe, or a successful settlement through the facilitator (identical settlements are coalesced, so allow up to five minutes), relists it automatically. A 404/405 from a POST/PUT/PATCH/DELETE, MCP, or method-less resource is inconclusive and changes nothing. A hostname that starts resolving to private address space is hidden immediately and is relisted only by a healthy probe. Hidden rows keep their data and are visible through /discovery/listing-status.
• There is no re-index endpoint. To force a refresh, make one verify-shaped payment against your own endpoint through a client that echoes extensions — /verify catalogs and moves no funds. Confirm with the processing header status.

​

Endpoints

​

GET /discovery/resources

​

GET /discovery/search

​

GET /discovery/listing-status

​

GET /discovery/stats

"merchants": {
  "hosts": 1505,          // distinct services — the "how many merchants" number
  "resources": 25086,     // distinct paid endpoint URLs
  "catalogEntries": 25086, // rows: one per (resource, toolName)
  "total": 25086          // deprecated alias of catalogEntries
}

​

Opting out and delisting

• v1: declare discoverable: false inside outputSchema.input and the facilitator will not index the resource.
• v2: simplest is to omit the bazaar extension from your 402 — with nothing to echo, nothing is indexed.
• Dead resources leave on their own. Take the endpoint down (connection refused, DNS gone, or 404/410 on a GET resource) and the probes above hide it within about two days; it comes back automatically if it reappears. Entries on hosts that can never be reached from the public internet were removed in September 2026 and are refused at write time.
• Immediate removal of a live entry (for example a path you have retired but still serve) is still a manual request — reach out on Discord or open an issue with proof of resource ownership. The x402 specification defines no delisting semantics yet.

​

Troubleshooting

​

Need help?