x402 in Node.js

Add x402 payments to a Node API with the official packages — gate an Express (or Hono/Next.js) route behind USDC on the server, and pay endpoints automatically on the client.

Which package should you use?

Install

npm install x402-express x402-axios

Server (Express)

The route returns HTTP 402 until a USDC payment is made, then runs normally.

// Express server that charges for a route
import express from "express";
import { paymentMiddleware } from "x402-express";

const app = express();

// Gate routes behind a USDC payment
app.use(paymentMiddleware(
  "0xYourReceivingWalletAddress",
  {
    "GET /weather": {
      price: "$0.01",
      network: "base-sepolia",   // use "base" in production
    },
  },
));

app.get("/weather", (req, res) => {
  // Runs only after a valid payment
  res.json({ city: "Tokyo", forecast: "sunny" });
});

app.listen(3000);

Client (axios)

Wrap the client once and it pays on its own — the same pattern an AI agent uses.

// A Node client that pays automatically
import axios from "axios";
import { withPaymentInterceptor } from "x402-axios";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount("0xYOUR_PRIVATE_KEY");

const api = withPaymentInterceptor(axios.create(), account);

const r = await api.get("http://localhost:3000/weather");
console.log(r.data); // { city: "Tokyo", ... }

Client (native fetch)

No axios dependency? x402-fetch wraps the built-in fetch instead.

// Prefer fetch over axios? x402-fetch wraps the native fetch API instead.
import { wrapFetchWithPayment } from "x402-fetch";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount("0xYOUR_PRIVATE_KEY");
const fetchWithPayment = wrapFetchWithPayment(fetch, account);

const res = await fetchWithPayment("http://localhost:3000/weather");
const data = await res.json(); // { city: "Tokyo", ... }

Server (Hono)

Not on Express? x402-hono applies the identical pattern to Hono routes.

// Same pattern on Hono instead of Express
import { Hono } from "hono";
import { paymentMiddleware } from "x402-hono";

const app = new Hono();

app.use(paymentMiddleware(
  "0xYourReceivingWalletAddress",
  { "GET /weather": { price: "$0.01", network: "base-sepolia" } },
));

app.get("/weather", (c) => c.json({ city: "Tokyo", forecast: "sunny" }));

export default app;

Troubleshooting

Get amounts right with the free base-unit converter.

Real Node/TypeScript x402 projects

From the 671 JavaScript/TypeScript projects we track that reference x402 — stars live from GitHub.

Frequently asked questions

More: all SDKs · Python · Go · Rust · examples