How an agent finds a paid endpoint: .well-known/x402.json, llms.txt and an MCP server card

#ai #x402 #agents #api

Disclosure: this article was generated by an AI system.

A paid endpoint has a discovery problem before it has a payment problem. Before any payment can happen, an agent has to find the endpoint and learn what to POST. A landing page written for humans leaves an agent guessing at routes and body shapes. A service can publish a small set of machine-readable files so the agent does not have to guess. This post walks through those files. The excerpts are a schematic example service (a paid report API at api.example.com), trimmed for length; they illustrate the shape, not a live service. Examples are schematic; support varies by client/framework and isn't guaranteed.

/.well-known/x402.json: the payment facts, machine-readable

A discovery document shape used in the x402 ecosystem. Schematic excerpt:

{"version": 2, "resources": [{
  "resource": "https://api.example.com/api/order/{order}/entity",
  "accepts": [{ "scheme": "exact", "network": "eip155:8453",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "3000000", "payTo": "0x1234...abcd", "maxTimeoutSeconds": 1800 }],
  "extensions": { "bazaar": { "info": { "input": ..., "output": ... }, "schema": ... } }
}]}

Without creating an order or paying anything, an agent reading this file learns the resource URL, the scheme, the network (eip155:8453 is Base), the asset (USDC), the amount (3000000 units), the payee, and the maxTimeoutSeconds value (1800) that the payment requirements will carry. The bazaar extension goes further: a JSON schema and an example for the input body and the output, so a crawler or planner can learn the request shape from the file itself.

/openapi.json: the whole contract, payment terms included

Standard OpenAPI 3, with one extension: x-payment-info declares the protocol (x402), network, asset, amount and payee in the same document that lists the routes. An agent that consumes OpenAPI can learn a free coverage-check route, an entity-selection step that returns 402, and the pay route from one document. A useful extra is a metadata-only demo route that answers 402 so directory crawlers can index the payment shape without ever accepting a payment.

/llms.txt: a short plain-text summary

llms.txt is a compact text file written for language-model readers: what the service offers, which pages matter, and the exact machine-use flow in a few lines:

Report API: POST /api/order {company,country} -> JSON candidates;
POST /api/order/{order}/entity {idx} -> 402 x402 requirements;
POST /api/order/{order}/pay with PAYMENT-SIGNATURE header;
GET /api/order/{order} -> status + report.
Discovery: /.well-known/x402.json, /openapi.json.

Whether a given agent's framework picks it up depends on that framework - but the file costs nothing to publish, and when it is read, five exact flow lines beat a page of marketing.

/.well-known/mcp/server-card.json: the MCP route

Agents that speak MCP get a different front door. A server card can describe a streamable-HTTP MCP server with tools for a free coverage check, order creation and result retrieval, each with a full input schema. One honest detail worth copying: if the MCP tools do not handle the payment itself, the card should say so plainly. Discovery, ordering and delivery can sit in MCP while the signature step stays a raw HTTP call with the PAYMENT-SIGNATURE header.

What to know when building a paid agent endpoint

Put a free step first. A check that costs nothing lets agents explore and fail cheap. Request payment only after the free step has run and the input is confirmed.
Make every layer self-describing. The 402 response itself should carry the amount, payee, network and timeout values the client needs to sign.
Give crawlers a demo 402. A metadata-only pay route lets directories index the payment shape without touching a real order.
Publish two front doors. Raw HTTP with OpenAPI and x402.json for general agents; an MCP card for MCP clients. Same service underneath.
Write llms.txt for the agent, not the human. Exact flow lines, not vision statements.

Honest close

None of this creates distribution on its own. The directory ecosystem for x402 services is young and reach today is small - these files simply make a service legible to whatever does come looking. If an agent finds an endpoint through one of them, that is the point.

Feedback welcome: what else would your agent need to discover before it trusts a paid endpoint?

DEV Community