Ask402

How do I accept x402 payments on my API?

Short answer

Add x402 middleware to your server, tell it which routes cost what and which wallet address receives the money, and point it at a facilitator that verifies and settles payments. Official middleware exists for Express, Next.js, Hono, Fastify, FastAPI, Flask and Go. Start on a test network, then switch to a production facilitator.

What you need

  • A wallet address to receive payments. You only need the address on the server, not its private key.
  • A facilitator to verify and settle payments. See what a facilitator is.
  • Middleware for your framework.

A minimal Express server

This follows the official quickstart. It charges $0.001 in USDC for GET /weather on Base Sepolia, a test network.

import express from "express";
import { paymentMiddleware, x402ResourceServer } from "@x402/express";
import { ExactEvmScheme } from "@x402/evm/exact/server";
import { HTTPFacilitatorClient } from "@x402/core/server";

const app = express();
const payTo = "0xYourEvmAddress";

// Test facilitator. Replace with a production facilitator before going live.
const facilitator = new HTTPFacilitatorClient({ url: "https://x402.org/facilitator" });

app.use(
  paymentMiddleware(
    {
      "GET /weather": {
        accepts: [{ scheme: "exact", price: "$0.001", network: "eip155:84532", payTo }],
        description: "Weather data",
        mimeType: "application/json",
      },
    },
    new x402ResourceServer(facilitator).register("eip155:84532", new ExactEvmScheme()),
  ),
);

app.get("/weather", (req, res) => res.json({ weather: "sunny", temperature: 70 }));
app.listen(4021);

Install with npm install @x402/express @x402/core @x402/evm. Unpaid requests to /weather now get a 402 with the price. Paid requests reach your handler.

The quickstart has the same example for Next.js, Hono, Fastify, FastAPI, Flask and Go, and shows how to add Solana and other networks by listing more entries in accepts.

Going live

  1. Switch facilitator. x402.org/facilitator is for test networks only. Choose a production one from the facilitator directory and check that it supports your networks.
  2. Switch network. Change eip155:84532 (Base Sepolia) to a real network such as eip155:8453 (Base).
  3. Offer more than one network if you can. Buyers hold funds in different places, and each extra entry in accepts widens who can pay you.
  4. Write a clear description. Agents read it to decide whether your endpoint does what they need.

Things that go wrong

  • Browser clients cannot see the price. The three x402 headers are not exposed to browser code by default. Add PAYMENT-REQUIRED and PAYMENT-RESPONSE to Access-Control-Expose-Headers, and PAYMENT-SIGNATURE to Access-Control-Allow-Headers.
  • A proxy strips or truncates headers. The price is in a header, and with many offers it gets long. Make sure your proxy or CDN passes large headers through.
  • The price is cached. A cached 402, or a cached paid response served to a non-payer, breaks the flow. Mark paid routes as not cacheable.
  • Free and paid mixed on one route. Decide per route and method. GET /weather and POST /weather are configured separately.

Check your work

Paste your endpoint into the 402 checker. It shows exactly what a client sees: the version, each offer, the price in dollars where the token is recognized, and warnings such as a test network on a production address.

Being found

Once you are live, buyers and agents need to discover you. See the Bazaar and how to get listed.

Sources

Facts checked against these sources on . Protocols change, so the official specification wins if it disagrees with this page. Read this page as Markdown.

Who writes this. Ask402 is published by Havok Holdings LLC, which also runs Agent402, one of the x402 services covered here. Agent402 is labelled wherever it appears. Everything else is described from each project’s own documentation, and nobody pays to be listed.