How x402 turns HTTP 402 into a payment step, what the facilitator does, and what an agent’s spend state must look like when many agents pay from one budget.
TL;DR: x402 is an open protocol, started by Coinbase, that uses the HTTP 402 status code to put a stablecoin payment inside an ordinary request: the server names a price, the client signs a payment, a facilitator verifies and settles it onchain. The protocol moves money; it does not decide whether an agent should spend it. When many agents pay from one budget, that decision depends on authorization-time context: remaining budget net of payments still in flight, per-agent limits and recent spend, read at the moment the agent signs.
HTTP has had a status code for payments since the 1990s and almost nobody used it. The spec still says 402 Payment Required is “reserved for future use”. Paying for an API meant an account, a card on file, a monthly invoice and an API key. That works when a human signs up once. It breaks when an agent discovers a data source mid-task, needs one response, and has no one to fill in a billing form.
x402 is a protocol built to fix that: the server answers “this costs one cent,” and the client pays in the same exchange.
It leaves a harder question to you. When twenty agents share one budget and each can sign a payment at any moment, how does each one know what is left? This page covers how x402 works, what the facilitator does, and what your spend state has to look like when an agent decides to pay.
x402 is an open payment protocol that uses the HTTP 402 Payment Required status code to charge for a resource inside a normal request. The server returns its price, the client retries with a signed stablecoin payment, and a facilitator verifies and settles that payment onchain before the server returns the response.
Coinbase Developer Platform introduced x402 in a whitepaper dated May 6, 2025. In April 2026 the protocol moved to the x402 Foundation at the Linux Foundation, and the reference implementation now lives in the x402-foundation/x402 repository, with coinbase/x402 kept as a development fork. The repository describes x402 as “a payments protocol for the internet. Built on HTTP,” with SDKs for TypeScript, Python and Go.
Its stated principles include an open standard that “will never force reliance on a single party,” and trust minimization: “all payment schemes must not allow for the facilitator or resource server to move funds, other than in accordance with client intentions.”
That last line matters for the rest of this page. The client signs exactly what it agrees to pay, and nobody downstream can take more. Whether it should have agreed is decided before the signature, on the client’s side.
The x402 v2 specification defines three roles: the client that wants a resource, the resource server that charges for it, and the facilitator that verifies and settles payments. The repository README names three headers: PAYMENT-REQUIRED on the server’s 402 response, PAYMENT-SIGNATURE on the client’s paid retry, and PAYMENT-RESPONSE on the final response.
Step 1: the price. The client requests a resource with no payment attached. The server answers 402 with a PaymentRequired object. Abridged from the spec’s example:
{
"x402Version": 2,
"accepts": [
{
"scheme": "exact",
"network": "eip155:84532",
"amount": "10000",
"asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
"payTo": "0x2096...287C",
"maxTimeoutSeconds": 60,
"extra": { "name": "USDC", "version": "2" }
}
]
}
The network uses a chain-agnostic namespace:reference identifier (here, Base Sepolia). The amount is in the asset’s atomic units; for a six-decimal stablecoin, 10000 is one cent.
Step 2: the signature. The client picks one of the accepted options and retries with a PaymentPayload. For the exact scheme on EVM chains, the default payload is an EIP-3009 transferWithAuthorization signed by the payer (the scheme also defines Permit2 for tokens without EIP-3009), carrying from, to, value, validAfter, validBefore and a unique nonce. The nonce stops replay; the two timestamps bound how long the authorization stays usable.
Step 3: verify, settle, respond. The server checks the payment itself or calls a facilitator’s POST /verify, then POST /settle, which submits the transfer onchain. The server returns the resource with a SettlementResponse (a success flag, the transaction hash, the network) in PAYMENT-RESPONSE.
No account, no API key, no invoice. The payment is the authentication.
The facilitator is the piece that lets a seller accept x402 payments without running a node or holding keys. The spec gives it three endpoints: POST /verify checks a payment without executing it, POST /settle executes it, and GET /supported lists the schemes and networks it handles.
For the exact scheme on EVM chains with an EIP-3009 authorization, the scheme spec lists what verification covers: the signature recovers to authorization.from; the payer has sufficient balance of the asset; the amount and validity window meet the requirements; the token and network match; and a simulated transferWithAuthorization succeeds. Settlement is the facilitator calling transferWithAuthorization on the token contract.
Anyone can run a facilitator; the protocol does not require a particular one. Coinbase operates a hosted one through its developer platform. Its documentation says it “validates signed payments, screens transactions, submits settlement onchain, and reports the result to your resource server,” including OFAC and Know Your Transaction (KYT) checks, and that it supports the protocol’s exact, upto and batch-settlement schemes on EVM networks. The first 1,000 onchain facilitator transactions each month are free, then $0.001 each, per the same page; verification is free.
Notice what is not on the list. The facilitator checks a wallet’s onchain balance. It has no idea that the wallet belongs to a team whose agents have, say, a $40 daily budget, that this agent’s share is $5, or that eleven other payments from the same wallet are mid-flight. It sees one payment. That is the correct scope for a facilitator, and it is why spend control lives with whoever runs the agents.
A scheme is the rule for turning a signed payment into a transfer. The x402 repository defines four:
The upto spec is for usage-priced calls, such as “Paying for LLM token generation (charge per token generated).” The auth-capture spec gives a payment a lifecycle: “it can be held before it is finalized, finalized for less than the maximum, cancelled outright, or returned after the fact.” Under batch-settlement, “the transfer of value is not executed synchronously during that request.”
For spend state, what matters is when you learn the final cost. Under exact, what an agent signs is what it spends. Under the other three, what it authorizes and what finally moves can differ, or move later. A budget that counts only settled transfers undercounts all three. Reserve the authorized maximum, and release the difference when the final amount arrives.
| Scheme | What the client authorizes | What moves |
|---|---|---|
exact | One fixed amount | That amount, at settlement |
upto | A maximum | The amount used, which “MUST be <= the authorized maximum” and “MAY be 0” |
batch-settlement | A commitment at request time | Value moved later, “out of band” |
auth-capture | A maximum, held first in the default escrow flow | Captured up to the hold, the rest voided, refundable later |
Support now reaches well past Coinbase:
On the chain side, the exact scheme has chain-specific specs for EVM networks, Solana and 15 others, including Stellar, Sui, Aptos and the XRP Ledger.
The numbers below are illustrative, built to show the mechanism.
A research team runs twelve agents that buy market data and document lookups over x402. They share a $40 daily budget. Each agent checks spend against a counter that a background job recomputes from settled payments every 30 seconds.
At 14:02:00 the counter reads $38.10 spent, $1.90 left. A news event lands. Between 14:02:01 and 14:02:20, all twelve agents start pulling data, each signing one or two payments of $0.25 to $0.50. Each agent reads the counter, sees $1.90 available and a price under it, and signs. Every facilitator verification passes, because the wallet itself holds plenty of USDC.
At 14:02:30 the job runs and the counter reads $44.70. The team is $4.70 over a cap that every agent checked.
Nothing in x402 failed. Each payment was signed, verified and settled exactly as specified. The agents acted on context that was 30 seconds old and did not count each other’s signed payments. That is a race condition on unmergeable state: two agents’ spends against one budget do not merge, they add up.
More agents or a slower recompute job widen the overshoot. A per-agent cap without a shared cap only bounds each agent’s share of the damage.
The fix is to make the decision to sign read and write the same state, under concurrency, with no recompute job between them.
Reserve before you sign. The budget check and the reservation are one transaction. If it commits, the agent signs. If it fails, the agent does not.
The reservation and the recorded result are your state. The price, the signature and the settlement belong to x402.
-- One transaction per payment attempt (Postgres-style SQL)
BEGIN;
UPDATE budgets
SET reserved = reserved + :amount
WHERE budget_id = :budget_id
AND spent + reserved + :amount <= cap
RETURNING budget_id; -- zero rows: over budget, ROLLBACK and do not sign
INSERT INTO payment_intents (intent_id, budget_id, agent_id, seller, amount, nonce, status)
VALUES (:intent_id, :budget_id, :agent_id, :seller, :amount, :nonce, 'reserved');
COMMIT;
-- After the PAYMENT-RESPONSE arrives:
-- success -> move :amount from reserved to spent, mark intent 'settled'
-- failure -> release :amount from reserved, mark intent 'failed'
-- no reply before validBefore -> treat as failed and release
Expire reservations with the authorization. The validBefore timestamp on a signed EIP-3009 authorization tells you when an unsettled authorization becomes unusable. A reservation that outlives it is budget you are holding for nothing.
Store intents, not just totals. Intent rows give the next decision per-agent and per-seller spend, and map each onchain transaction back to the agent that caused it.
If your budget really is one row and one cap, any Postgres does this with the conditional update above, and you should use it. Under READ COMMITTED, a second UPDATE on the same row waits for the first to commit, then re-evaluates its WHERE clause against the updated row, so two reservations cannot both pass the cap. It gets harder when the decision to sign reads derived context as well: spend by this agent in the last ten minutes, spend with this seller across the fleet, whether this endpoint’s billing pattern resembles past loops. Now the check is an aggregate over a table that every agent is writing to at once, and it has to be current when it runs.
x402 specifies how a price is stated, how a payment is signed, and how it is verified and settled. It does not specify:
The bottom four rows are a validity window problem: how long may an agent keep signing on a superseded budget or policy, and what does each second cost? If agents run sequentially, with time between steps, a periodic recompute is fine. If they run concurrently against shared money, it is not.
| Concern | Where it lives |
|---|---|
| Wallet balance | The chain; the facilitator checks it at verification |
| Replay protection | The nonce in the signed authorization |
| How long a signature stays usable | validAfter and validBefore |
| Shared budgets across agents | Your system |
| Per-agent and per-task limits | Your system |
| Spend velocity and loop detection | Your system |
| Policy changes reaching running agents | Your system |
Tacnode holds the agent side of the loop: the decision context each agent reads before it signs, and the decision it writes after. The payment itself stays with x402: the facilitator verifies it and the chain settles it.
Budgets, reservations, per-agent limits and payment intents are state your system owns. Held in the Tacnode Context Lake™, they are covered by full ACID transactions: two agents reserving against the same budget cannot both succeed past the cap, because the reservation is a committed write. The derived context the decision also needs, such as recent spend per agent, per seller and per minute, is computed on demand against the latest committed data in the same system, so the check and the aggregate read the same moment. Settlement results flow back in as writes and become context for the next payment.
That is the context gap closed for one specific decision: the agent signs with an accurate picture of what has already been promised. For the broader pattern of agents that buy things, see how shopping agents buy and ACID for agents.
Former Cockroach Labs. Tells stories about infrastructure that actually make sense.
Fresh Context Newsletter
The argument behind the posts — what breaks when AI acts on stale data, from the team building the Context Lake. About twice a month.
Book a demo and discover how Tacnode can power your AI-native applications.
Book a Demo