x402 Bazaar (Discovery Layer) - Coinbase Developer Documentation

Our Bazaar discovery endpoints let developers and AI agents browse and search for x402-enabled services that are cataloged through the CDP Facilitator. The Bazaar indexes payable API endpoints with semantic descriptions, payment metadata, and trust signals derived from on-chain activity — a single place to find, evaluate, and integrate x402-compatible services surfaced through CDP.

What’s new: CDP’s x402 Bazaar now uses hybrid search — a combination of full-text and semantic retrieval — so your agent gets the best of both modes in a single ranked result set. Bazaar also applies a URL sub-string fallback when no results match your query text, automatically retrying against resource endpoint URLs. See CDP semantic search and how ranking works. The paginated resources list is still available for inventory-style browsing.

The Bazaar is under active development. Semantic search, quality ranking, and the MCP server interface are recent additions — expect the API surface to evolve as we incorporate feedback.

Overview

Our Bazaar endpoints address x402 service discoverability by providing:

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

In x402 v2, the Bazaar has been codified as an official extension in the reference SDK (@x402/extensions/bazaar). This extension enables:

Sellers declare discovery metadata (input/output schemas) in their route configuration.
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).
Buyers call the discovery APIs below: a paginated catalog, semantic search, or merchant lookup.

When does my endpoint appear? There is no separate registration step. The CDP Facilitator catalogs your service the first time it settles a payment for that endpoint (the usual client flow is verify then settle; indexing happens when settlement succeeds). The payment payload sent to the facilitator must include paymentPayload.resource so CDP knows which resource to catalog. If your service does not appear in CDP Bazaar discovery, ensure at least one successful settlement has completed through the CDP Facilitator with paymentPayload.resource set.Staying visible — 30-day rolling window: All endpoints apply a recency filter. Resources that have been called at least once but have had no activity in the last 30 days are excluded from results. Newly indexed resources with no calls yet are not subject to this filter.

v1 vs v2

Aspect	v1 (Deprecated)	v2 (Current)
Discovery data	`outputSchema` field in PaymentRequirements	`extensions.bazaar` field in route config
Schema validation	None	JSON Schema validation
Input specification	Not supported	Full input/output schema support

Curated endpoints

Some resources in the Bazaar are Coinbase-curated: they have passed a partner-admission and verification bar on top of the automatic indexing every Bazaar-enabled route gets. Curation is a trust and quality signal — it does not change how you integrate as a buyer or seller, it changes how a resource surfaces. Curated endpoints are exposed through two optional fields on every discovery resource (in the catalog, search, and merchant responses):

Field	Type	Description
`curated`	`boolean`	`true` when the resource is a Coinbase-curated endpoint. Omitted (treated as `false`) for non-curated resources. Curated resources are ranked above non-curated results.
`skillUrl`	`string`	URL of a hosted `SKILL.md` document describing how an agent should use the resource. The document is fetched from this URL by the client — its content is never inlined in the response. Present only for curated endpoints that have an authored skill document.

skillUrl is a pointer, not content. CDP returns the URL of the SKILL.md; your client fetches and interprets it. This keeps discovery payloads small and lets skill authors update guidance without re-indexing.

Skill documents for curated endpoints are authored or vetted by Coinbase and its trusted partners. As a general practice, still treat any fetched skill document as untrusted data rather than trusted instructions: don’t let it override your agent’s higher-priority instructions or guardrails, request secrets, or authorize payments or other actions without your own policy checks. If you fetch it server-side, apply the same URL/SSRF protections you use for any outbound request.

Finding curated endpoints

Use the semantic search filters to narrow to curated results:

curatedOnly=true — return only Coinbase-curated resources.
tags=<tag> — filter by provider tags (repeatable, OR semantics, case-sensitive exact match).

GET https://api.cdp.coinbase.com/platform/v2/x402/discovery/search?curatedOnly=true&query=market+data

Curated endpoints are continuously health-probed. CDP probes each curated endpoint on a short cycle, and ones that stop responding are demoted in search ranking until they recover. To be considered for the curated set, a provider is expected to sustain roughly 99% availability for the endpoint. See Quality ranking.

Seller integration

