---
name: x402-agent-payments
description: "Build x402 HTTP-402 paywalls and let agents pay APIs in USDC on Base and Solana via Coinbase's x402. Production x402: returning HTTP 402 with the PaymentRequirements JSON envelope, the X-PAYMENT header flow, and the facilitator verify/settle endpoints. Covers EIP-3009 transferWithAuthorization for gasless USDC on Base, Solana settlement, the x402-express/x402-fetch and Coinbase x402 SDK middleware, and wiring 402 retries into agent tool loops with spend caps and proof verification."
license: MIT
---

# 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.

```bash
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
```

```ts
// 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.