x402 Tutorial

Implement x402 from scratch and have a paid API endpoint running in five steps. Copyable server + client code, tested for free on a testnet — no private key on your server.

Step 1 — Create the project

mkdir x402-demo && cd x402-demo
npm init -y
npm install express @x402/express

Step 2–3 — Add the paywall & facilitator

One middleware turns a normal route into a paid one. The route handler only runs after a valid USDC payment; everything else returns HTTP 402.

// server.js
import express from "express";
import { paymentMiddleware } from "@x402/express";

const app = express();

// Charge $0.01 in USDC for GET /weather
app.use(
  paymentMiddleware(
    "0xYourReceivingWalletAddress",       // where the money lands
    {
      "GET /weather": {
        price: "$0.01",
        network: "base-sepolia",          // testnet first
      },
    },
    { url: "https://x402.org/facilitator" } // hosted facilitator
  )
);

app.get("/weather", (req, res) => {
  // This only runs AFTER a valid payment
  res.json({ city: "Tokyo", forecast: "sunny", temp_c: 24 });
});

app.listen(3000, () => console.log("http://localhost:3000"));

Step 4 — Test it

# 1. No payment -> you get HTTP 402 with payment details
curl -i http://localhost:3000/weather
# HTTP/1.1 402 Payment Required
# { "accepts": [ { "scheme": "exact", "network": "base-sepolia", ... } ] }

# 2. An x402-aware client (or the @x402/fetch wrapper) signs a USDC
#    payment, retries, and gets a 200 with the JSON body.

Here's a tiny client that pays automatically — the same pattern an AI agent uses:

// client.js  — an agent/script that pays automatically
import { wrapFetchWithPayment } from "@x402/fetch";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { baseSepolia } from "viem/chains";

const account = privateKeyToAccount(process.env.PRIVATE_KEY);
const wallet = createWalletClient({ account, chain: baseSepolia, transport: http() });

const fetchWithPay = wrapFetchWithPayment(fetch, wallet);
const res = await fetchWithPay("http://localhost:3000/weather");
console.log(await res.json()); // { city: "Tokyo", ... }

Step 5 — Go live

Frequently asked questions

Next: starter kits & demos · SDKs by language · facilitators · gateways