x402 Bazaar (Discovery Layer)

​

Overview

• For buyers (API consumers, including agents): call the discovery endpoints to list or search the CDP Facilitator’s catalog, inspect pricing and schemas, then pay and call the resource.
• For sellers (API providers): when the CDP Facilitator sees a valid x402 payment that implements Bazaar cataloging, your declared metadata can surface in the CDP Bazaar discovery APIs.

​

Access modes

• Paginated catalog (HTTP) (GET /v2/x402/discovery/resources) — inventory-style browsing with limit and offset. For custom UIs, dashboards, and backend integrations. Paths, parameters, and examples are in CDP discovery endpoints (HTTP) and Paginated catalog below.
• Semantic search (HTTP) (GET /v2/x402/discovery/search) — same CDP index as the catalog, optimized for query, filters, and quality ranking, not for walking the full catalog. See CDP Bazaar: Semantic search.
• MCP Server (GET /v2/x402/discovery/mcp) — for AI agents via Model Context Protocol (search_resources / proxy_tool_call wrap paid calls). See Bazaar MCP Server and the MCP Server guide.

​

How it works

1. Sellers declare discovery metadata (input/output schemas) in their route configuration.
2. The CDP Facilitator extracts and catalogs that metadata when it processes payments for your routes (discovery indexing runs after settle completes; verify alone is not enough).
3. Buyers call the discovery APIs below: a paginated catalog, semantic search, or merchant lookup.

​

v1 vs v2

​

Seller integration

1. Point your resource server at the CDP Facilitator URL https://api.cdp.coinbase.com/platform/v2/x402 for verify and settle.
2. Register bazaarResourceServerExtension (Node/Go/Python equivalents) and attach declareDiscoveryExtension() (or the language-specific helper) on routes you want discoverable.
3. Complete at least one successful settlement through CDP (after verify) so discovery can index the resource.

​

Discovery extension options

// For GET endpoints (query params)
declareDiscoveryExtension({
  input: { city: "San Francisco" }, // Example query params
  inputSchema: {
    properties: {
      city: { type: "string", description: "City name" },
    },
    required: ["city"],
  },
  output: {
    example: { temperature: 72 },
    schema: {
      properties: {
        temperature: { type: "number" },
      },
    },
  },
});

// For POST endpoints (request body)
declareDiscoveryExtension({
  input: { prompt: "Hello world" }, // Example body
  inputSchema: {
    properties: {
      prompt: { type: "string", maxLength: 1000 },
    },
    required: ["prompt"],
  },
  bodyType: "json", // Signals this is a body method
  output: {
    example: { response: "Hi there!" },
  },
});

​

Bazaar extension validation

​

Buyer integration

​

CDP discovery endpoints (HTTP)

​

CDP Facilitator discovery endpoint

GET https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources

​

Query parameters

​

Response body (200 OK)

