HTTP 402, x402 and MPP
In short: 402 Payment Required is the HTTP status a server sends when a request has to be paid for. Two protocols, x402 and MPP, define what goes with it: the server answers 402 with a price, the client signs a payment and repeats the request, and the server answers 200 with a receipt. Both tell an agent how to pay. Neither decides whether it should, which is the part spendctl covers.
HTTP 402 in one paragraph
Section titled “HTTP 402 in one paragraph”Status code 402 has been in HTTP since HTTP/1.1 (RFC 2068, January 1997), and the current HTTP specification, RFC 9110, still describes it as “reserved for future use”. For almost thirty years nothing standard came with it. x402 (2025) and MPP (2026) are the two published answers to what a 402 response should carry.
The shape both protocols share
Section titled “The shape both protocols share”- The client asks for a resource:
GET /report. - The server answers
402 Payment Requiredwith a quote: how much, in which asset, on which network or payment method, to which recipient. - The client signs a payment that matches the quote and repeats the request with it.
- The server checks the payment, serves the response (
200 OK) and returns a receipt.
No account, no API key and no invoice are involved. That is the appeal for agents: software can pay for an API it has never seen before. It is also the risk, because the quote comes from the server and the client is the one that signs.
x402 was published by Coinbase in May 2025. Since April 2026 the protocol is governed by the x402 Foundation under the Linux Foundation, and the specification and SDKs live at github.com/x402-foundation/x402. Two versions are in use, and a client has to read both:
| x402 v1 | x402 v2 | |
|---|---|---|
| Quote (server → client) | JSON body of the 402 | PAYMENT-REQUIRED header (base64 JSON) |
| Payment (client → server) | X-PAYMENT header |
PAYMENT-SIGNATURE header |
| Settlement (server → client) | X-PAYMENT-RESPONSE header |
PAYMENT-RESPONSE header |
| Network names | base-sepolia |
CAIP-2 ids such as eip155:84532 |
| Amount field | maxAmountRequired |
amount, in the asset’s smallest unit |
A quote lists one or more options under accepts. Each names a scheme (exact is the common one), the network, the asset (a token contract), the amount, the recipient (payTo) and how long the authorization may stay valid. With exact on an EVM network the client signs an EIP-3009 transferWithAuthorization; a facilitator chosen by the seller verifies the signature and settles it on chain, so neither side has to run a node.
MPP (Machine Payments Protocol)
Section titled “MPP (Machine Payments Protocol)”MPP was published by Stripe and Tempo in March 2026 (announcement, docs at mpp.dev). It is a separate protocol, not a layer over x402: it uses HTTP’s authentication headers.
| MPP | |
|---|---|
| Quote (server → client) | WWW-Authenticate: Payment … with a method, an intent and a request |
| Payment (client → server) | Authorization: Payment … |
| Receipt (server → client) | Payment-Receipt header |
The request inside a charge challenge carries the amount, the currency (for example usd, or a token) and the recipient. The method says which rail is used; card payments through Stripe’s Shared Payment Tokens are one of them, so MPP is not limited to stablecoins. A server may advertise x402 and MPP on the same 402.
What neither protocol decides
Section titled “What neither protocol decides”Both protocols describe the exchange. They leave the buyer’s side of the decision open:
- The x402 v2 specification lists “Client-side budget management” as out of scope.
- The official x402 client caps a single payment and otherwise pays the amount the server states. A public report shows it paying a price inflated ten times (x402 issue #3866).
- A total per day, a list of sellers the agent may pay, a human approval above a threshold and one record of every attempt are all left to whoever runs the agent.
Those four are a policy, and a policy has to sit somewhere the agent cannot edit it. Where spend controls can live compares the places.
Where spendctl sits
Section titled “Where spendctl sits”spendctl is a sidecar you run next to your agents (npx spendctl init && npx spendctl start). The agent sends its requests through it; when a seller answers 402, spendctl reads the quote, x402 v1, x402 v2 or MPP, into one shape (recipient, network, asset, amount in USD), checks it against the policy, holds it for a human when the policy says so, has your wallet sign once, and writes a ledger row for the attempt.
What works today, exactly:
- x402 v1 and v2: the
exactscheme on EVM networks, signed and settled end to end. A recorded payment on Base Sepolia is on Real payments. - MPP:
chargechallenges are parsed, checked against the same policy and recorded. Paying one needs anmppxcredential provider wired into the sidecar in code; there is nospendctl.yamlsetting for it yet, and no live MPP payment has been made through spendctl.
Glossary
Section titled “Glossary”| Term | Meaning |
|---|---|
| 402 challenge, quote | The seller’s 402 response: what it wants to be paid, in which asset, to whom |
accepts |
The list of payment options in an x402 quote; the client picks one |
payTo, recipient |
The address or account the payment goes to |
| CAIP-2 | A chain identifier format: eip155:8453 is Base, eip155:84532 is Base Sepolia |
| Atomic units | An amount in the asset’s smallest unit: 10000 of a 6-decimal token is 0.01 |
| EIP-3009 | The signed transfer authorization x402’s exact scheme uses on EVM networks |
| Facilitator | The service, chosen by the seller, that verifies and settles an x402 payment |
| Sidecar | A process you run next to the agent; requests pass through it |
| Spend policy | The rules a payment must pass: budgets, allowed hosts, pinned recipients, approval thresholds |
| Governed payment | A request the spendctl sidecar signed or held for a human; the unit plans count |
| Approval | A human’s decision on a held payment, bound to the recipient, network, asset and amount shown |
| Receipt | The ledger row for an attempt: who, what, how much, why, and the transaction hash |
| Idempotency key | A header the agent sends so a retry of the same request is not paid twice |
- Try the flow with mock money: Sandbox, or locally with the Quickstart.
- Give an agent a budget it cannot raise: Budgets for AI agents.
- Questions people ask first: FAQ.