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.
The four actors in a typical x402 call
The agent decides that it needs a capability. The buyer application turns that intent into an HTTP request and enforces spending policy. The resource server offers payment requirements and controls access to the result. A facilitator may verify the signed payload and settle payment for the server. Keeping these roles distinct prevents the language model from becoming the wallet or the payment network from deciding what work the agent should perform.
Not every deployment uses all four as separate services. A seller can handle verification and settlement directly, and a deterministic program can act as the buyer without a language model. The protocol concerns the HTTP exchange; the agent is simply one possible source of purchasing intent.
A complete request from intent to result
Imagine an agent needs a current weather report for a travel plan. It selects a documented read-only endpoint and sends the normal request without payment. The server replies with HTTP 402 and encoded requirements. Trusted client code decodes the options, verifies that the resource matches the requested URL and checks amount, network, asset and destination against the policy for the weather tool.
If one option is allowed, the client creates a narrowly scoped payment payload with the appropriate signer and retries the original request using the payment header. The server verifies and settles, then returns the weather data. The application stores three outcomes separately: what it paid, whether settlement succeeded and whether the returned data met the tool contract.
| Step | Component | Decision or evidence |
|---|---|---|
| 1. Select tool | Agent / orchestrator | Capability and input fit |
| 2. Request | HTTP client | No payment signature yet |
| 3. Inspect 402 | Policy layer | Amount, network, asset, destination |
| 4. Sign and retry | Wallet adapter | Scoped authorization |
| 5. Validate result | Application | Settlement and useful output |
What should the policy check before signing?
A validly shaped requirement is not automatically an approved purchase. The client should bind policy to the tool or endpoint: allowed host and path, HTTP method, payment scheme, exact network identifier, asset, maximum amount and known or approved destination. It should also check the remaining task and daily budgets before creating the signature.
The resource binding matters because an attacker or configuration error could return a payment request for a different URL. Destination changes deserve scrutiny even when the amount stays small. For newly discovered services, require a human or a stricter evaluation policy until one representative call has been reviewed.
- Does the requirement refer to the resource the agent requested?
- Is the scheme and network supported by this signer?
- Is the asset allowed and the amount below both request and task caps?
- Is the pay-to destination expected for this provider?
- Will this retry remain safe if the first response was delayed?
How automatic payment wrappers help—and what they do not do
Official fetch and Axios wrappers automate the mechanical loop: detect the 402, parse requirements, create a payment with registered schemes and retry. That reduces protocol code in each tool integration. The wrapper still needs a signer and configuration that reflect the buyer's policy; automation should not mean accepting every offer the server returns.
The wrapper also cannot judge whether the requested tool is appropriate or the result is true. Keep tool selection, payment authorization and output validation as visible stages. This separation makes it possible to decline a technically valid payment or quarantine a technically successful but suspicious result.
What can go wrong after the agent pays?
Settlement may succeed while the resource server times out, returns malformed data or produces a valid response that does not answer the request. The application should not blindly retry a paid operation because a second request may create a second charge. Use a provider-supported idempotency key when available and record enough correlation data to ask for support or reconcile the transaction.
For important workflows, validate the response against a schema and task-specific checks before passing it back to the model. Mark a payment as settled even when the output fails; otherwise cost records become falsely optimistic. A clear distinction between payment failure and product failure is essential for choosing whether to retry, switch providers or stop.
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.