How AI agents pay for APIs with x402
A direct, current explanation of the unpaid request, payment requirements, signer, retry and settlement response.
DIRECT ANSWER
An AI agent calls an x402-protected API without payment. The server returns HTTP 402 with machine-readable requirements. An x402-aware client checks the price and network against policy, signs an authorization with the agent's wallet, retries with a payment signature, and receives the result after the server verifies and settles the payment.
Key takeaways
- The agent still needs an x402-aware HTTP client; a wallet alone does not handle the protocol.
- The first unpaid response is the policy checkpoint for amount, asset, network and destination.
- Payment success and useful output should be logged separately.
The five-step buyer loop
The core flow is request, requirements, policy decision, signed retry and result. The server may use a facilitator to verify and settle, but the buyer does not grant the facilitator arbitrary wallet access. The signed payload should authorize only the payment described by the selected requirement.
- Request the resource without a payment signature.
- Parse the PAYMENT-REQUIRED header or supported response body.
- Reject requirements outside the agent's policy.
- Sign the supported payment scheme and retry.
- Store the response and settlement evidence.
What the agent must know
A useful tool description includes the endpoint, method, input schema and expected output. Payment metadata does not explain whether a tool is safe or relevant. Discovery and MCP can help the agent select a capability; x402 handles the paid exchange once the resource is chosen.
Where controls belong
Keep private keys outside prompts and tool output. Use dedicated wallets, limited balances, host allowlists, per-request caps, workflow budgets and retry ceilings. An autonomous agent should be able to decline a valid payment requirement when the spend or destination is outside policy.
Related directory entries
Sources and methodology
TOLL·402 distinguishes public claims, registry discovery, unpaid quote checks and settled paid-call verification. Sources below support the visible claims; presence in a registry is not treated as verification.
- x402 client/server concepts — Authoritative request, requirements and retry responsibilities.
- x402 buyer quickstart — Current client packages and signer registration.
- x402 wallet concepts — Buyer wallet role and key-management context.