How to Accept Agent Payments on Your API (x402)

AI agents are starting to pay for data, tools, and APIs on their own — in stablecoins, over HTTP, using a protocol called x402. If you run an API, a scraper, a model endpoint, or any service, you can let agents pay you per call. Here's the whole thing, plainly.

How x402 works (30 seconds)

1. An agent requests your paid endpoint.
2. Your server replies HTTP 402 Payment Required with a little JSON: how much, which token, which chain, and your receiving wallet.
3. The agent's software signs a stablecoin (usually USDC) payment and retries the request with an X-PAYMENT header.
4. A facilitator verifies the payment; your server returns the data. Settlement lands on-chain in seconds. No login, no invoice, no chargebacks.

That's it. You're adding a paywall machines can navigate by themselves.

What you need

• A receiving wallet (a "payTo" address) — just a public address where you get paid. You never share a private key.
• A facilitator — the service that verifies/settles payments so you don't have to touch a blockchain. For testing, the free https://x402.org/facilitator works on Base Sepolia + Solana devnet. To go live, use a mainnet facilitator such as Coinbase's CDP facilitator (free for Base, Solana, Stellar).
• The middleware for your framework.

Step 1 — Add the middleware

x402 ships as one-line middleware for most stacks (Express, Hono, Next.js, plus Python and Go). Example in Express:

npm install x402-express

import express from "express";
import { paymentMiddleware } from "x402-express";

const app = express();

app.use(paymentMiddleware(
  "0xYourReceivingWalletAddress",                       // where you get paid
  { "GET /premium": { price: "$0.01", network: "base" } }, // which routes cost what
  { url: "https://x402.org/facilitator" }               // testnet; swap for a mainnet facilitator to go live
));

app.get("/premium", (req, res) => res.json({ data: "the paid thing" }));
app.listen(3000);

That's the whole integration: any request to /premium without payment gets a 402; with a valid payment, it passes through. (Exact package names and options evolve — always confirm against the official Quickstart for Sellers.)

Step 2 — Test on a testnet

Point the facilitator at https://x402.org/facilitator, use a Base Sepolia test wallet, and hit your endpoint with an x402-aware client (see our companion guide for the agent side). You should get a 402, then a paid 200.

Step 3 — Go live and get discovered

• Swap the testnet facilitator for a mainnet one (Coinbase CDP is free for Base/Solana/Stellar) and set a real payTo wallet.
• Registering with a facilitator's Bazaar / discovery endpoint means your service becomes enumerable by agents and by directories — including ours. That's how agents find you.

Step 4 — Watch it settle

Once real payments land, you can see them on-chain. The Agent Almanac Economy scoreboard measures exactly this — real settled volume per provider wallet — so you can watch your endpoint show up in the actual data.

Two honest things worth knowing

• Most agent payments are tiny. The typical payment today is well under 10¢ — price for a swarm of micro-calls, not big-ticket purchases.
• Being real matters. Of tens of thousands of listed services, only a few hundred have ever been paid. Ship something agents actually want, and you're already ahead of the long tail of dead listings.

Next: the other side — How to make your AI agent pay for things (x402). Or see the live state of the economy you're joining on the scoreboard.