An AI agent does not browse a marketplace the way a person does. It reads a tool list, chooses a name, inspects a schema, checks a price and calls an endpoint. If any of those steps is missing, the API does not exist to the agent, even if the page looks good in a browser.
That is the gap between a normal API directory and an agent-ready one. The directory can be useful to a human and still be invisible to a model. The fix is not more marketing copy. It is a small set of machine-readable surfaces, each written for a different part of the agent loop.
The five surfaces that matter
| Surface | What it answers | Who reads it |
|---|---|---|
| MCP tool list | What can I do right now? | An agent connected to an MCP server |
| OpenAPI document | What are the exact routes and schemas? | A developer or an agent building a client |
| llms.txt | What is this site, and where are the important pages? | A model doing research |
| Agent card | Who operates this service, and how do I reach it? | An agent doing capability discovery |
| x402 challenge | What does this call cost, on which network, to which wallet? | An agent ready to pay |
Most teams publish one of these and assume the rest will follow. They do not. Each surface has a different job, and an agent may meet your API through any of them.
MCP is a runtime surface, not a REST wrapper
MCP is often described as "a way to expose APIs to models". That description hides the important part. MCP is a tool surface that a model chooses from at runtime. The model sees a tool name, a description and an input schema. It does not see your landing page, your pricing table or your changelog.
That changes what good documentation means. A tool description has to say when to use the tool, what it returns and what it costs. A schema has to reject bad input before the call. A tool name has to be specific enough that the model does not confuse it with a neighbouring tool.
Bad:
- Name:
lookup - Description: "Looks up data."
Better:
- Name:
verify_email_address - Description: "Check whether an email address has valid syntax, a real domain and a mail exchanger. Returns deliverable, risky or undeliverable. Costs 0.001 USDC per call on Base."
The second version gives the model a reason to choose the tool, a description of the output and the price. That is the difference between a tool that gets called and a tool that gets skipped.
OpenAPI is the contract
OpenAPI is still the best format for the exact request and response shape. It is what a developer reads when they integrate, and what an agent reads when it needs to construct a call without a tool wrapper.
Two details matter more than the rest:
- Every paid route should say it is paid. Do not hide the 402 behind a generic 200 response. Document the payment challenge, the network, the asset and the price.
- Examples should be real. A schema with an empty example forces the model to guess. A working request and response pair removes that guess.
An OpenAPI file that only describes free discovery endpoints is useful, but it is not a catalogue of the paid product. If the paid routes are external, link to them and describe the challenge.
llms.txt is the front page for a model
llms.txt is a small, plain-text map of a site. It is not a replacement for a sitemap and it is not a magic ranking file. It is a practical way to tell a model what the site is, what the important pages are and how to use them.
A useful llms.txt has:
- One sentence on what the product is.
- The discovery endpoints, with a working example URL.
- The payment model in plain language.
- A short catalogue summary: number of listings, categories, networks and price range.
- Links to the machine-readable listing pages, not only the HTML pages.
The common mistake is to paste the whole marketing site into the file. A model does not need the hero copy. It needs the route, the price and the next action.
Agent cards and security.txt are trust signals
An agent card tells another agent who operates the service, what it can do and where to find it. A security.txt tells a researcher how to report a problem. Neither will make an API go viral, but both reduce the cost of trusting an unknown provider.
The same rule applies to public receipts. A receipt that links a named route to a real settlement is more useful than a badge that says "verified". The badge is a summary. The receipt is the evidence.
The x402 challenge is part of discovery
In an x402 API, the first unpaid call is not an error. It is the price quote. The 402 response contains the scheme, network, asset, amount, payee and timeout. An agent can read that quote before it signs anything.
That makes the challenge a discovery surface. If the challenge is malformed, the agent cannot pay. If the price is hidden until after payment, the agent cannot budget. If the payee changes between the quote and the settlement, the agent cannot trust the route.
A good paid route makes the challenge boring: valid JSON, a stable payee, a readable amount and a network the agent supports.
A practical checklist
Before you announce an API to agents, check these:
- A model can find the capability from a tool name and one sentence.
- The input schema rejects missing or malformed fields.
- The price is visible before payment.
- The 402 challenge is valid and stable.
- The OpenAPI document includes the paid route or links to it.
- llms.txt names the catalogue and the discovery endpoints.
- A listing page has a canonical URL, a description and structured data.
- A public receipt or verification record exists.
- The error responses are documented.
- The service has a contact and a security.txt.
None of these is exotic. The advantage comes from doing all of them, consistently, for every route.
What APIStead does
APIStead publishes an MCP server, an OpenAPI document, llms.txt, llms-full.txt, agent HTTP endpoints, per-listing JSON and Markdown twins, and a public receipt index. Every paid route returns a real x402 challenge, and every verified route links to a settlement.
The catalogue is deliberately small. A verified route with a clear price is more useful to an agent than a thousand unverified endpoints with no evidence.
If you are building an API for agents, start with the surfaces above. Then make the first paid call easy to understand, and publish the receipt.