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

Token	Chains	Best For
USDs	Arbitrum	Sperax ecosystem payments
USDC	Ethereum, Arbitrum, Base	Standard payments
USDT	Ethereum, Arbitrum	Alternative stablecoin

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
  }
});