x402 Protocol

What is x402?

x402 is a micropayment protocol built on top of HTTP 402 (Payment Required). It enables instant, trustless micropayments for API access without complex blockchain interactions or gas fees for every request. Think of it as “pay-per-use” for APIs, perfect for AI agents and automated trading.

How It Works

Request

Client makes an API request to a protected endpoint.

402 Response

Server responds with HTTP 402 Payment Required and payment details:

Cost in USDC
Facilitator information
Nonce for signature

Authorization

Client creates an EIP-3009 authorization signature:

No gas fees
Offline signing
Single nonce per payment

Retry with Payment

Client retries request with payment signature in headers.

Verification

Facilitator verifies the signature and forwards request to server.

Settlement

After 300ms delay (anti-race condition), facilitator settles payment on-chain.

Key Features

Instant

Payments verified in milliseconds, no waiting for block confirmations

Trustless

EIP-3009 signatures are cryptographically secure

Gasless

Client doesn’t pay gas - facilitator handles settlement

Micropayments

Payments as low as $0.0001 are economically viable

EIP-3009: Transfer With Authorization

x402 uses EIP-3009 for gasless USDC transfers:

Standard Transfer (Traditional)

User → Wallet → Gas Fee → Blockchain → Transfer

EIP-3009 (x402)

User → Sign Message → Facilitator → Blockchain (facilitator pays gas)

Authorization Structure

{
  from: "0x...",           // Your wallet
  to: "0x...",             // Facilitator/platform
  value: "100000",         // Amount in USDC (6 decimals)
  validAfter: 0,           // Valid from timestamp
  validBefore: 2^256-1,    // Valid until timestamp
  nonce: "0x...",          // Unique nonce (prevents replay)
}

Signed with EIP-712 structured data signature.

x402 V2 (Current)

Network Format: CAIP-2

Version 2 uses CAIP-2 network identifiers:

eip155:84532 - Base Sepolia (testnet)
eip155:8453 - Base (mainnet)

Instead of simple chain IDs.

Payment Header

PAYMENT-SIGNATURE: <base64_encoded_payment_data>

Payment data structure:

{
  "version": 2,
  "network": "eip155:84532",
  "authorization": {
    "from": "0x...",
    "to": "0x...",
    "value": "100000",
    "validAfter": 0,
    "validBefore": "115792089...",
    "nonce": "0x...",
    "v": 27,
    "r": "0x...",
    "s": "0x..."
  }
}

Backward Compatibility

x402 V2 servers still accept V1 payments via X-PAYMENT header for compatibility.

Facilitators

402.cat uses round-robin across multiple facilitators for reliability:

Facilitator	URL	Status
PayAI	facilitator.payai.network	Primary
httpcat	httpcat-facilitator.fly.dev	Secondary
x402.org	www.x402.org/facilitator	Tertiary
Railway	ts-2-facilitator-production.up.railway.app	Backup
Dexter	x402.dexter.cash	Backup
Coinbase CDP	api.cdp.coinbase.com	Optional (requires API key)

If one facilitator is down, the system automatically tries the next.

Payment Flow

Example: Buying a Token

1. httpcat buy MOON 0.10

2. CLI → GET /tokens?symbol=MOON
   ← 200 OK (free endpoint)

3. CLI → POST /entrypoints/token_buy_0_10/invoke
   ← 402 Payment Required
   {
     "cost": "0.10",
     "facilitator": "facilitator.payai.network",
     "nonce": "0x1234..."
   }

4. CLI → Sign EIP-3009 authorization
   {
     "from": "0xUser...",
     "to": "0xFacilitator...",
     "value": "100000",  // $0.10 in USDC
     "nonce": "0x1234..."
   }

5. CLI → POST /entrypoints/token_buy_0_10/invoke
   Headers: PAYMENT-SIGNATURE: <signature>
   ← 200 OK
   {
     "success": true,
     "data": {...}
   }

6. Facilitator → Settles on-chain (async, 300ms delay)

Cost Structure

Free Endpoints

No payment required:

