x402 protocol
x402 is a way for a web service to charge for a request in the request itself. An agent wallet pays services this way: the agent asks for a resource, the service says what it costs, the wallet pays in USDC, and the service answers. This page explains the protocol, what Keyban adds at each step and why the wallet uses it.
How an x402 payment works
- Wallet MCPthe agent's side
- Keybanpolicy and co-signature
- x402 serviceand its facilitator
- 1x402_pay: service URL
- 2one request to read the price
- 3402 and payment requirements
- 4policy decision and the authorization to sign
- 5co-signing rounds
- 6request with the signed payment
- 7verified and settled, then the resource
In short, Keyban reads the price and builds what is signed, and the agent only signs it.
x402 reuses an HTTP status code that has existed for decades, 402 Payment Required. The buyer is the agent. One payment goes in five steps, and each step says what the protocol does and what Keyban does:
- The agent asks for a resource. The buyer requests the resource. With Keyban, the agent gives Keyban the service's URL through
x402_pay, and Keyban makes the request itself, once, to read what it costs. - The service answers
402with its payment requirements: the price, the token, the network and the address to pay. Keyban reads the real price and the address from that answer, never from the agent, and keeps a payment option the wallet can settle: theexactscheme, in USDC, on the wallet's own network. - Keyban decides. The protocol has no such step. Keyban checks the destination and the amount against the spending policy, creates the payment intent, and holds the payment for a human if it is above the approval threshold. A refused payment stops here, before anything is signed.
- The buyer signs an authorization to pay exactly that. The wallet pays through the standard's EIP-3009
transferWithAuthorization: a message that says "pay this amount to this address before this time". The agent sends no transaction itself and needs no native token for fees. Keyban builds the authorization, with a random one-time number and a validity window no longer than the service allows, and the agent checks that it matches the fingerprint Keyban recorded and signs it with its shared key, together with Keyban. The wallet's smart account validates the signature through the standard ERC-1271 mechanism. The agent adds nothing of its own: it cannot change the amount, the recipient or the time window. - The agent sends the request again, with the authorization attached. The service has the payment verified and settled on the blockchain through a facilitator, which submits the authorization, then returns the resource.
The service chooses its facilitator, and the buyer only picks among the payment options the service offers. The service does not need an account, an API key or a subscription: payment is the credential.
The three tools
The agent has three tools for x402:
discover_x402_servicessearches Keyban's directory of services that accept x402. A service that offers no scheme the wallet can settle is marked as not payable;x402_infoalso checks the network.x402_infochecks what a URL would cost, and what parameters it takes, without paying anything. The agent should call it before paying, with the same method, query and body it will pay with, because some prices depend on them.x402_payfetches the resource and pays automatically, within the policy.
Inside a mission, a payment goes through x402_pay_in_mission instead of x402_pay. See Missions.
How the agent and you find services is on the Discover services page, and the full list of tools on the Wallet MCP tools page.
What a wallet can and cannot pay
- Only the
exactscheme. The wallet pays a fixed price. Theuptoscheme Coming soon, where the service charges up to a maximum, is not supported yet: a service that offers only another scheme is refused withpolicy/x402-no-exact-accept. - Only USDC, in the amount the service states.
- Only on Base mainnet and XDC mainnet. The wallet pays on its own network and never follows the service to another chain, and a service that does not offer a payment on that chain is refused.
- Only services that pass the policy. The service's domain must pass the destination rules, and the price must fit the caps and budgets.
When an x402 payment is refused, the reason starts with policy/ and is explained on the Refusal reasons page.
Why x402 is the rail of an agent
An agent that must pay for data or a service cannot fill a form, sign up for an account or keep a card on file. With x402, the price is in the response, the payment is a signature, and there is nothing to subscribe to. That fits a software agent that makes many small requests to services it has never used before, and it fits a spending policy: every request has a price that Keyban can compare with a cap before anything is signed.
Related
- Spending policy: the limits an x402 payment is checked against.
- Payment intents: what happens while a payment waits for approval.
- Networks and assets: the networks and the token.