x402 Paywall Kit

Basic: Pay for Premium API Data

Agent calls api.example.com/premium, gets 402, pays 0.10 USDC, gets data:

const agentFetch = createAgentFetch({
  walletPrivateKey: process.env.X402_WALLET_PRIVATE_KEY as 0x${string},
  network: "eip155:8453",
  policy: {
    maxPerRequest: "0.50",
    maxDailySpend: "5.00",
    allowedNetworks: ["eip155:8453"],
    allowedAssets: ["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"],
    requireHumanApproval: false,
  },
});
const response = await agentFetch("https://api.example.com/premium/weather");
// First request returns 402 -> agent auto-pays 0.10 USDC -> retries -> gets 200 with data

Domain-Restricted: Only Pay Trusted APIs

const agentFetch = createAgentFetch({
  walletPrivateKey: process.env.X402_WALLET_PRIVATE_KEY as 0x${string},
  network: "eip155:8453",
  policy: {
    maxPerRequest: "1.00",
    maxDailySpend: "20.00",
    allowedNetworks: ["eip155:8453"],
    allowedAssets: ["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"],
    domainAllowlist: ["api.trusted-service.com", "data.partner.io"],
    requireHumanApproval: false,
  },
});

Testnet Development

const agentFetch = createAgentFetch({
  walletPrivateKey: process.env.X402_WALLET_PRIVATE_KEY as 0x${string},
  network: "eip155:84532",  // Base Sepolia testnet
  policy: {
    maxPerRequest: "10.00",
    maxDailySpend: "100.00",
    allowedNetworks: ["eip155:84532"],
    allowedAssets: ["0x036CbD53842c5426634e7929541eC2318f3dCF7e"], // USDC on Base Sepolia
    requireHumanApproval: false,
  },
});

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | X402_WALLET_PRIVATE_KEY | Yes | Hex private key (with 0x prefix) of a wallet funded with USDC on Base |

Policy Configuration

The policy object controls what the agent is allowed to spend:

interface X402Policy {
  maxPerRequest: string;        // Max USDC per single request (e.g., "1.00")
  maxDailySpend: string;        // Max USDC per day (e.g., "10.00")
  allowedNetworks: string[];    // CAIP-2 networks (e.g., ["eip155:8453"])
  allowedAssets: string[];      // Token contract addresses
  domainAllowlist?: string[];   // Only pay these domains (optional)
  domainDenylist?: string[];    // Never pay these domains (optional)
  requireHumanApproval: boolean;
}

Supported Networks

| Network | CAIP-2 ID | USDC Address | |---------|-----------|--------------| | Base (mainnet) | eip155:8453 | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 | | Base Sepolia (testnet) | eip155:84532 | 0x036CbD53842c5426634e7929541eC2318f3dCF7e |

Full Config Reference

interface AgentFetchConfig {
  walletPrivateKey: Hex;        // From env: X402_WALLET_PRIVATE_KEY
  policy: X402Policy;           // Spending rules
  network: Network;             // CAIP-2 format (e.g., "eip155:8453")
  spendFilePath?: string;       // Daily spend persistence (default: ".x402/daily-spend.json")
  logFilePath?: string;         // Payment log file path
  rpcUrl?: string;              // Custom JSON-RPC URL
  tokenDecimals?: number;       // Token decimals (default: 6 for USDC)
}