← All guides · Selling to AI agents

How Do AI Agents Discover Paid APIs? A Guide to Every Surface

Part 10 of Selling to AI agents · 1,576 words · published 2026-08-04 · updated 2026-08-04 · Markdown variant

How an AI agent finds out a paid API or resource exists before it ever reads a price: llms.txt, the JSON API index, MCP registries, incidental 402 discovery, x402 auto-listing, and what .well-known does and does not cover.

Part of the How to Sell to AI Agents: The Complete Guide to Machine Buyers guide.

The pillar names four discovery surfaces in one section — your own site's entry points, an MCP server, marketplaces, and the rail that lists you automatically. This is the deep dive on that stage of selling to AI agents: not the pricing an agent reads once it has found you, but the mechanics of it finding out you exist at all, and the honest limits of each surface as of August 2026.

Proactive vs. reactive discovery

Proactive discovery is an agent specifically shopping for a capability — it has a task, knows it needs an API or a dataset, and is resolving candidates before committing to any of them. Reactive discovery is an agent stumbling into a paid surface mid-task with no prior intent to shop: it follows a link or calls an endpoint named in a doc it was already reading, and only learns a paid surface exists when it hits the wall. These are different design problems. Proactive discovery rewards being indexed somewhere an agent already resolves candidates from — llms.txt, a JSON directory, an MCP registry. Reactive discovery rewards the wall itself being self-sufficient, since there was no earlier fetch to supply context — which is what makes the HTTP 402 response, covered below, a discovery surface in its own right, not just a payment gate.

Your own site's entry points: llms.txt and the JSON API index

The cheapest, most controllable discovery surface is the one you serve yourself. /llms.txt, proposed by Jeremy Howard (Answer.AI) on 3 September 2024, is a plain-Markdown file at the site root — an H1 title, an optional summary, and H2 link-list sections an agent fetches first and follows selectively (full format in the llms.txt convention explained). The commercial rule that matters here: the index itself, and anything it links to that a buyer needs to evaluate an offer, has to be free and reachable in that first hop — an agent that cannot read your terms without paying to find them cannot decide to pay at all.

The JSON side follows the same discover-the-index-then-fetch-the-item pattern, one level more structured. GET /api/resources.json (or an equivalent corpus index) returns every item's slug, title, description, tags, and variant URLs with no body content — an agent fetches that once, then fetches /api/resources/<slug>.json only for the items it actually needs, rather than crawling HTML to reconstruct a catalog. The same pattern extends to an /api/openapi.json spec for a typed client (full shapes in JSON API for agents). Neither surface says anything about price beyond that a paid item exists — the fields that let an agent compare and act on an offer are a separate concern covered in machine-readable pricing pages. Discovery's job stops at "this is reachable and this is what it is called."

MCP registry listing and community aggregators

For a tool-calling agent, an MCP server puts a catalog directly into its available-actions list — no crawling, no parsing, no guessing which slug maps to which capability. MCP's discovery mechanics are less settled than llms.txt's, though: the official MCP Registry (registry.modelcontextprotocol.io) launched in preview in September 2025 and was still in preview as of mid-2026, not yet the single canonical index a search engine is for its own ecosystem (details in finding and evaluating MCP servers). Beyond the registry, servers also reach agents through client-vendor marketplaces and community aggregators — PulseMCP, Smithery, Glama, and MCP.so among the larger ones as of 2026 — which vary in review rigor and are leads to evaluate, not endorsements to trust outright.

Publishing an MCP server is therefore registry submission via the mcp-publisher CLI, plus whatever aggregators and client marketplaces happen to pick it up — not a single "get listed" action. That is not a reason to skip it: a paid tool exposed this way is installed, a stronger placement than a link an agent has to choose to follow. It is a reason not to treat MCP listing as a complete strategy on its own.

The HTTP 402 itself as an incidental discovery signal

A 402 response is not only a payment gate — it is the moment an agent that was not shopping learns a paid surface exists at all. An agent calling an endpoint for an unrelated reason gets 402 Payment Required back instead of the resource, and everything it now knows has to come from that one response, since there was no prior index fetch. ChangeGamer's own 402 contract returns error, resource, price_usd, payment_url, how_to_pay, terms, license, pricing_catalog, and a preview object (title, description, section outline) in one JSON response, with Link headers to the payment, license and pricing resources (documented in paying for access: the HTTP 402 flow). An agent with zero prior context can still decide from that one document — self-sufficiency is what reactive discovery demands, distinct from what a proactive index has to do, which is being findable in the first place. A strong llms.txt/JSON index reduces how often an agent hits a 402 cold, but never eliminates it: plenty of traffic follows links it found elsewhere, not your index.