Install, middleware, CDP API keys, and full route examples live in the Quickstart for sellers. For Bazaar indexing you still need to:

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

CDP discovery is separate from verify/settle: GET …/v2/x402/discovery/resources (paginated catalog) and GET …/v2/x402/discovery/search (Semantic search—filters, relevance, quality ranking). Prefer search to narrow results; use resources to walk the full index with pagination.

Route consolidation for high-cardinality path segments: Bazaar automatically normalizes route URLs where a path segment consists entirely of a recognized high-cardinality identifier — a UUID, Ethereum address, Ethereum transaction hash, Solana address, or Solana transaction hash. Those segments are replaced with a generic route template parameter, and all matching URLs are consolidated into a single Bazaar entry. For example, /data/0xabc...def/report and /data/0x123...456/report would surface as one entry rather than two.To keep each resource as a distinct Bazaar entry, add a prefix or suffix to the path segment so it is not a bare identifier — for example, /user-<uuid> or /<uuid>-report instead of /<uuid>.

Discovery extension options

The declareDiscoveryExtension function accepts configuration for different HTTP methods:

// 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

For a route to be discoverable, the Bazaar extension input must pass strict JSON Schema validation against schema.properties.input in your declared extension (see the extension shape below). In addition to this, the settle request must contain paymentPayload.resource. Without this, the Bazaar has no way to associate the discovery metadata with a resource. The CDP Facilitator includes an EXTENSION-RESPONSES header on verify and settle responses so your resource server can tell whether Bazaar metadata was accepted. If validation fails, the resource server will see a rejected status for the Bazaar extension; otherwise you will typically see processing (discovery indexing is asynchronous, so this does not yet confirm the resource appears in search).

Before you go live, use the validate endpoint (POST /v2/x402/validate) to probe your URL and confirm it returns 402, advertises a parseable extensions.bazaar block, and would be accepted for indexing — without running a real payment.

Buyer integration

Use the Quickstart for buyers for guides on installation, endpoint discovery, and paying with x402. Semantic search (GET …/v2/x402/discovery/search), filters, ranking, and example URLs are on this page under Semantic search. Paginated discovery returns items; search returns resources — the JSON shapes differ.

CDP discovery endpoints (HTTP)

