Bazaar — Service Discovery

What is Bazaar?

Bazaar is the discovery layer for x402. It answers: "What can I buy here, and how much does it cost?" Agents browse a structured catalog of services, prices, and input/output schemas at /.well-known/x402.json.

How it works

Publish /.well-known/x402.json:

{
  "x402Version": 1,
  "name": "Your Service",
  "description": "What your service does",
  "network": "base",
  "facilitator": "coinbase",
  "payTo": "0xYourWallet",
  "services": [
    {
      "method": "POST",
      "path": "/api/generate",
      "description": "Generate content",
      "amount": "100000",
      "discoverable": true,
      "outputSchema": {
        "input": {
          "type": "http",
          "method": "POST",
          "bodyFields": {
            "prompt": { "type": "string", "required": true }
          }
        },
        "output": {
          "result": { "type": "string" }
        }
      }
    }
  ],
  "freeEndpoints": [
    { "method": "GET", "path": "/api/status", "description": "Health check (free)" }
  ]
}

Key fields

name: Your service's display name in the catalog
facilitator: Payment processor — "coinbase" for mainnet
payTo: Wallet address that receives payments
discoverable: Set true on services you want agents to find
outputSchema: Describes request/response format so agents know how to call your API
freeEndpoints: Listed so agents know what they can access without paying

402 header extensions (optional)

For full Bazaar support, include extensions.bazaar in the base64-encoded Payment-Required header of your 402 response. This is the JSON payload before base64 encoding:

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "100000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0xYourWallet",
      "maxTimeoutSeconds": 60
    }
  ],
  "resource": {
    "description": "Your endpoint description"
  },
  "extensions": {
    "bazaar": {
      "discoverable": true
    }
  }
}

The server base64-encodes this JSON and returns it in the HTTP header:

HTTP/1.1 402 Payment Required
Payment-Required: eyJ4NDAyVmVyc2lvbiI6MiwiYWNjZXB0cyI6Wy4uLl0sImV4dGVuc2lvbnMiOnsiYmF6YWFyIjp7ImRpc2NvdmVyYWJsZSI6dHJ1ZX19fQ==

The extensions.bazaar object is optional — your site will not lose points for omitting it. When present, it signals to agents that this endpoint is part of a discoverable catalog.

Spec maturity

Part of x402 v2. Bazaar discovery is defined within the x402 specification.

Learn more