x402 Payment Protocol: The Complete Developer Guide

HTTP status code 402 was reserved “for future use” in 1997. Nearly three decades later, the x402 protocol finally gives it a purpose: enabling machine-to-machine payments natively over HTTP. This guide covers the full protocol as implemented by Obolo, from first request to verified response.

What Is HTTP 402?

When the HTTP specification was drafted, its authors reserved status code 402 — “Payment Required” — anticipating a future where payments would be part of the web's fabric. That future never arrived for browsers. Credit cards won. But for AI agents, the original vision makes perfect sense: a machine-readable signal that says “this resource costs money, here's how to pay.”

The x402 protocol standardizes what a 402 response body looks like, which headers carry payment proof, and how a server verifies that proof. It turns HTTP 402 from a dormant curiosity into a working payment rail.

The x402 Flow: Step by Step

Every x402 interaction follows the same eight-step sequence. No SDK is required on the client side — any HTTP client that can read JSON and set headers will work.

1. Agent sends a GET (or POST) request to the proxy URL without any payment headers. This is the discovery step.
2. Proxy returns 402 Payment Required. The response body is a JSON object containing payment_options— an array of accepted payment methods, each specifying the chain, token contract address, amount in the token's smallest unit, and the treasury wallet address to send funds to.
3. Agent selects a payment option. A well-designed agent picks the cheapest option by comparing gas fees across chains. On Base L2, a USDC transfer typically costs less than $0.01 in gas.
4. Agent sends an on-chain transfer — a standard ERC-20 transfer() call for EVM chains, or an SPL token transfer on Solana, or a TRC-20 transfer on TRON. The recipient is the treasury wallet from the 402 response.
5. Agent retries the original request with three additional headers: X-Payment-Hash (the transaction hash), X-Payment-Chain (which blockchain was used), and X-Agent-Wallet(the sender's address).
6. Proxy verifies the payment on-chainby querying the chain's RPC endpoint. It confirms the transaction exists, the amount matches, the recipient matches, and the transaction has not been used before.
7. Proxy forwards the request to the upstream API, attaching provider credentials if configured.
8. Upstream responds through the proxy. The agent receives the API response along with X-Payment-Verified: true and rate-limit headers.

Payment Headers

x402 uses three HTTP headers to carry payment proof. All three are required on the authenticated retry request:

• X-Payment-Hash— The transaction hash (or signature on Solana) proving the on-chain transfer. This is a hex string for EVM chains or a base58 string for Solana.
• X-Payment-Chain— The blockchain used for payment. Accepted values: base, ethereum, solana, tron, arbitrum, optimism, polygon, bsc.
• X-Agent-Wallet— The wallet address that sent the payment. Used for audit logging and reputation tracking.

Multi-Token Support

Obolo accepts four stablecoins across eight blockchains, giving agents maximum flexibility:

• USDC — Circle's USD Coin. Available on all 8 supported chains.
• USDT — Tether. Available on Ethereum, TRON, Arbitrum, Optimism, Polygon, BSC.
• USD1 — Available on Base and Ethereum.
• PYUSD — PayPal's stablecoin. Available on Ethereum and Solana.

The 402 response body lists every token/chain combination the endpoint accepts. Providers can restrict which tokens they accept in the dashboard. Agents pick whichever option minimizes their total cost (price + gas).

Replay Protection

Every transaction hash is stored in Cloudflare KV after successful verification. If an agent (or attacker) resubmits the same X-Payment-Hash, the proxy immediately rejects the request with a 409 Conflict response. The deduplication store uses a TTL long enough to outlast any practical replay window while keeping storage bounded.

Obolo also implements a two-phase locking mechanism: before verifying on-chain, it acquires a short-lived lock on the hash to prevent concurrent verification of the same transaction. This eliminates the race condition where two requests submit the same hash simultaneously.

Why x402 Matters for AI Agents

AI agents cannot sign into dashboards. They cannot complete CAPTCHA challenges, enter credit card numbers, or negotiate enterprise contracts. They need a payment method that is:

• Programmatic — No UI, no human in the loop.
• Stateless — No session cookies, no OAuth tokens to refresh.
• Verifiable — Payment proof is on-chain, auditable by anyone.
• Instant — Settlement in seconds, not days.
• Universal — Works with any HTTP client in any language.

HTTP 402 is the only HTTP status code designed for payment. x402 turns it into a real protocol. No SDK required. No wallet UI. No human approval. Just HTTP.

Code Example: The Full Flow

Here is the complete x402 flow using curl:

# Step 1: Discover payment requirements
curl -s https://proxy.gateflow.io/v1/weather-api-a1b2 \
  | jq .

# Response: 402 Payment Required
# {
#   "error": "Payment Required",
#   "payment_options": [
#     {
#       "chain": "base",
#       "token": "USDC",
#       "amount": "100000",
#       "recipient": "0xTREASURY...",
#       "contract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
#     }
#   ]
# }

# Step 2: Send USDC on Base (via your wallet/script)
# ... returns tx hash 0xabc123...

# Step 3: Retry with payment proof
curl -s https://proxy.gateflow.io/v1/weather-api-a1b2 \
  -H "X-Payment-Hash: 0xabc123..." \
  -H "X-Payment-Chain: base" \
  -H "X-Agent-Wallet: 0xYOUR_WALLET"

# Response: 200 OK with API data

Further Reading

The x402 protocol is open and composable. Obolo's implementation adds replay protection, multi-chain support, and fraud detection on top of the base specification. To dive deeper:

• x402 Protocol Specification — The full technical spec with schema definitions.
• Agent Quickstart Guide — Get your first agent paying for APIs in under 10 minutes.
• AP2 Mandate Protocol — Delegated spending for agents operating under human-set budgets.