{
  "x402Version": 2,
  "items": [
    {
      "resource": "https://api.example.com/weather",
      "type": "http",
      "x402Version": 1,
      "accepts": [
        {
          "scheme": "exact",
          "network": "eip155:84532",
          "amount": "1000",
          "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
          "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C"
        }
      ],
      "lastUpdated": "2024-01-15T12:30:00.000Z",
      "metadata": {
        "description": "Weather data API",
        "input": { ... },
        "output": { ... }
      }
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 42
  }
}

​

items[] fields

​

CDP Bazaar: Semantic search

GET https://api.cdp.coinbase.com/platform/v2/x402/discovery/search

​

Quality ranking

1. Retrieval relevance — how well the service matches your query and filters, using the mode indicated by searchMethod in the response (for example semantic vector vs full-text retrieval over the same indexed text CDP stores for Bazaar).
2. Service quality (objective signals) — a composite, facilitator-side score informed by observable CDP data, including:
   • Buyer reach — how many distinct buyers the service has served (through the CDP Facilitator)
   • Transaction volume — how many transactions (successful payments) the resource has processed
   • Recency — how recently the service has been used
   • Metadata quality — quality and completeness of Bazaar / discovery metadata (for example descriptions, input/output schemas, and examples)

​

Query parameters

​

Response (200 OK)

{
  "resources": [
    {
      "resource": "https://example.com/api/endpoint",
      "type": "http",
      "x402Version": 2,
      "description": "Optional description of the resource",
      "lastUpdated": "2025-01-01T00:00:00Z",
      "accepts": []
    }
  ],
  "partialResults": false,
  "searchMethod": "vector",
  "x402Version": 2
}

GET https://api.cdp.coinbase.com/platform/v2/x402/discovery/search
GET https://api.cdp.coinbase.com/platform/v2/x402/discovery/search?query=weather+data
GET https://api.cdp.coinbase.com/platform/v2/x402/discovery/search?network=eip155:8453&asset=usdc
GET https://api.cdp.coinbase.com/platform/v2/x402/discovery/search?payTo=0xabc123...&maxUsdPrice=1.0
GET https://api.cdp.coinbase.com/platform/v2/x402/discovery/search?query=news&scheme=upto&limit=5
GET https://api.cdp.coinbase.com/platform/v2/x402/discovery/search?extensions=custom&network=base-sepolia

​

Merchant discovery endpoint

GET https://api.cdp.coinbase.com/platform/v2/x402/discovery/merchant?payTo=<address>

​

Query parameters

​

Response schema

{
  "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
  "resources": [
    {
      "resource": "https://api.example.com/premium/data",
      "type": "http",
      "x402Version": 2,
      "accepts": [
        {
          "scheme": "exact",
          "network": "eip155:84532",
          "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
          "amount": "1000",
          "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
          "maxTimeoutSeconds": 60
        }
      ],
      "lastUpdated": "2025-06-01T12:00:00.000Z",
      "metadata": {
        "description": "Premium data API"
      }
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

​

Bazaar MCP Server

​

How the MCP server works

1. search_resources — Semantic search across the Bazaar index. Returns matching resource descriptions, pricing, input/output schemas, and relevance-ordered results.
2. proxy_tool_call — Call a discovered resource by passing its toolName and arguments. Under the hood, the @x402/mcp client sends the call to the Bazaar MCP server. If the server responds with a payment-required error, the client automatically creates a payment payload using the configured x402 client, attaches it to the MCP request’s _meta field, and retries the call. The server then verifies and settles the payment on-chain before forwarding the request to the resource server and returning the response.

​

MCP Server endpoint

https://api.cdp.coinbase.com/platform/v2/x402/discovery/mcp

​

Client setup

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { createX402MCPClient } from "@x402/mcp";
import { x402Client } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

// 1. Create an x402 payment client
const paymentClient = new x402Client();
const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
registerExactEvmScheme(paymentClient, { signer });

// 2. Create a standard MCP client and connect to the Bazaar
const mcpClient = new Client({ name: "my-agent", version: "1.0.0" });
// ... connect mcpClient to the Bazaar MCP server transport ...

// 3. Wrap with automatic payment handling
const client = createX402MCPClient(mcpClient, paymentClient, {
  autoPayment: true,
  onPaymentRequested: async (req) => {
    console.log(`Payment requested: ${req.price} on ${req.network}`);
    return true; // approve
  },
});

// 4. Discover available tools
const results = await client.callTool("search_resources", {
  query: "weather forecast",
});

// 5. Call a discovered tool via the proxy
const weather = await client.callTool("proxy_tool_call", {
  toolName: "weather_tool",
  city: "SF",
});
// Payment handled automatically — weather contains the tool response

​

Extension architecture

// Extension structure
{
  bazaar: {
    info: {
      input: {
        type: "http",
        method: "GET",
        queryParams: { ... }
      },
      output: {
        type: "json",
        example: { ... }
      }
    },
    schema: {
      // JSON Schema validating the info structure
      $schema: "https://json-schema.org/draft/2020-12/schema",
      type: "object",
      properties: { ... }
    }
  }
}

​

Key components

​

Best practices

​

For sellers

1. Provide clear examples: include realistic output.example values that demonstrate your API’s response format.
2. Document inputs: use inputSchema with descriptions to help clients understand required parameters.
3. Use appropriate types: specify correct JSON Schema types (string, number, boolean, array, object).
4. Write semantic descriptions: natural-language descriptions (e.g., "Real-time weather conditions for any city") rank higher in semantic search than bare endpoint names like /weather. Include a description field in your route config or Bazaar extension metadata.
5. Validate against the Bazaar schema: ensure your extension input strictly matches schema.properties.input, and inspect the EXTENSION-RESPONSES header on verify/settle (see Bazaar extension validation) if discovery is not picking up your route.

​

For buyers

1. Cache discovery results: don’t query discovery on every request.
2. Handle pagination: on /discovery/resources, use offset and limit for large result sets. On the CDP /discovery/search endpoint, there is no pagination—tighten query and filters instead of page-walking the catalog.
3. Validate compatibility: confirm each hit’s accepts entries match the wallet and networks you use with CDP (see Network Support).
4. Prefer search for CDP discovery at scale: use /v2/x402/discovery/search when you need relevance, filters, or quality-ranked results; use /discovery/resources when you need a traditional paginated inventory.

​

Support

• GitHub: github.com/x402-foundation/x402
• Discord: Join #x402 channel
• Documentation: x402 Overview

​

FAQ

​

How do I get listed in the Bazaar, and when does my service show up?

​

Can I opt out of discovery?

​

What networks are supported?

​

How often is the discovery catalog updated?

​

Is there a test Bazaar for development?

​

Can I list endpoints that require auth or return 200 without payment?