The agent-ready API checklist

An API can be “developer-friendly” and still be hostile to an agent. Agents need determinism, clear prices, machine-readable errors and a payment contract they can read before spending.

Discovery

• A stable, public base URL.
• A free sample or health route with the same output shape as the paid route.
• An OpenAPI document, or a JSON schema per route.
• A machine-readable price and network list.
• A 402 challenge on the paid route.
• A payTo wallet that matches the listing.
• An MCP endpoint if the tool is useful at runtime.

Request and response

• JSON in, JSON out.
• No HTML error pages.
• Stable field names.
• ISO 8601 timestamps.
• Amounts in atomic units plus a human-readable string.
• example_request and example_response.
• schema_version.
• Pagination with next_cursor, has_more, total.
• 4xx for caller errors, 5xx for provider errors.
• 429 with Retry-After.

Payment

• PAYMENT-REQUIRED header with scheme, network, asset, amount, payTo, maxTimeoutSeconds.
• Base USDC support first.
• Price below a sane per-call cap.
• Settle after a successful response.
• PAYMENT-RESPONSE with the settlement result.
• A public receipt and receipt_url.
• Idempotency for paid calls.
• A clear no-refund policy and a spend-safety guide.

Trust

• A recent paid verification, not just a 402 check.
• Uptime and latency history.
• A reliability score with a timestamp.
• A stable payout wallet; changes are announced.
• Sanctions screening on the payout wallet.
• A security contact.
• A changelog and deprecation policy.

The agent’s view

Before paying, an agent should be able to answer:

1. What does this API return?
2. How much will it cost?
3. Which network and token?
4. Who receives the money?
5. Has anyone paid it successfully?
6. What happens if it fails?
7. How do I retry safely?

If any answer is missing, the agent is taking a risk it cannot price. Fix that before you add another endpoint.