GET /health
GET /tokens (list all)
GET /tokens/:id (token info - some details)
GET /positions
GET /api/* (read-only endpoints)

Paid Endpoints

Require x402 payment:

POST /tokens ($0.01 - create)
POST /entrypoints/token_buy_* (variable)
POST /entrypoints/token_sell ($0.01)
POST /entrypoints/token_info ($0.0001)
POST /entrypoints/* (various costs)

See Fee Structure for complete pricing.

Referral System

Earn 10% of all fees by setting the X-402-Referrer header:

POST /entrypoints/token_buy_0_10/invoke
X-402-Referrer: 0xYourAddress...
PAYMENT-SIGNATURE: <signature>

Benefits:

10% of all fees from referred users
Includes both x402 and trading fees
Passive income from successful referrals
Claimable once minimum threshold reached

Example:

User buys $0.20 of tokens via your referral link
- x402 fee: $0.20
- Trading fee: $0.002
- Total fees: $0.202
- Your cut: $0.0202 (10%)

Implementation

httpcat-cli Handles This Automatically

The CLI abstracts away all x402 complexity:

# You just run:
httpcat buy MOON 0.10

# CLI handles:
# 1. Detecting 402 response
# 2. Signing authorization
# 3. Retrying with payment
# 4. Verifying settlement

Building Your Own Client

If building a custom client:

import { x402Client } from '@402/client';

const client = new x402Client({
  privateKey: process.env.PRIVATE_KEY,
  network: 'eip155:84532'
});

// Automatic payment handling
const response = await client.post('/entrypoints/token_buy_0_10/invoke', {
  identifier: 'MOON',
  amount: 0.10
});

// CLI handles 402 → sign → retry automatically

Security

Nonce Protection

Each payment uses a unique nonce:

Prevents replay attacks
Cannot reuse signatures
Validated on-chain

Signature Verification

EIP-3009 signatures are:

Cryptographically secure (ECDSA)
Tied to specific parameters
Verifiable on-chain
Cannot be forged

Amount Limits

Safety limits prevent accidents:

Testnet: Max $0.20 per tx
Mainnet: Max $200 per tx
Client-side validation
Server-side enforcement

Facilitator Trust

Facilitators cannot:

Steal funds (authorization is specific)
Change amounts (signature validation)
Reuse signatures (nonce tracking)

They can:

Delay settlement (but not prevent)
See payment details (transparent)

Benefits for AI Agents

Why x402 is Perfect for AI

No Wallet UI: Agents can’t interact with MetaMask/wallet UIs
Programmatic: Simple HTTP signatures
Instant: No waiting for confirmations
Gasless: Agents don’t manage gas fees
Micropayments: Pay exactly for what you use

Example: AI Trading Agent

import requests
from x402 import sign_payment

def trade_token(token, amount):
    # Make request
    response = requests.post(
        'https://agent.402.cat/entrypoints/token_buy_0_10/invoke',
        json={'identifier': token, 'amount': amount}
    )

    if response.status_code == 402:
        # Sign payment
        payment = sign_payment(
            cost=response.json()['cost'],
            facilitator=response.json()['facilitator'],
            nonce=response.json()['nonce']
        )

        # Retry with payment
        response = requests.post(
            'https://agent.402.cat/entrypoints/token_buy_0_10/invoke',
            json={'identifier': token, 'amount': amount},
            headers={'PAYMENT-SIGNATURE': payment}
        )

    return response.json()

Comparison to Alternatives

Feature	x402	Traditional API Keys	On-Chain Only
Setup	Wallet only	Account registration	Wallet + gas
Cost	Pay per use	Subscription	Gas per tx
Speed	Instant	Instant	Block confirmation
Micropayments	✅ $0.0001+	❌ Not economical	❌ Gas too high
Trustless	✅ Crypto signatures	❌ API key trust	✅ Blockchain
AI-Friendly	✅ Programmatic	✅ Programmatic	❌ Complex

Next Steps

Fee Structure

Complete fee breakdown

API Reference

Explore all paid endpoints

CLI Commands

Use httpcat CLI (automatic x402)

Examples

See complete workflows

x402 makes micropayments practical. Instead of monthly subscriptions or complex blockchain interactions, you pay exactly what you use, when you use it.

Getting Started

httpcat-cli

MCP Server

Core Concepts

What is x402?

How It Works

Key Features

Instant

Trustless

Gasless

Micropayments

EIP-3009: Transfer With Authorization

Standard Transfer (Traditional)

EIP-3009 (x402)

Authorization Structure

x402 V2 (Current)

Network Format: CAIP-2

Payment Header

Backward Compatibility

Facilitators

Payment Flow

Example: Buying a Token

Cost Structure

Free Endpoints

Paid Endpoints

Referral System

Implementation

httpcat-cli Handles This Automatically

Building Your Own Client

Security

Benefits for AI Agents

Why x402 is Perfect for AI

Example: AI Trading Agent

Comparison to Alternatives

Next Steps

Fee Structure

API Reference

CLI Commands

Examples

Getting Started

httpcat-cli

MCP Server

Core Concepts

​What is x402?

​How It Works

​Key Features

Instant

Trustless

Gasless

Micropayments

​EIP-3009: Transfer With Authorization

​Standard Transfer (Traditional)

​EIP-3009 (x402)

​Authorization Structure

​x402 V2 (Current)

​Network Format: CAIP-2

​Payment Header

​Backward Compatibility

​Facilitators

​Payment Flow

​Example: Buying a Token

​Cost Structure

​Free Endpoints

​Paid Endpoints

​Referral System

​Implementation

​httpcat-cli Handles This Automatically

​Building Your Own Client

​Security

​Benefits for AI Agents

​Why x402 is Perfect for AI

​Example: AI Trading Agent

​Comparison to Alternatives

​Next Steps

Fee Structure

API Reference

CLI Commands

Examples

What is x402?

How It Works

Key Features

EIP-3009: Transfer With Authorization

Standard Transfer (Traditional)

EIP-3009 (x402)

Authorization Structure

x402 V2 (Current)

Network Format: CAIP-2

Payment Header

Backward Compatibility

Facilitators

Payment Flow

Example: Buying a Token

Cost Structure

Free Endpoints

Paid Endpoints

Referral System

Implementation

httpcat-cli Handles This Automatically

Building Your Own Client

Security

Benefits for AI Agents

Why x402 is Perfect for AI

Example: AI Trading Agent

Comparison to Alternatives

Next Steps