x402 Protocol Payments
x402 is Coinbase's open standard for HTTP-native payments. It lets AI agents pay for API access automatically — the server returns HTTP 402, the agent's wallet signs and pays, and a facilitator settles on-chain.
When to use x402 vs REST API
- x402 — Pay-per-request API access for AI agents. The agent wallet auto-pays on each HTTP call.
- REST API — Invoice-style payments, custom amounts, webhook-driven flows, SaaS billing.
How x402 Works
Agent Server Facilitator
| | |
|--- GET /api/weather -->| |
| | |
|<-- 402 + PAYMENT-REQUIRED header --------------|
| (price, network, payTo address) |
| | |
| [Agent wallet signs payment payload] |
| | |
|--- GET /api/weather + PAYMENT-SIGNATURE ------->|
| | |
| |--- verify + settle --->|
| |<-- settlement OK ------|
| | |
|<-- 200 + weather data -| |
Server Setup (Protect Your Routes)
Use withX402 from x402-next to wrap any Next.js API route with x402 payment requirements.
1. Install Dependencies
npm install x402-next @x402/core @x402/evm
2. Protect an API Route
// app/api/premium-data/route.ts
import { NextRequest, NextResponse } from "next/server"
import { withX402 } from "x402-next"
const handler = async (req: NextRequest) => {
return NextResponse.json({ data: "premium content" })
}
export const GET = withX402(
handler,
"0xYourWorkspaceWallet", // payTo address
{
price: "$0.01", // USD price per request
network: "base-sepolia", // or "base" for mainnet
config: {
description: "Premium data access",
},
},
{ url: "https://x402.org/facilitator" }
)
Route Config Options
| Field | Type | Description |
|---|---|---|
price | string | USD price, e.g. "$0.01" |
network | string | "base-sepolia" (testnet) or "base" (mainnet) |
config.description | string | What the endpoint does |
Client Setup (Agent Auto-Pay)
Agents use @x402/fetch to wrap fetch — it automatically handles 402 responses by signing and sending payments from the agent's wallet.
Install
npm install @x402/fetch @x402/core @x402/evm
Agent Code
import { wrapFetch } from "@x402/fetch"
import { CdpClient } from "@coinbase/cdp-sdk"
const cdp = new CdpClient({ apiKeyId: "...", apiKeySecret: "..." })
const account = await cdp.evm.getOrCreateAccount({ name: "my-agent" })
// Wrap fetch with x402 auto-pay
const x402Fetch = wrapFetch(fetch, account)
// Now any 402 response is automatically paid
const res = await x402Fetch(
"https://paydirect.com/api/x402/weather"
)
const data = await res.json()
console.log(data) // { source: "PayDirect x402 Weather API", data: {...} }
PayDirect x402 Demo Endpoints
PayDirect provides two x402-protected demo endpoints you can test against:
| Endpoint | Price | Description |
|---|---|---|
GET /api/x402/weather | $0.001 | Random weather data |
GET /api/x402/content?topic=AI | $0.01 | AI-generated content |
Both endpoints use Base Sepolia testnet, so you can test with testnet USDC.
How x402 Payments Flow Through PayDirect
- Agent calls x402-protected route with
PAYMENT-SIGNATUREheader x402-nextmiddleware verifies the payment via Coinbase's facilitator- Facilitator settles the payment on-chain (tokens move to the
payToaddress) - PayDirect's payment bridge records the settlement in the dashboard
- The route handler executes and returns the API response
Networks
| Environment | x402 Network | Chain ID | USDC Address |
|---|---|---|---|
| Sandbox | base-sepolia | 84532 | 0x036CbD53842c5426634e7929541eC2318f3dCF7e |
| Live | base | 8453 | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |