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

Disclosure: I build Dutiful, the service used as the example. The files below are Dutiful's own published discovery artifacts - treat them as our setup, not a specification or a guarantee that any framework supports them.

A previous post (https://dev.to/dutiful_dev/how-an-agent-pays-for-and-reads-a-company-check-over-x402-3dh3) walked through paying for an HTTP request with x402: create the order, read the 402, sign, retry. It assumed the agent already knew where to knock. 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. These are the files I publish so it does not have to guess.

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

This is the x402 discovery document. Schematic excerpt, trimmed for length - the live file is at https://dutiful.work/.well-known/x402.json:

{"version": 2, "resources": [{
  "resource": "https://dutiful.work/api/order/{order}/entity",
  "accepts": [{ "scheme": "exact", "network": "eip155:8453",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "3000000", "payTo": "0x1CD7...fA52", "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, $3.00), 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 learns the free POST /api/order coverage check, the entity step that returns 402, the pay route - and /api/pay-demo, a metadata-only route that answers 402 so directory crawlers can index the payment shape but never accepts a payment.

/llms.txt: a short plain-text summary

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

Company 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. The server card describes a streamable-HTTP MCP server with three tools - check_coverage (free), create_order and get_report - each with a full input schema. One honest detail: the MCP tools do not handle the payment itself. create_order says plainly that it "does not pay" - paying still means sending the signed payment in a PAYMENT-SIGNATURE header to the returned pay_url, then reading the result with get_report. MCP covers discovery, ordering and delivery; the signature step stays a raw HTTP call.

What I would tell someone building a paid agent endpoint

1. Put a free step first. check_coverage costs nothing, so agents can explore and fail cheap. Payment is only requested after the free coverage check has run and an entity is chosen.
2. Make every layer self-describing. The 402 response itself carries the amount, payee, network and timeout values the client needs to sign.
3. Give crawlers a demo 402. A metadata-only pay route lets directories index the payment shape without touching a real order.
4. Publish two front doors. Raw HTTP with OpenAPI and x402.json for general agents; an MCP card for MCP clients. Same service underneath.
5. 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, our directory submissions are mostly still pending or unavailable, and reach today is small - these files simply make the service legible to whatever does come looking. If an agent finds the 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? Docs and links: https://dutiful.work/developers . Sample report: https://dutiful.work/sample . Contact: [email protected].