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
- Switch facilitator.
x402.org/facilitatoris for test networks only. Choose a production one from the facilitator directory and check that it supports your networks. - Switch network. Change
eip155:84532(Base Sepolia) to a real network such aseip155:8453(Base). - Offer more than one network if you can. Buyers hold funds in different places, and each extra entry in
acceptswidens who can pay you. - 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-REQUIREDandPAYMENT-RESPONSEtoAccess-Control-Expose-Headers, andPAYMENT-SIGNATUREtoAccess-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 /weatherandPOST /weatherare 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
- Quickstart for sellers, x402 documentation
- Facilitator list, x402 documentation
- x402 version 2 HTTP transport specification
- Server examples, x402 repository
Facts checked against these sources on . Protocols change, so the official specification wins if it disagrees with this page. Read this page as Markdown.
Related questions
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.