x402's auto-listing rail: the first sale as the listing event

x402 has a distribution property none of the above have: it lists a seller automatically, with no submission step. Coinbase's developer platform runs the x402 Bazaar, a discovery layer indexing payable endpoints via a paginated catalog (GET …/v2/x402/discovery/resources) and hybrid full-text-plus-semantic search. Sellers do not register anywhere; the CDP facilitator auto-catalogs an endpoint the first time it settles a payment for it (grounded in agentic payment protocols and agent wallets and x402). A seller's first successful x402 sale is thus simultaneously its listing event — an inversion of the usual marketing-precedes-revenue order. An endpoint that has never settled a payment is invisible on this surface regardless of how well documented it is; the Bazaar indexes proven payment activity, not published intent. This surface is also contingent on actually running x402 — a wallet, a signing library, a facilitator relationship — so it is a multiplier once running, not a starting point for a seller with no payment rails yet.

What .well-known does — and does not — cover

Worth stating precisely, since it is easy to over-assume from adjacent conventions: there is no established .well-known convention for pricing or offer discovery. The .well-known conventions that do exist in the verified record are identity and authorization surfaces. A2A defines a self-published Agent Card at /.well-known/agent-card.json — identity discovery for one agent calling another, not a seller advertising a price (compared in full in MCP vs A2A). MCP's OAuth 2.1 flow uses two .well-known fetches in sequence: /.well-known/oauth-protected-resource (RFC 9728 — which authorization servers are trusted) then /.well-known/oauth-authorization-server (RFC 8414 — the authorization_endpoint, token_endpoint, registration_endpoint) at the server the first document names (full flow in MCP server authentication). Both establish who is calling and how to authenticate, resolved before a protected-resource request is even attempted — neither is a mechanism to learn what something costs.

If a seller wants a stable, predictable pricing path, the pattern this cluster documents — a JSON offer catalog at a fixed path such as /api/pricing.json, linked from the llms.txt index and the 402 body's pricing_catalog field — achieves that without relying on a convention that does not yet exist for this purpose. Do not build against an assumed .well-known/pricing path; nothing in the verified corpus confirms agents check one.

Two edge cases worth a direct answer

An agent with a fixed, single-fetch discovery budget should spend it on /llms.txt or a JSON index, not an MCP connection attempt. That is a cost argument, not a preference: an index fetch is one unauthenticated GET with no handshake, and a well-formed response can itself point onward to an MCP server or a pricing catalog — it is not a dead end even as the only fetch spent. An MCP connection is a protocol handshake, and for a remote server usually an OAuth negotiation, before the agent has learned anything at all — a poor first move on a one-request budget, even though it is the stronger surface once a session is already open.

A seller with neither an MCP server nor any x402 history is still discoverable, just through a narrower funnel. /llms.txt plus a JSON index reach every agent that crawls, fetches pages directly, or is pointed at the domain by a citation — a real, often majority, share of agent traffic in 2026, not a fallback for sellers who have not "graduated" to MCP or x402. What that seller misses is tool-calling agents that only resolve capabilities via an installed MCP connector, and x402-native agents shopping the Bazaar directly. The llms.txt/JSON-only path is weaker, not invalid, and the cheapest surface to stand up first.

Sequencing discovery against the rest of the funnel

Discovery only answers one question — does this paid thing exist, and where — before handing off to evaluation, a different job with a different field shape, covered in machine-readable pricing pages. If evaluation ends in a purchase, the credential the buyer receives is a separate concern again, covered in issuing API keys to AI agents. In order of cost to build: llms.txt and a JSON index first (cheapest, broadest reach, no external dependency), an MCP server second (stronger placement, narrower reach, dependent on a registry ecosystem still maturing), and x402 activity last (strongest automatic distribution, but contingent on payment infrastructure existing and being used before the Bazaar lists anything).

#discovery #llms.txt #mcp #x402 #agents #json-api