Horizon Pulse
GitHubTry free
Blog

Why agent discoverability matters

Published

A paid API that no agent can find earns nothing. That sounds obvious, but it's one of the most common gaps in x402: the route works, it returns 402 Payment Required, a payment even settles, and the API still doesn't show up where agents look.

How agents find tools today

Agents rarely browse. They search catalogs and read machine-readable descriptions. Four surfaces do most of the work:

  • Coinbase's x402 Bazaar. The CDP catalog of x402 resources. Per Coinbase's docs, agents reach it through CDP APIs and the Bazaar MCP server, and people browse it on agentic.market. A route appears there only after the facilitator has seen a paid call (more below).
  • MCP registries and directories. For agents that work through the Model Context Protocol, a registry entry is how an MCP server gets found. Many of these need the server owner to submit from their own account.
  • llms.txt and skill.md. Plain-text files at a known path that tell a language model what your service does, which endpoints matter, and when to use them. An agent can read them in one fetch.
  • OpenAPI. The schema an agent uses to build a valid request. Coinbase's docs are direct about why this matters: without input schemas and examples, "agents can discover your endpoint but can't construct a valid call."

Discovery and usability are two separate problems. A catalog entry gets an agent to your door. Your description and schemas decide whether it can call you correctly the first time.

Why a paid route stays invisible

Coinbase documents the Bazaar's indexing requirements in its troubleshooting guide (My endpoint is missing from the Bazaar). An endpoint must:

  1. Be served over public HTTPS. Localhost, plain HTTP, and endpoints behind an authenticating proxy aren't indexed.
  2. Return valid Bazaar metadata on the 402.
  3. Have settled at least one payment through the CDP facilitator. On that settlement call, both paymentPayload.extensions.bazaar and paymentPayload.resource must be set.

After that, indexing can take up to 15 minutes. The guide's first recommendation is to run CDP's validation endpoint, which names the missing requirement faster than a manual checklist.

Missing one of these is common. As of 2026-10-01, 25 public GitHub issues in x402-foundation/x402 and coinbase/cdp-sdk describe a settled-but-not-indexed payment.

Coinbase's Get discovered guide adds three more things sellers miss:

  • Listings expire. "Resources that go 30 days without a settlement are removed from both the catalog and search results." A listing has to be maintained. It isn't a one-time task.
  • Descriptions have a hard limit. Keep the route description to 500 characters or fewer. The CDP facilitator rejects verify and settle requests whose description is longer. Bare endpoint names and placeholder text score zero on metadata quality.
  • Ranking is earned. Results are ordered by real usage and listing quality over a rolling 30-day window, and new endpoints rank conservatively. Resources on shared tunneling domains are weighted below those on dedicated domains.

One more practical point: if your server validates input before the x402 middleware runs, the Bazaar's asynchronous check, which sends your example input or an empty body, may never reach the 402. Make sure it does.

What we learned listing our own routes

Horizon Pulse runs a live x402 v2 service on Base mainnet: USDC through Coinbase's CDP facilitator, with 13 paid routes. As of the CDP merchant lookup on 2026-10-08, 13 routes are listed in Coinbase's x402 Bazaar. We're also listed on x402scan, and our /.well-known/x402 manifest is live. We share this as a delivery reference, not a revenue claim.

What carried over into how we deliver for others:

  • Metadata goes in the 402 itself. Our 402 responses carry serviceName, tags and an icon URL, so a catalog has something to show beyond a URL.
  • The first settle is the trigger, so plan for it. One route in our own codebase was committed and listed the same afternoon, because we ran the paid test call that triggers indexing right after the commit.
  • Verify on-chain, not just in logs. Our end-to-end paid settlements are verified on-chain, which rules out a payment problem when a route is missing.
  • Don't charge for broken data. If an upstream price feed is down, our gas, portfolio and signals routes return 503 with charged:false and settlement is skipped, so an agent never pays for a failed answer.
  • Cover more than one surface. The same service also exposes its tools over MCP at /mcp. Agents that never touch a catalog can still find you through the files and registries they do read.

Where we can help

If you'd like this done for your API, our new Agent promotion service covers listing work for the Coinbase x402 Bazaar, x402scan, MCP directories and agent catalogs. It also includes an agent-optimized description pack (llms.txt, skill.md, an OpenAPI summary, and a Bazaar description that fits Coinbase's 500-character limit) and a monthly agent-traffic report. Where a directory needs your own account, such as the MCP Registry or npm, we prepare a ready-to-submit pack and you submit it. We can't promise placement, ranking or traffic. Directories make their own decisions. Details are at horizonpulse.dev/agent-promotion. If you only need to know why an existing route isn't listed, our listing fix starts with a written review.