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. 1.Install

    npm install @x402/next @x402/core @x402/evm
  2. 2.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. 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. 4.Go live on Base

    1. Change the network to eip155:8453 (Base mainnet) in both register() and accepts.
    2. 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.
    3. Set PAY_TO_ADDRESS to a wallet you control on Base; that is where the USDC lands.
    4. 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. 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. 2.Install

    npm install @x402/fetch @x402/evm viem
  3. 3.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. 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

  1. Every term on this page: x402 glossary.
  2. The protocol step by step: How x402 works.
  3. Daily grades for every listed seller: x402 Conformance Index.
  4. 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.