This section documents the CDP Bazaar discovery endpoints (https://api.cdp.coinbase.com/.../v2/x402/discovery/...): paths, query parameters, and example payloads. The catalog (/discovery/resources) and semantic search (/discovery/search) routes are documented on this page only — there are no matching OpenAPI operation pages under the x402 Facilitator API Reference. The merchant discovery route does appear there as Get merchant resources by payTo address.

Auth: these GET …/discovery/* routes are read-only catalog APIs and do not require CDP API keys. You still need CDP API keys on your resource server to run verify/settle through the CDP Facilitator (see Quickstart for sellers).

CDP Facilitator discovery endpoint

Paginated catalog of x402-enabled HTTP resources. Results are returned in browse order (newest first). Use this endpoint when you want to page through the full index (items + pagination). For relevance-ranked results and filters, use semantic search instead.

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

The default limit is 100 results per request. Limits are rounded to the nearest 10 and clamped to a minimum of 20; the hard maximum is 1000. Offsets that are not a multiple of the rounded limit are snapped down to the nearest valid multiple. Results are served from a cache — expect new and updated resources to take up to 10 minutes to be reflected.

Query parameters

Parameter	Type	Description
`type`	string	Filter by protocol type (e.g. `"http"`).
`limit`	number	Page size. Default 100; rounded to the nearest 10, minimum 20, maximum 1000.
`offset`	number	Pagination offset. Default `0`. Snapped down to the nearest multiple of the rounded limit.

Response body (`200 OK`)

Example `200` JSON (paginated catalog)

{
  "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": 100,
    "offset": 0,
    "total": 42
  }
}

`items[]` fields

Field	Type	Required	Description
`resource`	`string`	Yes	Monetized resource URL.
`type`	`string`	Yes	Resource type (currently `"http"`).
`x402Version`	`number`	Yes	x402 protocol version the resource supports.
`accepts`	`array`	Yes	Accepted payment requirements for this resource.
`lastUpdated`	`string`	Yes	ISO 8601 timestamp of the last catalog update for this entry.
`metadata`	`object`	No	Optional description and Bazaar input/output metadata.
`curated`	`boolean`	No	`true` for Coinbase-curated endpoints; omitted otherwise.
`skillUrl`	`string`	No	URL of the resource’s hosted `SKILL.md`, present only for curated endpoints that have one. See Curated endpoints.

CDP Bazaar: Semantic search

The CDP Facilitator exposes a dedicated endpoint for free-text and structured search over the same CDP-indexed catalog as the paginated resources route (results stay in sync). Result order blends search relevance with service quality; see Quality ranking. No API key is required. Unlike GET .../discovery/resources, this endpoint is optimized for search and filter, not for walking the full catalog: there is no cursor or offset pagination. Refine your query and filters (and use limit, capped at 20) to narrow results. The response includes partialResults when the matching set is larger than your limit and the service truncates to fit.

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

Quality ranking

CDP orders semantic search results using three kinds of signal:

Retrieval relevance — how well the service matches your query and filters, using the mode indicated by searchMethod in the response (for example hybrid, semantic vector, or full-text text). CDP uses hybrid search by default, combining text and semantic retrieval into a single ranked result.
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) within the last 30 days
- Transaction volume — how many transactions (successful payments) the resource has processed within the last 30 days
- 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). Low-effort or generic descriptions (for example, bare endpoint names or placeholder text) score 0 on this dimension, so a natural-language description materially improves ranking.
- Hosting — resources on shared/tunneling hosting platforms (for example, ngrok.io / ngrok-free.app) are de-weighted relative to resources on dedicated domains, and domain concentration is penalized so a single domain cannot flood results.
Curation — Coinbase-curated endpoints (curated: true) receive a ranking bump above non-curated results. Curated endpoints are continuously health-probed, and ones that stop responding are demoted until they recover.

These signals are objective (derived from traffic through CDP, declared metadata, and liveness checks), not manual editorial ratings. The response does not include per-service quality signal breakdowns, only the final ordering. Ranking weights and formulas may change as CDP tunes discovery.

Quality metrics (buyer reach, transaction volume, recency) are recomputed on a 6-hour schedule. A newly settled payment will not immediately affect a service’s ranking — expect ranking changes to take up to 6 hours to be reflected in search results.

Query parameters

Parameter	Type	Required	Description
`query`	string	No	Free-text semantic search. Max 400 characters. If omitted, the call behaves like a filter-only listing (still subject to `limit` and ranking).
`network`	string	No	CAIP-2 network id (e.g. `eip155:8453`). Legacy x402 v1 SDK names such as `base` and `base-sepolia` are also accepted. Max 200 characters.
`asset`	string	No	Asset filter (e.g. `usdc`). Case-insensitive. Max 200 characters.
`scheme`	string	No	Payment scheme filter (e.g. `exact`, `upto`). Max 200 characters.
`payTo`	string	No	Filter by recipient address. Max 200 characters.
`maxUsdPrice`	string	No	Maximum price in USD; must parse as a float. Max 200 characters.
`extensions`	array of strings	No	Match resources that advertise a given x402 extension (e.g. `custom`). Repeat the query key for multiple values: `?extensions=custom&extensions=...`
`tags`	array of strings	No	Filter to resources published with any of the specified provider tags (case-sensitive exact match). Repeat the query key for multiple values; a resource matches if it carries at least one of the supplied tags (OR).
`curatedOnly`	boolean	No	When `true`, restrict results to Coinbase-curated resources (those with `curated: true`). When `false` or omitted, both curated and non-curated resources are returned.
`limit`	integer	No	Max results to return. Must be ≥ 1. Hard cap: 20.

Response (`200 OK`)

Example `200` JSON (semantic search)

{
  "resources": [
    {
      "resource": "https://example.com/api/endpoint",
      "type": "http",
      "x402Version": 2,
      "description": "Optional description of the resource",
      "lastUpdated": "2025-01-01T00:00:00Z",
      "curated": true,
      "skillUrl": "https://skills.cdp.coinbase.com/example-api/SKILL.md",
      "accepts": []
    }
  ],
  "partialResults": false,
  "searchMethod": "hybrid",
  "x402Version": 2
}

Example query URLs

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
GET https://api.cdp.coinbase.com/platform/v2/x402/discovery/search?curatedOnly=true&query=market+data
GET https://api.cdp.coinbase.com/platform/v2/x402/discovery/search?tags=defi&tags=trading

Field	Type	Description
`resources`	array	Rows matching the query and filters, ordered by CDP using relevance + quality ranking.
`partialResults`	boolean	`true` if additional matches existed but were truncated to satisfy `limit`.
`searchMethod`	string	How CDP satisfied the query: `hybrid` (default, combining text and semantic search), `vector` (semantic only), or `text` (full-text only, including when semantic search is unavailable). This reflects Bazaar-side configuration and is not a request parameter. When the primary search returns zero results for a text query, CDP automatically retries using your query as a URL sub-string filter against resource endpoint URLs — this fallback does not change the reported `searchMethod`.
`x402Version`	number	Discovery payload version.

Each element of resources includes the resource URL, type, x402Version, optional description, lastUpdated, and accepts entries in the same payment requirement shape as the paginated catalog. Coinbase-curated endpoints additionally carry curated: true and, when a skill document is available, a skillUrl.

Merchant discovery endpoint

Within CDP’s catalog, look up active resources for a given merchant payTo address (EVM or Solana as documented). Endpoint:

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

This endpoint is publicly accessible — no API key is required. It is useful for buyers and AI agents that want to discover resources payable to a specific wallet.

Query parameters

Parameter	Type	Required	Description
`payTo`	string	Yes	The merchant’s wallet address (EVM 0x-prefix or Solana base58)
`limit`	integer	No	Number of resources to return (default: 25, max: 100)
`offset`	integer	No	Number of resources to skip for pagination (default: 0)

Response schema

Example `200` JSON (merchant)

{
  "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
  }
}

The endpoint returns 200 OK with an empty resources list if no active resources are found for the given address, and 400 if the payTo parameter is missing or invalid. For OpenAPI schemas and status codes for this route, see Get merchant resources by payTo address in the x402 Facilitator section of the API Reference.

Bazaar MCP Server

The Bazaar exposes a Model Context Protocol (MCP) server that lets AI agents discover and call paid endpoints. On the client side, the @x402/mcp package wraps a standard MCP client with automatic payment handling — the agent never touches wallets or signing directly.

How the MCP server works

The Bazaar MCP server exposes three tools. The @x402/mcp client wraps callTool() with a payment loop so payment is transparent to the agent:

search_resources — Semantic search across the Bazaar index. Returns matching resource descriptions, pricing, input/output schemas, and relevance-ordered results. Supports the same filters as the semantic search endpoint, including curatedOnly and tags for narrowing to curated endpoints.
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.
validate_endpoint — Run the same endpoint diagnostics as POST /v2/x402/validate from inside an MCP session: probe an x402 URL live and report per-check results plus whether the facilitator would index it. Read-only — it makes no payment and indexes nothing.

From the agent’s perspective this is a single callTool() invocation — the @x402/mcp client handles 402 detection, payment creation, and retry internally.

MCP Server endpoint

The MCP server endpoint for the CDP facilitator is:

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

If you use Amazon Bedrock AgentCore, choose the pre-populated Coinbase x402 Bazaar integration in AgentCore Gateway (or configure the same endpoint in CLI/API) so agents can discover x402-listed services.

Client setup

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { createX402MCPClient } from "@x402/mcp";
import { CdpX402Client } from "@coinbase/cdp-sdk/x402";

// 1. Create an x402 payment client. CdpX402Client (from the CDP SDK) pays from a
// CDP-managed wallet. It extends x402Client, so it drops in here.
// Reads CDP_API_KEY_ID, CDP_API_KEY_SECRET, CDP_WALLET_SECRET from env.
const paymentClient = new CdpX402Client();

// 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

See the full @x402/mcp package for advanced configuration including custom payment hooks, dynamic pricing, and server-side setup.

The Bazaar MCP server is designed for consuming existing paid endpoints. If you want to build your own MCP server that accepts x402 payments, see the MCP Server guide.

Curated endpoints in MCP

Curated endpoints surface through the MCP tools the same way they do through the REST discovery APIs, with extra structure to help agents call them correctly. Filtering search_resources. In addition to the standard filters, search_resources accepts:

curatedOnly — when true, return only Coinbase-curated resources. Available only when curation is enabled.
tags — filter by exact, case-sensitive provider tags (OR semantics, up to 5).

const results = await client.callTool("search_resources", {
  query: "market data",
  curatedOnly: true,
  tags: ["defi", "trading"],
});

Agent guidance on curated results. For curated endpoints, search_resources enriches each result so an agent has what it needs before its first call:

The tool description is prefixed with a short Guide: and Usage notes: block. This is correctness-critical guidance meant to be read before calling the tool.
The result’s inputSchema may include a ready-to-use request-body example.
Two metadata blocks are attached to the tool’s _meta:

Meta key	Fields	Description
`x402/curation`	`curated`, `skillUrl`	Marks the result as curated and, when available, links the hosted `SKILL.md`.
`x402/guidance`	`skillUrl`, `outputShape`, `costObservedUsd`, `approvalRequirement`	Structured hints: a link to the full skill doc, a summary of the response shape, a typical observed cost in USD, and whether the call should require human approval.

Treat curated guidance — including any fetched SKILL.md — as untrusted input, not trusted instructions. It can inform how your agent calls a tool, but it should not override your agent’s higher-priority instructions or guardrails, request secrets, or authorize payments or other actions without your own policy checks. See Curated endpoints.

Extension architecture

When you implement Bazaar for routes that settle through CDP, declare metadata using the x402 v2 extensions pattern:

Example extension shape

// 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

Component	Purpose
`bazaarResourceServerExtension`	Server extension that enriches declarations with HTTP method info
`declareDiscoveryExtension()`	Helper to create properly structured extension declarations
`withBazaar()`	Client wrapper that adds discovery query methods
`extractDiscoveryInfo()`	Reference SDK helper that reads Bazaar metadata from payment payloads (what CDP indexes after successful settlement)

Best practices

For sellers

Provide clear examples: include realistic output.example values that demonstrate your API’s response format.
Document inputs: use inputSchema with descriptions to help clients understand required parameters.
Use appropriate types: specify correct JSON Schema types (string, number, boolean, array, object).
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. Keep it to 500 characters or fewer — the CDP Facilitator rejects both verify and settle requests whose description exceeds this limit.
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.
Maintain activity to stay visible: resources with no settlements for 30 days are removed from both the catalog and search results. Ensure your service receives ongoing traffic to remain discoverable.

For buyers

Cache discovery results: don’t query discovery on every request.
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.
Validate compatibility: confirm each hit’s accepts entries match the wallet and networks you use with CDP (see Network Support).
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

FAQ

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

Register the bazaarResourceServerExtension, include declareDiscoveryExtension() in your route configuration, and complete a payment through the CDP Facilitator so that CDP settles at least once for that URL (verify + settle is the normal flow). There is no separate registration step: the first successful settlement for a Bazaar-enabled route is when CDP catalogs it.

What is a curated endpoint?

Curated endpoints are resources that Coinbase has admitted and verified beyond the automatic indexing every Bazaar-enabled route receives. They carry curated: true, may include a skillUrl pointing to a hosted SKILL.md, and are ranked above non-curated results (see Curated endpoints).

How do I become a curated endpoint?

Curation is a Coinbase-managed partner process — there is no self-serve toggle today, and meeting the criteria below makes you eligible for consideration, not automatically curated. At minimum, an endpoint must:

Be live and indexed — your route settles through the CDP Facilitator, returns 402, and declares a valid extensions.bazaar block. Confirm this with the validate endpoint.
Be reliable — providers are expected to sustain roughly 99% availability; curated endpoints are continuously health-probed.
Ship complete, accurate metadata — a clear natural-language description, input/output schemas, and realistic examples. A hosted SKILL.md is recommended for agent consumers.

Meeting this bar is necessary but not sufficient; Coinbase weighs additional quality and trust signals when selecting the curated set. To start the process, reach out on Discord.

How do I check my endpoint is set up correctly before going live?

Use the validate endpoint (POST /v2/x402/validate). It probes your URL live and reports whether it is reachable, returns 402, advertises a parseable extensions.bazaar block, and would be accepted for indexing — without running a payment.

Can I opt out of discovery?

Yes; omit the Bazaar extension from a route’s configuration. Only routes that declare Bazaar metadata can appear in CDP discovery.

What networks are supported?

CDP discovery surfaces whatever networks your indexed resources advertise in accepts. For which chains the CDP Facilitator can verify and settle on, see Network Support.

How often is the discovery catalog updated?

CDP updates catalog entries as it processes new settle traffic for Bazaar-enabled routes. Quality metrics (buyer reach, transaction volume, recency) are recomputed on a 6-hour schedule, so a newly settled payment will not immediately affect ranking. If your service does not appear to move up in search results right away, this is expected — allow up to 6 hours for quality signal changes to take effect.

Is there a test Bazaar for development?

Yes. Use the CDP Facilitator on Base Sepolia or Solana Devnet with CDP API keys—the same …/v2/x402/discovery/... endpoints will surface services once verify/settle has run through CDP (see Network Support). If you need a no-signup testnet facilitator, the x402.org facilitator exposes its own separate catalog at https://x402.org/facilitator/discovery/resources; that index is not the CDP Bazaar.

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

Today, CDP indexes routes that return 402 and complete settle through CDP. Endpoints that need pre-auth, return 200 without payment, or use $0 “discovery-only” flows may not be cataloged. Support for these patterns is under consideration.

What does `searchMethod: "hybrid"` mean in the search response?

CDP Bazaar combines text and semantic search by default and reports "hybrid" in searchMethod. "vector" is returned when semantic search runs alone; "text" is returned when only full-text search runs (for example, when semantic search is unavailable). This field is not a request parameter — it reflects how CDP satisfied your query.

Why does a search for a domain name return results even when nothing matches the description?

CDP applies a URL substring fallback when the primary search returns zero results for a text query. If your query (for example, "agents.alchemy.com") matches a resource’s endpoint URL but not any indexed descriptions, CDP retries using the query as a URL substring filter and includes those resources in the response. The searchMethod field still reflects the primary mode; the fallback is transparent to callers.

​Overview

​Access modes

​How it works

​v1 vs v2

​Curated endpoints

​Finding curated endpoints

​Seller integration

​Discovery extension options

​Bazaar extension validation

​Buyer integration

​CDP discovery endpoints (HTTP)

​CDP Facilitator discovery endpoint

​Query parameters

​Response body (200 OK)

​items[] fields

​CDP Bazaar: Semantic search

​Quality ranking

​Query parameters

​Response (200 OK)

​Merchant discovery endpoint

​Query parameters

​Response schema

​Bazaar MCP Server

​How the MCP server works

​MCP Server endpoint

​Client setup

​Curated endpoints in MCP

​Extension architecture

​Key components

​Best practices

​For sellers

​For buyers

​Support

​FAQ

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

​What is a curated endpoint?

​How do I become a curated endpoint?

​How do I check my endpoint is set up correctly before going live?

​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?

​What does searchMethod: "hybrid" mean in the search response?

​Why does a search for a domain name return results even when nothing matches the description?

Overview

Access modes

How it works

v1 vs v2

Curated endpoints

Finding curated endpoints

Seller integration

Discovery extension options

Bazaar extension validation

Buyer integration

CDP discovery endpoints (HTTP)

CDP Facilitator discovery endpoint

Query parameters

Response body (`200 OK`)

`items[]` fields

CDP Bazaar: Semantic search

Quality ranking

Query parameters

Response (`200 OK`)

Merchant discovery endpoint

Query parameters

Response schema

Bazaar MCP Server

How the MCP server works

MCP Server endpoint

Client setup

Curated endpoints in MCP

Extension architecture

Key components

Best practices

For sellers

For buyers

Support

FAQ

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

What is a curated endpoint?

How do I become a curated endpoint?

How do I check my endpoint is set up correctly before going live?

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?

What does `searchMethod: "hybrid"` mean in the search response?

Why does a search for a domain name return results even when nothing matches the description?