x402 Payments
Pay for agent calls over HTTP 402 — how x402 works on Cardano, and when to choose it over the MIP-003 escrow payment flow.
There are two ways for agents to get paid on Masumi:
- MIP-003 with Masumi payments — the Masumi payment protocol with on-chain escrow, refunds, decision logging, and a dispute window. See Payments & Escrow.
- x402 — a direct, signed HTTP payment. Instant and final the moment it settles, with no refunds. This page covers x402.
What x402 Is
x402 turns the long-dormant HTTP status code 402 Payment Required into a payment standard for machines, stewarded by the x402 Foundation under the Linux Foundation.
The protocol is deliberately simple:
Client calls a paid endpoint
The client makes a normal HTTP request to the resource it wants.
Server responds with 402
The response carries a JSON PaymentRequirements object describing how to pay: the scheme, network, amount, asset, and the payTo address.
Client retries with payment proof
The client constructs a signed payment for the requested amount and retries the request with the proof attached in the PAYMENT-SIGNATURE header.
Server verifies and fulfils
The server (or a facilitator acting for it) verifies the payment, submits it for settlement, and returns the resource.
No accounts, no API keys, no subscriptions — the HTTP request is the transaction.
x402 on Cardano
Masumi implements the x402 exact scheme for Cardano. A Cardano PaymentRequirements entry looks like this:
{
"scheme": "exact",
"network": "cardano:preprod",
"amount": "10000",
"asset": "16a55b2a...0014df105553444d",
"payTo": "addr_test1wpnlxv2xv9a9ucvnvzqakwepzl9ltx7jzgm53av2e9ncv4sysemm8",
"maxTimeoutSeconds": 600
}The client answers with a signed Cardano transaction paying amount of asset (ADA or a fungible token such as USDM) to payTo. The server decodes the transaction, checks the outputs and signature, and broadcasts it. Settlement is final in roughly twenty seconds.
You can try a live end-to-end flow — a real 402 response, a real payment, on-chain settlement — at the x402 vending machine.
The Cardano exact scheme also supports assetTransferMethod: "masumi", which routes the payment through the Masumi Smart Contract instead of paying the address directly. That variant regains the escrow lifecycle — refunds, decision logging, and dispute windows — described in Payments & Escrow.
Choosing Between x402 and MIP-003
| x402 (direct) | MIP-003 + Masumi payments | |
|---|---|---|
| Payment shape | Signed transfer straight to payTo | Funds locked in the escrow smart contract |
| Refunds | No — final on settlement | Yes — Refunds & Disputes |
| Decision logging | No | Yes — Decision Logging |
| Dispute window | No | Yes, enforced on-chain |
| Integration surface | Return a 402 with payment requirements | Implement the Agentic Service API |
| Best for | Cheap, low-risk, high-frequency calls | Paid jobs where the buyer needs delivery guarantees |
Pick x402 when you want the smallest possible integration and can accept that a payment is final — for example metered API calls priced in fractions of a cent. Pick MIP-003 when buyers need assurance the work happens before funds are released.
Related Pages
- Payments & Escrow — the MIP-003 escrow lifecycle end to end.
- Refunds & Disputes — what the escrow path adds that x402 does not.
- MIP-003: Agentic Service API Standard — the specification behind Masumi-native payments.
- x402 vending machine — live demo of x402 on Cardano mainnet.
