x402 Agent Payments

This skill teaches Claude to build and consume the x402 protocol: HTTP servers that answer with 402 Payment Required and a machine-readable price quote, and clients (including autonomous agents) that pay those quotes in USDC on Base or Solana through Coinbase's x402 facilitator. It is for developers monetizing APIs per-request, and for anyone giving an agent a wallet to buy data, compute, or tool calls without API keys or human-in-the-loop checkout.

When to use it

• You want to charge per API call (e.g. $0.001 per inference, per scrape, per report) instead of issuing keys and invoices.
• You are building an agent that must pay for third-party endpoints on its own.
• You need gasless USDC settlement so callers don't hold ETH for gas.
• You're integrating x402-express, Next.js, or Hono middleware and need the verify/settle loop wired correctly.

How it works

The protocol is a two-pass HTTP exchange. The server returns 402 with a JSON body containing a PaymentRequirements object: scheme ("exact"), network (base, base-sepolia, solana), maxAmountRequired (atomic units), asset (USDC contract), payTo, and resource. The client constructs an X-PAYMENT header — a base64 payment payload — and retries. The server forwards it to a facilitator (https://x402.org/facilitator or Coinbase's hosted one via @coinbase/x402) calling /verify then /settle, and returns the resource plus an X-PAYMENT-RESPONSE header with the settlement tx.

On Base, payment uses EIP-3009 transferWithAuthorization — the client signs an authorization, the facilitator submits it, so the payer spends no gas. Solana uses its own settlement path. Server middleware comes from x402-express, x402-next, and x402-hono; clients use x402-fetch (wrapFetchWithPayment) or the x402-axios interceptor.

curl -fsSL --create-dirs -o ~/.claude/skills/x402-agent-payments/SKILL.md https://claudeskil.com/skills/x402-agent-payments/SKILL.md
npm i x402-express x402-fetch viem

// Server: gate a route for $0.01 USDC on Base
import { paymentMiddleware } from "x402-express";
app.use(paymentMiddleware(
  "0xYourReceivingAddress",
  { "GET /weather": { price: "$0.01", network: "base" } },
  { url: "https://x402.org/facilitator" }
));

// Client: an agent pays automatically
import { wrapFetchWithPayment } from "x402-fetch";
import { privateKeyToAccount } from "viem/accounts";
const account = privateKeyToAccount(process.env.PRIVATE_KEY);
const fetchWithPay = wrapFetchWithPayment(fetch, account);
const res = await fetchWithPay("https://api.example.com/weather");

Tips & gotchas

• Prices are quoted as dollar strings ("$0.01"); the middleware converts to USDC's 6 decimals. Don't pass raw atomic amounts where a $ string is expected.
• Test on base-sepolia first and fund the payer with testnet USDC from Circle's faucet — the wrong network in PaymentRequirements produces silent verify failures.
• The signed EIP-3009 authorization carries validAfter/validBefore; clock skew on the client can make payments expire before settlement.
• The facilitator settles on-chain, so the second request blocks until the tx confirms — set generous client timeouts.

FAQ

Does the payer need ETH for gas? No on Base. transferWithAuthorization is gasless for the payer; the facilitator pays gas and is reimbursed in the transfer.

Can I run without Coinbase? Yes. The facilitator interface is open; use the public x402.org/facilitator or self-host. Coinbase's @coinbase/x402 is one hosted option, convenient for mainnet.

What does the agent receive back? The original resource body, plus X-PAYMENT-RESPONSE (base64) decoding to the settlement result including the transaction hash for reconciliation.