How to publish x402 Bazaar metadata agents can use

Minimum useful metadata

An agent needs to know what the route does, how to call it and what kind of response to expect before considering payment. Use an action-oriented description, explicit method, MIME type, input properties, required fields and one public example. Avoid promotional claims that cannot be evaluated from the response.

Common indexing failures

Services can remain absent when they use x402 v1 extension shapes, add non-standard Bazaar fields, send the extension on the wrong route or never complete an eligible settlement through the expected facilitator. Validate the exact package version and facilitator base URL against current documentation rather than copying an older example.

Make directories more accurate

Publish a canonical docs URL and a machine-readable manifest where appropriate. Keep route descriptions stable enough to deduplicate, but update price and schema changes promptly. If a route is retired, return a clear status and remove it from discovery metadata instead of leaving a permanent broken entry.

What the Bazaar indexes

The Bazaar is a discovery catalog for payable resources, not a general business directory. In x402 v2, the seller attaches the official Bazaar extension to a protected route. The metadata describes how to call that route and what it returns. The CDP Facilitator extracts the extension during payment processing and catalogs an eligible resource after settlement succeeds.

That lifecycle explains two common surprises. A well-written extension is not a separate registration form, and successful verification alone is not enough for CDP indexing. The route must use the compatible facilitator path and complete settlement with accepted metadata.

Describe the input as an executable contract

The input example must validate against the declared JSON Schema. For a GET route, describe the query parameters; for a body method, indicate the body type and schema. Mark required fields, use concrete types and include constraints that prevent obviously bad calls. A string called query is more useful when its description explains what can be searched and its maximum length.

Choose an example that is public, stable and inexpensive to execute. Do not use a private account ID, secret token or an edge case that needs undocumented setup. The example is part of the buying experience: agents and reviewers will use it to decide whether the route works as described.

• Use the exact method and input location the server accepts.
• Declare required properties and meaningful constraints.
• Make the example pass the schema without hidden fields.
• Keep sensitive and mutating values out of public examples.

Describe output so a buyer can validate value

An output example should show the real response envelope and the fields a buyer can rely on. Include types and important nullability or limit behavior in the schema. If the route returns a job identifier rather than the final result, say so and document the follow-up operation; otherwise the apparent price per result will be misleading.

Avoid examples that contain claims your service does not guarantee. A search API can show titles, URLs and snippets without promising that every result is true. An extraction API can distinguish retrieved page content from a generated summary. Precise boundaries make the resource easier for agents to select and safer for providers to maintain.

The path from declaration to searchable resource

Register the Bazaar resource-server extension, attach the discovery declaration to the route and point verification and settlement at the supported CDP Facilitator URL. Make a client call that receives the 402, submits a valid payment and completes settlement. The extension response can indicate whether metadata was accepted for processing, while indexing itself is asynchronous.

After settlement, query the paginated resources endpoint or semantic search using a distinctive phrase from the description. Search and list responses use different JSON shapes, so test the correct parser. If the route is absent, inspect extension responses and facilitator logs before repeatedly paying it.

How to diagnose a missing Bazaar listing

First confirm that the protected route actually returns 402 and includes the current v2 extension shape. Validate the example against the schema exactly; strict validation can reject a value that looks plausible to a person. Confirm the resource server registered the extension and used CDP's facilitator for both verify and settle.

Then prove that at least one settlement succeeded for that URL. A verify-only test, a settlement through a different facilitator or a zero-dollar route may not produce a CDP Bazaar entry. Finally, allow for asynchronous indexing and query by the exact merchant or a distinctive term before treating search ranking as an ingestion failure.

Maintain metadata as part of the API contract

Update the schema and examples in the same release that changes the route. Keep descriptions stable enough for buyers to recognize the capability, but do not preserve obsolete claims for search continuity. When price or accepted networks change, the live payment requirement remains authoritative and documentation should be updated promptly.

Retire old resources deliberately. Remove the extension from routes that should no longer be discovered, return a clear status and update canonical documentation. Leaving many stale variations harms buyers and can make the provider's active route harder to find in a large catalog.

Related directory entries

Sources and methodology

TOLL·402 distinguishes public claims, registry discovery, unpaid quote checks and settled paid-call verification. Sources below support the visible claims; presence in a registry is not treated as verification.

1. x402 Bazaar documentation — Authoritative indexing and extension behavior.
2. x402 seller quickstart — Current declaration examples.
3. x402 issue 2207 — Reports missing extension responses and failed Bazaar indexing after successful CDP facilitator settlements.