Skip to main content
By the end of this page your listing is legible to an agent that has never seen your API, and you know precisely what the facilitator records at verify, what it records at settlement, and why a good parameter description is what wins a search. This uses describeEndpoint from @rail402.dev/sdk (also exported from @rail402.dev/seller-helpers).
describeEndpoint only declares metadata. It does not register your endpoint, it does not gate payment, and it does not itself catalog anything. Payment is gated by the @x402 paywall middleware, and cataloging happens on the facilitator when a payment settles. describeEndpoint is the description the catalog reads once a payment carries it.

​
What an agent sees

An agent choosing between your endpoint and someone else’s has nothing but your text, and search ranks on that same text. A parameter named q with no description is invisible in search and unusable by an agent, because the agent cannot tell what to put in it. So the description is the product. Compare:
The second wins a search like “what is the price of gold” even though your endpoint’s own description shares no literal word with the query. That match comes from the parameter description, so write each one for a reader who has never seen your API.

​
describeEndpoint params

Pass one entry per parameter under params. Each entry carries a description and optional hints an agent uses to build a valid call.
The resource-level description is a separate field on the paywall route, not part of describeEndpoint. describeEndpoint describes the parameters; the route’s own description describes the endpoint. Both are indexed. See the Seller quickstart for where the resource description goes.

​
What the facilitator catalogs, and when

Cataloging is automatic and settlement-gated. There is no separate registration call. A resource enters the catalog because a payment carrying its discovery metadata settles. The flow is hybrid, in two stages:
1

At verify: a provisional listing

When a well-formed payment reaches /verify, the facilitator writes a provisional listing. It is discoverable, but it carries no ranking signals, has no owner, and is pruned after a short time-to-live. This is why a resource can appear during payment verification, as the upstream reference facilitators expect. A free /verify can never lock out or spoof a real seller, because a provisional listing is always displaceable.
2

At settle: a confirmed, owned listing

When the payment settles, the listing is confirmed. Settlement is the only thing that earns ownership and ranking. The owner is the payTo that settled the payment, which is what stops anyone from rewriting your listing after the fact.
Because ownership and ranking cost a real settled payment, the catalog resists spam without any moderation queue. See Bazaar for the trust model and Search for how ranking works.

​
Confirm your listing landed

The facilitator reports the cataloging outcome in the EXTENSION-RESPONSES header on its /verify and /settle responses. The value is base64-encoded JSON.
processing means the provisional listing is recorded. success means it is cataloged and owned. rejected carries a non-null rejectedReason you can read and a machine code you can branch on. You can also confirm from the outside once the payment settles:

​
How the catalog stays honest

Clients echo the resource block into the payment payload, so the facilitator treats every listing as untrusted input. You get these protections for free:
  • Ranking grows with distinct real payers, not with self-payments, so paying your own endpoint earns no ranking signal.
  • The asset identity on your listing is derived by the facilitator from the on-chain contract, not taken from the client, so a token cannot claim to be USDC when it is not.
  • A route template is percent-decoded before it is checked for path traversal, so a crafted template cannot escape its origin.

​
Check your own account first

Before a stranger’s payment fails on a missing trustline, run preflight against your payTo at boot. It returns coded findings for the problems that stop a payment landing. See Preflight and testing.

​
Next steps

Charge for an MCP tool

List an MCP tool as a first-class Bazaar resource with describeTool.

Preflight and testing

Catch a missing trustline or bad payTo before it costs a buyer a failed payment.

How search ranks

See why the description is the product and how BM25 plus embeddings rank it.

Bazaar trust model

Understand settlement-gated ownership and why the catalog resists spam.

​
When it fails

A rejected listing tells you why. The rejections you are most likely to see are bazaar_stellar_fees_not_sponsored (your exact listing must carry extra.areFeesSponsored: true) and bazaar_info_schema_validation_failed (your example values do not match your declared parameters). Every code and its reason is in Errors.