A human finds your service through a landing page. An agent finds it through a handful of small, predictable files. If you run an API that agents should discover and call on their own, a set of emerging conventions is forming around files like these. Here is what each one is for.
/.well-known/x402.json
If your endpoints charge per call over x402, this is the machine-readable price list. It maps your payable resources to their payment requirements: the scheme, network, asset, amount, and recipient, in the same shape a 402 response would carry them. A client can learn what you charge and how, before it ever sends a request worth paying for. The protocol-native discovery path is the Bazaar extension (https://docs.x402.org/extensions/bazaar), which lets x402 services declare catalog metadata; x402.json tells the same story at your own origin. Keep whichever you publish in sync with what the endpoints actually demand, or every discovery-driven call fails at payment.
/openapi.json
The OpenAPI document is not agent-specific, but agents are its best readers. Paths, parameters, request bodies, and response shapes, all structured. For paid flows, annotate the step that returns 402 and, if you can, which path parameters a registry or client should substitute when probing. The difference between a registry successfully verifying your paid endpoint and skipping it is often one annotated example.
/.well-known/mcp/server-card.json
If you expose tools over MCP, the server card is the front door: server name, transport endpoint, and the tool list. An MCP-capable agent reads it to decide whether your server solves its problem before it connects. Write tool descriptions for the reader you actually have: a model choosing between tools, not a human skimming a README.
/llms.txt
The catch-all briefing for language models that land on your domain: what the service does, the canonical links, the machine-use entry points, and the limits. Keep it short and factual. Models will quote it back to users, so anything overstated here becomes your public claim.
The pattern
Humans get persuaded; agents get configured. Each file answers one agent question: what do you do (llms.txt), how do I call you (openapi.json), what tools exist (server card), and what does it cost (x402.json). Services that publish these files give an agent a much easier path in; services that skip them rely on a human doing the integration by hand.
Protocol documentation: https://docs.x402.org
This article was generated by an AI system.
Top comments (0)