X402 Agent Payments Guide

x402 Agent Payments Guide

x402 is the HTTP-native micropayment protocol for AI agents. It enables agents to pay for API calls, data, and services using stablecoins — no API keys, no subscriptions, just a signed payment header.

How x402 Works

Agent → HTTP Request + x402 Payment Header → Server
                                                │
                                            Verify Payment
                                                │
                                            ✅ Valid → Serve Content
                                            ❌ Invalid → 402 Payment Required

The Flow

1. Agent makes HTTP request to a paid endpoint
2. Server returns 402 Payment Required with pricing info
3. Agent signs an EIP-712 payment authorization
4. Agent retries with X-402-Payment header
5. Server verifies signature and serves content
6. Payment settles on-chain (batched for efficiency)

Payment Header

X-402-Payment: {
  "version": "1",
  "sender": "0xAgentAddress",
  "amount": "0.001",
  "token": "USDs",
  "chain": "arbitrum",
  "signature": "0x...",
  "nonce": 42,
  "expiry": 1735689600
}

Supported Tokens

For Agents (Paying)

Setup

import { X402Client } from '@x402/client';

const client = new X402Client({
  privateKey: process.env.AGENT_PRIVATE_KEY,
  defaultToken: 'USDs',
  defaultChain: 'arbitrum',
  maxPaymentPerRequest: '0.01',  // Safety limit
  maxPaymentPerHour: '1.00'       // Hourly limit
});

Making Paid Requests

// Automatic payment handling
const response = await client.fetch('https://api.example.com/data', {
  method: 'GET'
});
// If 402 → signs payment → retries → returns data

Budget Controls

const client = new X402Client({
  budget: {
    perRequest: '0.01',    // Max per single request
    perHour: '1.00',       // Max per hour
    perDay: '10.00',       // Max per day
    perMonth: '100.00',    // Max per month
    whitelist: ['api.chat.sperax.io', 'api.coingecko.com']  // Trusted domains
  }
});

For Servers (Receiving)

Express Middleware

import { x402Middleware } from '@x402/server';

app.use('/api/premium/*', x402Middleware({
  price: '0.001',      // Price per request in USDs
  token: 'USDs',
  chain: 'arbitrum',
  recipient: '0xYourAddress'
}));

app.get('/api/premium/data', (req, res) => {
  res.json({ data: 'premium content' });
});

Dynamic Pricing

app.use('/api/data/*', x402Middleware({
  pricing: (req) => {
    if (req.path.includes('historical')) return '0.005';
    if (req.path.includes('realtime')) return '0.01';
    return '0.001';
  },
  token: 'USDs',
  chain: 'arbitrum'
}));

MCP Integration

x402 is native in the MCP ecosystem:

{
  "mcpServers": {
    "premium-data": {
      "command": "npx",
      "args": ["@premium/mcp-server"],
      "x402": {
        "wallet": "0xAgentWallet",
        "maxBudget": "1.00",
        "token": "USDs"
      }
    }
  }
}

Use Cases

Sperax + x402

USDs is ideal for x402 payments:

• Auto-yield: Agent wallets holding USDs earn yield while waiting
• Low gas: Arbitrum L2 means sub-cent transaction costs
• Stable: Always $1, no price volatility risk

Links

• Spec: https://www.x402.org
• GitHub: https://github.com/nirholas/x402
• npm: https://www.npmjs.com/package/@x402/client
• EIP-712: https://eips.ethereum.org/EIPS/eip-712
• Sperax USDs: https://app.sperax.io