x402 Concepts & Architecture

What is x402?

x402 is an HTTP-native payment protocol that enables micropayments for API calls. It extends HTTP with the 402 Payment Required status code.

Core Concepts

1. Payment Required Response

When a client requests a protected resource without payment:

HTTP/1.1 402 Payment Required
X-Payment-Required: true
X-Payment-Amount: 0.01
X-Payment-Asset: USDC
X-Payment-Network: ethereum
X-Payment-Recipient: 0x1234...

2. Payment Header

Client includes signed payment in subsequent request:

POST /api/analyze HTTP/1.1
X-Payment-Signature: 0xabcd...
X-Payment-Amount: 0.01
X-Payment-Asset: USDC
X-Payment-Nonce: 12345
Content-Type: application/json

{"query": "Analyze BTC"}

3. Payment Verification

Server verifies payment on-chain before serving content:

async def verify_payment(request):
    signature = request.headers["X-Payment-Signature"]
    amount = request.headers["X-Payment-Amount"]
    
    # Verify on Ethereum network
    is_valid = await ethereum_client.verify_transfer(
        signature=signature,
        amount=amount,
        recipient=WALLET_ADDRESS
    )
    
    return is_valid

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                      x402 PAYMENT FLOW                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  CLIENT                      SERVER                    BLOCKCHAIN   │
│  ┌──────┐                   ┌──────┐                   ┌──────┐    │
│  │      │  1. Request       │      │                   │      │    │
│  │      │──────────────────▶│      │                   │      │    │
│  │      │                   │      │                   │      │    │
│  │      │  2. 402 Required  │      │                   │      │    │
│  │      │◀──────────────────│      │                   │      │    │
│  │      │                   │      │                   │      │    │
│  │      │  3. Sign Payment  │      │                   │      │    │
│  │      │─────────────────────────────────────────────▶│      │    │
│  │      │                   │      │                   │      │    │
│  │      │  4. Request+Sig   │      │                   │      │    │
│  │      │──────────────────▶│      │  5. Verify       │      │    │
│  │      │                   │      │──────────────────▶│      │    │
│  │      │                   │      │                   │      │    │
│  │      │                   │      │  6. Confirmed    │      │    │
│  │      │                   │      │◀──────────────────│      │    │
│  │      │  7. Response      │      │                   │      │    │
│  │      │◀──────────────────│      │                   │      │    │
│  └──────┘                   └──────┘                   └──────┘    │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Terminology

Term	Definition
x402	HTTP 402 Payment Required protocol
Seller	Service provider accepting payments
Buyer	Client making payments for services
Facilitator	Optional intermediary for payment routing
Bazaar	Marketplace for discovering x402 services
Payment Signature	EIP-3009 authorization for transfer

Supported Assets

Asset	Network	Status
USDC	Ethereum	✅ Primary
EURC	Ethereum	🔜 Coming

Pricing Models

Per-Request

Fixed price per API call:

pricing:
  model: "per_request"
  amount: "0.01"
  currency: "USDC"

Per-Token (LLM)

Price based on input/output tokens:

pricing:
  model: "per_token"
  input_price: "0.00001"
  output_price: "0.00003"
  currency: "USDC"

Per-Minute

Time-based billing:

pricing:
  model: "per_minute"
  amount: "0.10"
  currency: "USDC"
  minimum_minutes: 1

Dynamic

Price varies based on complexity:

pricing:
  model: "dynamic"
  base_price: "0.01"
  multipliers:
    - condition: "query_length > 1000"
      multiplier: 2.0
    - condition: "requires_browser"
      multiplier: 1.5

Error Codes

Code	Meaning
`402`	Payment required
`402.1`	Insufficient payment
`402.2`	Invalid signature
`402.3`	Wrong asset
`402.4`	Wrong network
`402.5`	Payment expired

Security Considerations

Replay Protection

Each payment includes unique nonce
Server tracks used nonces
Payments expire after timeout

Double-Spend Prevention

Payment verified on-chain before service
Atomic execution via smart contracts

Rate Limiting

Max requests per payment
Cooldown between payments
Account-level limits

Resources

Next: Seller Onboarding Guide →