x402 Payments

Agent Swarm includes built-in support for x402 payments, allowing agents to automatically pay for x402-gated API endpoints using USDC on Base.

How It Works

x402 is an open payment protocol that uses the HTTP 402 "Payment Required" status code for native micropayments over HTTP. When an agent calls an x402-gated API:

1. The initial request returns a 402 Payment Required response
2. The x402 client automatically signs a USDC payment authorization (EIP-3009)
3. The request is retried with the payment signature
4. The API returns the response — payment is settled on-chain asynchronously

The entire flow is gasless for the payer and completes in ~1.5–2 seconds.

Setup

Choose a Signer

Two signer backends are supported:

The signer is auto-detected based on which credentials are set. Use X402_SIGNER_TYPE to override.

Openfort Setup

1. Create an account at openfort.xyz
2. Get your API key and wallet secret
3. Set environment variables:

OPENFORT_API_KEY=sk_test_...
OPENFORT_WALLET_SECRET=<base64-encoded-p256-key>

Viem Setup

1. Generate a wallet (e.g., cast wallet new)
2. Get test USDC from the CDP Faucet on Base Sepolia
3. Set environment variable:

EVM_PRIVATE_KEY=0x...

No ETH needed — x402 payments are gasless for the payer.

Spending Limits

Configure via environment variables or programmatically:

See the full environment variables reference.

Usage

Drop-in Fetch Replacement

import { createX402Fetch } from "@/x402";

const paidFetch = createX402Fetch();

// Use like normal fetch — 402 payments are automatic
const response = await paidFetch("https://api.example.com/paid-endpoint");
const data = await response.json();

Full Client with Spending Tracking

import { createX402Client } from "@/x402";

const client = await createX402Client();

// Make paid requests
const response = await client.fetch("https://api.example.com/paid-endpoint");

// Check spending
const summary = client.getSpendingSummary();
console.log(`Spent today: $${summary.todaySpent.toFixed(2)}`);
console.log(`Remaining: $${summary.dailyRemaining.toFixed(2)}`);

Custom Configuration

import { createX402Client } from "@/x402";

const client = await createX402Client({
  maxAutoApprove: 0.50,   // Max $0.50 per request
  dailyLimit: 5.00,       // Max $5.00 per day
  network: "eip155:8453", // Base mainnet
});

CLI

Test x402 payments from the command line:

# Check configuration
bun src/x402/cli.ts check

# Make a paid request
bun src/x402/cli.ts fetch https://api.example.com/paid-endpoint

# View spending summary
bun src/x402/cli.ts status

Module Structure

src/x402/
├── index.ts              # Public API re-exports
├── client.ts             # Payment client with spending limits
├── config.ts             # Environment variable loading
├── openfort-signer.ts    # Openfort backend wallet signer
├── spending-tracker.ts   # In-memory spending tracking
└── cli.ts                # CLI for testing payments

Security

• Use burner wallets — load only small amounts of working capital
• Set spending limits — configure per-request and daily limits
• Never commit private keys — always use environment variables
• Testnet first — use Base Sepolia (eip155:84532) during development
• Openfort for production — keys managed in a TEE, not on disk

Further Reading

• x402 Protocol Specification
• x402 Buyer Quickstart
• x402.org

Related

• Environment Variables — x402 configuration variables
• Architecture Overview — How the x402 module fits into the system