x402 Examples

Four progressive examples showing the x402 HTTP payment protocol — from raw handshake to a Claude AI agent paying for data autonomously.

Protocol Overview

x402 reuses HTTP's built-in 402 Payment Required status code to gate resources behind stablecoin micropayments. No accounts, no API keys — just sign a payment authorization and retry.

Step 1 — Client requests resource (no payment)
  Client ──────────────────────────────────────► Server
  GET /weather

Step 2 — Server asks for payment
  Client ◄──────────────────────────────────── Server
  402 Payment Required
  PAYMENT-REQUIRED: base64({
    scheme: "exact",
    payTo: "0xRECIPIENT",
    amount: "1000",              ← USDC atoms (1000 = $0.001 USDC)
    network: "eip155:84532",     ← Base Sepolia (testnet)
    facilitator: "https://x402.org/facilitator"
  })

Step 3 — Client signs EIP-3009 authorization
  "I authorize transfer of $0.001 USDC from my wallet to 0xRECIPIENT"
  (off-chain signature — no gas needed yet)

Step 4 — Client retries with signed payment
  Client ──────────────────────────────────────► Server
  GET /weather
  PAYMENT-SIGNATURE: base64({signed EIP-3009 payload})

Step 5 — Server verifies via facilitator
  Server ─────────────────────────────────────► Facilitator
  POST /verify {payload, requirements}
  ← {isValid: true}

Step 6 — Server responds + settles on-chain (background)
  Client ◄──────────────────────────────────── Server
  200 OK  +  PAYMENT-RESPONSE: {txHash, payer, ...}
  (Facilitator executes on-chain transfer asynchronously)

Three parties:

• Client — pays using a wallet private key; auto-handled by x402 library
• Server — adds one middleware; never touches payment logic directly
• Facilitator (x402.org) — verifies signatures, executes on-chain settlement

---

Testnet Wallet Setup

All examples run on Base Sepolia (eip155:84532) — Ethereum's Base L2 testnet.

You only need testnet USDC — no ETH required.

x402 uses EIP-3009 transferWithAuthorization: the client signs an off-chain authorization, and the facilitator (x402.org) submits the actual on-chain transaction and pays gas on your behalf. The client never touches ETH.

Step 1 — Generate a wallet

Python (uses eth_account, already in requirements):

from eth_account import Account
import secrets

key = "0x" + secrets.token_hex(32)
account = Account.from_key(key)
print("Address    :", account.address)
print("Private key:", key)

Or use any EVM wallet (MetaMask, Coinbase Wallet, etc.) and export the private key.

Keep your private key secret. Store it in .env (already gitignored in this repo) and never commit it.

Step 2 — Fund with testnet USDC

x402 on Base Sepolia uses Circle's official testnet USDC:

Faucet	Amount	Contract
faucet.circle.com	10 USDC	0x036CbD53842c5426634e7929541eC2318f3dCF7e

Select "Base Sepolia", paste your address, click request. USDC arrives in ~30 seconds.

Tip: Use the same address as both X402_PRIVATE_KEY wallet and X402_RECIPIENT_ADDRESS while testing — you pay yourself, net cost is $0.

Step 4 — Configure .env

cp .env.example .env

Edit .env:

X402_PRIVATE_KEY=0x...          # private key from Step 1
X402_RECIPIENT_ADDRESS=0x...    # address from Step 1 (or a separate receiving address)
X402_NETWORK=eip155:84532       # Base Sepolia testnet

Step 5 — Verify balance (optional)

Check your testnet USDC balance on Sepolia Basescan:

https://sepolia.basescan.org/address/<YOUR_ADDRESS>#tokentxns

---

Examples

#	Example	What it teaches
01	Hello World	Raw 402 handshake vs x402 library auto-pay
02	Pay-Per-Call API	Realistic tiered API with x402 middleware
03	AI Agent + Paid Tools	Claude agent autonomously paying for data via tools
04	x402-anthropic	Claude API gateway using the x402-anthropic package

Prerequisites

Python (all examples):

pip install "x402[fastapi,httpx]>=2.11.0" fastapi uvicorn eth-account

TypeScript (all examples):

npm install @x402/express @x402/fetch @x402/evm @x402/core express viem
npm install -D typescript tsx @types/express @types/node

Running tests

pip install -r tests/requirements.txt
pytest tests/ -v

• test_smoke.py — starts all 4 servers, checks 402 structure and pricing (22 tests)
• test_mock.py — payment round-trips with mocked facilitator + real EVM signing, agent tool loop (11 tests)