Payment Protocol

x402
Payment Required

An HTTP 402-based payment protocol for AI agent commerce. Agents discover prices, sign card tokens, and pay for resources in a single retry — no wallets, no redirects, no human in the loop.

View live scheme
How It Works

Four-step payment flow

1
Agent requests a resource
The agent makes a standard HTTP request to a protected endpoint. No special headers needed on the first attempt.
2
Server returns 402 + payment requirements
The server responds with HTTP 402 Payment Required and an x-payment-required header containing the price, currency, and facilitator URL.
3
Agent signs a card token & retries
The agent constructs a payment payload with its card token, the requested amount, a unique nonce, and sends it via the X-PAYMENT header on a retry request.
4
Server settles & returns the resource
The server verifies the token, calls the facilitator's /settle endpoint to debit the card, and returns the requested resource on success.
API Reference

Endpoints

GET /x402/scheme

Returns the payment scheme specification — supported currency, token format, and facilitator status. Use this to discover whether card payments are configured and what parameters to use.

POST /x402/verify

Validates a payment token without charging the card. Checks the JWT signature, nonce uniqueness, amount limits, card status, and available balance. Returns { isValid: true } or a reason for rejection.

POST /x402/settle

Settles a payment — debits the card balance, records the transaction, and marks the nonce as used. Auto-closes the card when balance reaches zero. Returns a transaction ID on success.

Token Format

Card token payload

Card tokens are signed JWTs issued to agents. Each token is scoped to a specific card and capped at a maximum spend amount.

JWT Payload
{ "cardId": "card_8xK2m...", // Virtual card ID "userId": "user_3jF9...", // Card owner "maxAmountCents": 5000, // Max $50.00 per tx "iat": 1709337600, // Issued at "exp": 1709341200 // Expires in 1 hour }
Payment Payload

The full payment payload wraps the card token with the transaction details. This is base64-encoded and sent in the X-PAYMENT header.

Payment Body
{ "x402Version": 1, "scheme": "card", "payload": { "cardToken": "eyJhbGciOiJIUzI1NiI...", "amountCents": 250, // $2.50 "currency": "USD", "nonce": "a1b2c3d4...", // Unique per request "validBefore": 1709338200, // 10-min window "resourceUrl": "https://api.example.com/data" } }
Headers

Payment headers

x-payment-required
Sent by the server in the 402 response
402 Response
HTTP/1.1 402 Payment Required x-payment-required: { "scheme": "card", "currency": "USD", "amountCents": 250, "facilitator": "https://x402.agentcard.sh/x402", "description": "API access — 1 request" }
X-PAYMENT
Sent by the agent on the retry request
Retry Request
GET /protected-resource HTTP/1.1 X-PAYMENT: eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiY2FyZCIs... ↑ base64-encoded payment payload