Why monapi?

The x402 protocol enables native HTTP payments — but integrating it requires understanding CAIP-2 network IDs, token contract addresses, facilitator configuration, scheme registration, and more.

monapi wraps all of that into a single function call. You provide your wallet address and a price. We handle the rest.

Before (raw x402):  7+ concepts, 30+ lines of boilerplate
After  (monapi):  1 function, 3 lines of code

Quick Start

1. Install

npm install @monapi/sdk @x402/express

2. Add to your API

import express from "express";
import { monapi } from "@monapi/sdk";

const app = express();

app.use(monapi({
  wallet: "0xYourWalletAddress",
  price: 0.01, // $0.01 USDC per request
}));

app.get("/api/weather", (req, res) => {
  res.json({ forecast: "sunny" });
});

app.listen(3000);

3. Test it

curl -i http://localhost:3000/api/weather
# → 402 Payment Required
# Response includes payment instructions for x402-compatible clients

That's it. Any x402-compatible client (including AI agents with Coinbase wallets) can now pay and access your API automatically.

Frameworks

Express

import { monapi } from "@monapi/sdk";

// Global pricing — every route costs $0.01
app.use(monapi({
  wallet: process.env.MONAPI_WALLET,
  price: 0.01,
}));

// Per-route pricing
app.use(monapi({
  wallet: process.env.MONAPI_WALLET,
  routes: {
    "/api/weather":   0.01,
    "/api/forecast":  0.05,
    "/api/translate":  0.10,
  },
}));

Next.js

import { withMonapi } from "@monapi/sdk/next";
import { NextResponse } from "next/server";

async function handler(request: Request) {
  return NextResponse.json({ forecast: "sunny" });
}

export const GET = withMonapi(handler, {
  wallet: process.env.MONAPI_WALLET,
  price: 0.01,
});

For protecting multiple routes with a proxy:

import { monapiProxy } from "@monapi/sdk/next";

export default monapiProxy({
  wallet: process.env.MONAPI_WALLET,
  routes: {
    "/api/weather": 0.01,
    "/api/forecast": 0.05,
  },
});

MCP (Model Context Protocol)

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { monapiMcp } from "@monapi/sdk/mcp";
import { z } from "zod";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

const paid = monapiMcp({
  wallet: process.env.MONAPI_WALLET,
  price: 0.10,
});

server.tool("search", { query: z.string() },
  paid(async (args) => ({
    content: [{ type: "text", text: `Results for: ${args.query}` }],
  }))
);

Interactive Setup

Don't want to configure manually? Use the CLI:

npx monapi init

The wizard will:

1. Detect your framework (Express, Next.js, or MCP)
2. Help you set up a wallet (or guide you to create one via Coinbase)
3. Ask for your preferred network and pricing
4. Generate a .env file and a ready-to-paste code snippet

Configuration

All options with their defaults:

monapi({
  // Required
  wallet: "0x...",               // Your EVM wallet address (receives payments)

  // Pricing (one of these is required)
  price: 0.01,                   // Global price in USD for all routes
  routes: {                      // Or: per-route pricing in USD
    "/api/weather": 0.01,
    "/api/forecast": 0.05,
  },

  // Optional
  network: "base",               // "base" | "arbitrum" | "polygon" + testnets
  token: "USDC",                 // Payment token (currently only USDC)
  maxTimeoutSeconds: 60,         // Payment verification timeout (1–300)
  facilitatorUrl: "https://...", // Custom x402 facilitator URL
  onPayment: (event) => { ... }, // Callback after successful payment
});

Payment Events

Track successful payments with the onPayment callback:

app.use(monapi({
  wallet: process.env.MONAPI_WALLET,
  price: 0.01,
  onPayment: (event) => {
    console.log(`Received $${event.amount} from ${event.payer} on ${event.route}`);
    // event.txHash, event.network, event.timestamp also available
  },
}));

The callback is fire-and-forget — it never blocks the API response.

How It Works

