x402 explained: how apps and AI agents pay per API call

HTTP has had a status code for payments since 1997: 402 Payment Required. It was "reserved for future use" for almost three decades. x402 is an open protocol, started by Coinbase in 2025, that finally gives it a job: a server answers 402 with a price, the client pays with a stablecoin, and retries the same request. No account, no API key, no monthly plan.

That matters most for software that buys things on its own. An AI agent can't fill in a sign-up form or a card number, but it can hold a wallet and pay a fraction of a cent for exactly the data it needs.

The flow in four requests

1. Request. The client calls the endpoint as usual, for example GET /x402/v1/gas.
2. 402 with terms. The server answers 402 Payment Required with a PAYMENT-REQUIRED header: a base64 JSON object listing what it accepts. Each option has a scheme (exact), a network (eip155:8453 is Base), an asset (the USDC contract), an amount in the token's smallest unit, and the payTo address.
3. Pay and retry. The client signs a payment for one of those options and sends the same request again with a PAYMENT-SIGNATURE header.
4. Verify, serve, settle. The server checks the payment, runs the request and settles the payment on-chain. The response carries a PAYMENT-RESPONSE header with the transaction hash.

Version 1 of the protocol used X-PAYMENT and X-PAYMENT-RESPONSE headers and put the terms in the JSON body. Well-behaved servers accept both.

Why the client doesn't send a transaction

For USDC on EVM chains the exact scheme uses EIP-3009 (transferWithAuthorization). The client signs an off-chain authorisation: "move 0.005 USDC from me to this address, valid for the next 60 seconds, nonce X". It costs the client no gas and can't be reused or changed.

Someone still has to submit it on-chain. That's the facilitator: a service that verifies the signature and balance (/verify) and then submits the transfer and pays the gas (/settle). Coinbase's CDP and independent facilitators such as PayAI offer this, and the server never has to run a node or hold gas money.

What it costs

• The client pays the listed price in USDC, and nothing else on Base.
• The server pays nothing to receive it if the facilitator covers gas, which most do on a free tier for now.
• Minimums are tiny. Prices of 0.001–0.05 USDC per call are common, which is impossible with card payments where the fixed fee alone is around 30 cents.

Calling an x402 API

In JavaScript, the reference client wraps fetch:

import { wrapFetchWithPayment } from "@x402/fetch";
const pay = wrapFetchWithPayment(fetch, client); // client = your EVM signer
const res = await pay("https://scriptsmith-dashboard.pages.dev/x402/v1/phishing-check?url=metamsk.io");

The wrapper sees the 402, picks a payment option it can pay, signs, retries and returns the final response. Python and Go clients work the same way, and several agent frameworks and MCP wallets now pay x402 endpoints automatically.

A few habits keep costs predictable: set a maximum price per call in your client, keep only a small working balance in the agent's wallet, and log the PAYMENT-RESPONSE transaction hashes so you can reconcile spend.

Building an x402 API

The server side is small:

1. Return 402 with your terms when a request has no payment header.
2. Validate input before asking for payment, so nobody pays for a malformed request.
3. On a paid request, call the facilitator's /verify, run your handler, and only call /settle if the handler succeeded. That way a failed request is never charged.
4. Publish discovery documents (an OpenAPI file with prices, or /.well-known/x402) so registries and agents can find you.

Directories such as x402scan and 402index list public x402 endpoints, and Coinbase's Bazaar lists services that settle through its facilitator.

Is x402 safe?

The payment is a signed authorisation for one fixed amount to one address, so a server can't take more than the price it showed. The risks are the usual ones: paying for data that turns out to be bad, or an agent paying a malicious endpoint in a loop. Set per-call and per-day limits, and treat API responses as untrusted input.

Try it

Our Chain Check API sells crypto safety data this way: token approvals, phishing checks, EVM and Solana token risk, contract scans, wallet reports and gas. Call any endpoint without paying to see the real 402 terms.