Documentation

x402Wrap lets API developers monetize their endpoints with stablecoin micropayments using the x402 protocol. Install the middleware package, wrap your routes, and track revenue from the dashboard.

Payments settle in USDC on Base L2 via the Coinbase facilitator. Self-custody — funds go directly to your wallet. No API keys or accounts needed from the payer side.

Quick Start

1. 1. Sign up at x402wrap.draftlabs.org/signup — enter your email, password, and payout wallet address.
2. 2. Get your API key from the dashboard overview page. Copy it.
3. 3. Install the package
   bash Copy

   npm install x402wrap

4. 4. Add the middleware
   ts Copy

   import express from "express";
   import { x402 } from "x402wrap";
   
   const app = express();
   app.use(x402({
     walletAddress: "0xYourWalletAddress",
     network: "base-sepolia",
     routes: {
       "GET /api/weather/:city": { price: "$0.001" },
     },
   }));
   app.get("/api/weather/:city", (req, res) => {
     res.json({ temp: 72, city: req.params.city });
   });
   app.listen(3000);

5. 5. Set the env var (optional, for dashboard tracking):
   bash Copy

   export X402_API_KEY=x402_live_your_key_here

That's it. Your endpoint now returns 402 Payment Required to unpaid requests and processes payments automatically.

Installation & Setup

npm install x402wrap express

Currently supports Express. Next.js, Hono, and Workers support coming soon.

Config-based (recommended)

Use x402() to define all paid routes in a single config object. The middleware matches incoming requests and enforces payment automatically.

import express from "express";
import { x402 } from "x402wrap";

const app = express();
app.use(x402({
  walletAddress: "0xYourWallet",
  network: "base-sepolia",
  apiKey: process.env.X402_API_KEY, // optional, for dashboard tracking
  routes: {
    "GET /api/weather/:city": { price: "$0.001", description: "Weather data" },
    "GET /api/joke": { price: "$0.0005", description: "Random joke" },
  },
}));

Per-route

Use x402pay() for fine-grained control — apply payment middleware to individual routes.

import { x402pay } from "x402wrap";

const pay = x402pay({
  walletAddress: "0xYour...",
  network: "base-sepolia",
});

app.get("/api/data", pay("$0.01"), (req, res) => {
  res.json({ data: "premium" });
});

Configuration

Both x402() and x402pay() accept the same config object:

Networks

How x402 Works

The entire payment happens inside a single HTTP request/response cycle:

No API keys needed from the payer. No accounts. No subscriptions. Just HTTP + stablecoins.

API Reference

x402(config)

Config-based Express middleware. Define all paid routes in a single config object. Returns Express middleware.

app.use(x402({
  walletAddress: "0x...",
  network: "base-sepolia",
  routes: {
    "GET /api/data": { price: "$0.001" },
    "POST /api/generate": { price: "$0.05", description: "Generate content" },
  },
}));

Returns: Express middleware (req, res, next) => void

x402pay(config)

Per-route middleware factory. Returns a function that takes a price and returns Express middleware for a single route.

const pay = x402pay({ walletAddress: "0x...", network: "base-sepolia" });
app.get("/route", pay("$0.01"), handler);

Returns: (price: string) => ExpressMiddleware

Dashboard

The dashboard at x402wrap.draftlabs.org/dashboard gives you full visibility into your monetized endpoints.

Overview

See total revenue, monetized calls, active endpoints, and plan usage at a glance. Revenue chart shows daily trends. Your API key is displayed here — copy it to your server's env vars.

Endpoints

Register your API routes with their pricing. Each endpoint tracks its own call count and revenue. Toggle endpoints on/off — paused endpoints return 200 without charging.

Transactions

Every settled payment is logged with the endpoint, payer address, amount, transaction hash, and status. Filter by date range and status. Transaction hashes link to the Base block explorer.

Settings

Manage your account, API key (reveal / regenerate), payout wallet address, and subscription plan.

Plans & Limits

When you hit your plan limit, the middleware returns 429 Too Many Requests. Upgrade anytime from Settings.

Environment Variables

All configuration is passed directly in code. The only optional environment variable is:

# Optional — for dashboard transaction tracking
X402_API_KEY=x402_live_your_key_here

The API key enables transaction tracking in the x402Wrap dashboard. It is not required for payment processing. Your wallet address and network are now passed directly in the middleware config.

Security

• •Zero dependencies — no supply chain risk. The package only uses the built-in fetch() API.
• •Self-custody — funds settle directly to your wallet via the Coinbase facilitator. x402Wrap never holds funds.
• •API key stays private — only sent to the x402Wrap dashboard API for validation. Never shared with third parties or the facilitator.
• •On-chain settlement — every payment is verified and settled on Base L2 by the Coinbase facilitator. Transaction hashes are logged for auditability.
• •Key rotation — regenerate your API key anytime from the dashboard. The old key stops working immediately.
• •Validation caching — API key validation is cached in-memory for 60 seconds to reduce latency. No external cache service involved.

Roadmap