For x402 sellers and agent builders
x402 quickstart
Two samples, each a few lines: charge for an API route, or pay for one. Both run on the published @x402 packages (version 2.28). We ran both on 11/19/2026 before publishing: the seller route answered a valid 402 on the free testnet facilitator, and the buyer script signed a payment that our live API checked and refused for an empty wallet. New to the protocol? Read how x402 works first.
Sell: charge $0.01 for a Next.js route
Your app becomes the resource server. Start on Base Sepolia: test USDC is free from Circle's faucet and the x402.org facilitator needs no account.
1.Install
npm install @x402/next @x402/core @x402/evm2.Wrap the route handler
Set PAY_TO_ADDRESS to your payout wallet. The price is in dollars; the package turns $0.01 into 10000, the amount in USDC's six-decimal units.
// app/api/premium/route.ts (Next.js App Router) import { NextRequest, NextResponse } from "next/server"; import { withX402 } from "@x402/next"; import { HTTPFacilitatorClient, x402ResourceServer } from "@x402/core/server"; import { ExactEvmScheme } from "@x402/evm/exact/server"; // The facilitator verifies and settles payments for you. x402.org's is free on testnet. const server = new x402ResourceServer( new HTTPFacilitatorClient({ url: "https://x402.org/facilitator" }), ).register("eip155:84532", new ExactEvmScheme()); // Base Sepolia (testnet) const handler = async (_req: NextRequest) => { return NextResponse.json({ data: "your paid response" }); }; // Unpaid request: 402 with a PAYMENT-REQUIRED header. Paid request: verify, run the // handler, and settle ONLY if it answered below 400, so a failed call is never charged. export const GET = withX402( handler, { accepts: [ { scheme: "exact", price: "$0.01", network: "eip155:84532", payTo: process.env.PAY_TO_ADDRESS as `0x${string}`, // your wallet; receives the USDC }, ], description: "One premium data call", mimeType: "application/json", }, server, );3.Check the 402
Start the dev server and ask without paying. A valid 402 carries everything a buyer needs to pay you.
curl -i http://localhost:3000/api/premium # HTTP/1.1 402 Payment Required # payment-required: eyJ4NDAyVmVyc2lvbiI6Mi... (base64 JSON: price, network, payTo)4.Go live on Base
- Change the network to eip155:8453 (Base mainnet) in both register() and accepts.
- Point HTTPFacilitatorClient at a mainnet facilitator, for example Coinbase CDP (needs a CDP API key) or another facilitator that lists eip155:8453 at its /supported endpoint.
- Set PAY_TO_ADDRESS to a wallet you control on Base; that is where the USDC lands.
- Check your live 402 with the 402 Inspector before you list the route anywhere.
Network names follow CAIP-2. withX402 settles only when your handler answers below 400, so a request that fails is never charged.
Buy: pay for a real endpoint from Node
The script below buys 7 days of event risk from our API. The client signs an EIP-3009 authorization for the exact price; the facilitator pays the gas (gas sponsorship), so the wallet needs only USDC.
1.See the price first (free)
curl -i "https://www.blockchainiq.co/api/x402/v1/event-risk?days=7" # HTTP/1.1 402 Payment Required # payment-required: eyJ4NDAyVmVyc2lvbiI6Mi... (the price, before you pay anything)2.Install
npm install @x402/fetch @x402/evm viem3.Pay and read the receipt
spendControls is the safety catch: the client refuses any single payment above the cap, so a mispriced or hostile 402 cannot take more. Keep the key in an environment variable, and fund the wallet with only what you mean to spend.
// buy.mjs (Node 20+, run: AGENT_PRIVATE_KEY=0x... node buy.mjs) import { privateKeyToAccount } from "viem/accounts"; import { wrapFetchWithPayment, x402Client, decodePaymentResponseHeader } from "@x402/fetch"; import { ExactEvmScheme } from "@x402/evm/exact/client"; // A wallet holding a little USDC on Base. The payer needs no ETH: the facilitator pays gas. const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY); const client = x402Client.fromConfig({ schemes: [{ network: "eip155:*", client: new ExactEvmScheme(account) }], // Refuse any single payment above $2.00 (our dearest call, the Analyst pack, is $2.00). spendControls: { maxAmountPerPayment: 2.0 }, }); const payFetch = wrapFetchWithPayment(fetch, client); // First request gets 402 + PAYMENT-REQUIRED; the wrapper signs a USDC authorization // for exactly that amount and retries with PAYMENT-SIGNATURE. const res = await payFetch("https://www.blockchainiq.co/api/x402/v1/event-risk?days=7"); console.log(res.status); if (res.ok) { console.log((await res.json()).data); // Receipt: payer, network and the transaction hash. console.log(decodePaymentResponseHeader(res.headers.get("payment-response"))); }4.Prefer a tool to code?
Our MCP server gives Claude, Cursor and other MCP clients the same paid calls, capped at $2.00 per call. Setup is on Blockchain IQ for agents, with the full catalogue and prices.
Go further
- Every term on this page: x402 glossary.
- The protocol step by step: How x402 works.
- Daily grades for every listed seller: x402 Conformance Index.
- Package docs: coinbase/x402 on GitHub.
General education, not investment, legal or tax advice. Never put a private key in code or a repository. Samples tested 11/19/2026 with @x402 packages 2.28; check the package docs if a newer version changes an API.