1. Client calls your API
         ↓
2. monapi middleware intercepts the request
         ↓
3. No payment? → Returns 402 Payment Required
   (includes: price, token, network, wallet address)
         ↓
4. Client's x402 library pays automatically (USDC on Base)
         ↓
5. Client retries with payment proof in headers
         ↓
6. x402 facilitator verifies the payment
         ↓
7. ✅ Your API handler runs, client gets the response
         ↓
8. USDC arrives in your wallet

No monapi account needed. No dashboard, no API keys, no middleman. Payments go directly from the client to your wallet on the blockchain.

Zero gas fees for agents. USDC payments use EIP-3009 (transferWithAuthorization) — the x402 facilitator sponsors gas. Agents only need USDC, no native tokens like ETH or MATIC.

Networks & Tokens

All networks use sub-cent transaction fees, making them suitable for API micropayments.

| Network | Chain ID | Testnet | Use Case | |---|---|---|---| | base | EIP-155: 8453 | base-sepolia | Recommended default | | arbitrum | EIP-155: 42161 | arbitrum-sepolia | DeFi-heavy ecosystem | | polygon | EIP-155: 137 | polygon-amoy | High throughput |

| Token | Base | Arbitrum | Polygon | |---|---|---|---| | USDC | 0x8335... | 0xaf88... | 0x3c49... |

All contract addresses are native USDC issued by Circle. Verified against Circle's official documentation.

Start with a testnet (e.g. base-sepolia) for development. Switch to a mainnet when you're ready for production.

Wallet Setup

You need an EVM wallet that can receive USDC. We recommend Coinbase Smart Wallet:

1. Download the Coinbase app
2. Create an account (~2 minutes)
3. Copy your wallet address (starts with 0x)

Why Coinbase:

• Free, non-custodial wallet
• Native Base support (lowest transaction fees)
• Cash out USDC directly to your bank account
• Available in 100+ countries

Any EVM-compatible wallet works — MetaMask, Rainbow, etc.

Security

• No private keys — monapi only uses your public wallet address
• No data storage — The SDK runs entirely in your infrastructure
• No middleman — Payments go directly from client to your wallet
• Input validation — Wallet addresses, prices, routes, and URLs are rigorously validated
• HTTPS enforced — Facilitator URLs must use HTTPS (except localhost for development)
• Gas-free payments — Agents pay only USDC, gas is sponsored by the facilitator via EIP-3009

Found a vulnerability? See SECURITY.md.

Requirements

• Node.js 18+
• TypeScript 5+ (recommended, not required)
• One of: Express 4+, Next.js 13+, or MCP SDK 1+

Peer Dependencies

Install the x402 package for your framework:

# Express
npm install @monapi/sdk @x402/express

# Next.js
npm install @monapi/sdk @x402/next

# MCP
npm install @monapi/sdk @x402/mcp

FAQ

How do AI agents pay my API? AI agents with x402-compatible wallets (like Coinbase AgentKit) automatically detect the 402 response, pay the requested amount in USDC, and retry the request — all without human intervention. Agents only need USDC — no native tokens (ETH, MATIC) required. Gas fees are sponsored by the x402 facilitator.

What are the transaction fees? Base network fees are typically < $0.01 per transaction. There are no monapi fees.

Can I change prices without redeploying? Currently, prices are set in code. Dynamic pricing and a management dashboard are planned for a future release.

What happens if payment verification fails? The client receives a 402 response and can retry. Your API handler is never called until payment is verified.

Is this compatible with regular (non-paying) API clients? Any request without a valid payment header gets a 402 response. If you want some routes to be free, simply don't include them in the routes config.

Roadmap

• [ ] Dashboard with analytics and revenue tracking
• [ ] Tax reporting and compliance tools
• [ ] Solana support
• [ ] Dynamic pricing
• [ ] Trust scoring and KYA (Know Your Agent)

Contributing

We welcome contributions. Please open an issue first to discuss what you'd like to change.

License

MIT