mcp-pay

x402 micropayment billing for MCP tools. One wrapper. Any tool charges USDC per call. No Stripe. No signups. Agent-native.

Built by Brennan Zambo — extracted from the zambo.dev production MCP server running 28 tools with live x402 billing.

---

What it does

mcp-pay wraps any MCP tool handler with on-chain USDC payment verification. Before your tool runs, it verifies that the calling agent paid the required amount on Base mainnet — no Stripe account, no pricing page, no auth system.

An AI agent decides it needs your tool → pays $0.005 USDC on Base → includes the tx hash in the request header → your tool runs. The whole flow is autonomous. No human required.

This is the business model for the open source AI agent economy.

---

Install

npm install mcp-pay

Zero dependencies. Node.js 18+. Base mainnet only (currently).

---

Quick start

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { payable } from 'mcp-pay';
import { z } from 'zod';

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

// Wrap any tool handler with payable()
server.tool(
  'analyze_code',
  {
    description: 'AI code security audit',
    inputSchema: z.object({ code: z.string() }),
  },
  payable(
    { usdc: 0.005, wallet: '0xYOUR_WALLET_ADDRESS' },
    async ({ code }) => {
      const result = await runAudit(code);
      return { content: [{ type: 'text', text: result }] };
    }
  )
);

The agent calls the tool like this:

{
  "tool": "analyze_code",
  "arguments": {
    "code": "...",
    "_payment": "0xABC123...TX_HASH"
  }
}

Or via HTTP header: x-payment-hash: 0xABC123...TX_HASH

---

How payment verification works

1. Agent sends USDC to your wallet on Base mainnet
2. Agent includes the tx hash in _payment arg or x-payment-hash header
3. mcp-pay calls Base RPC nodes (no API key) to fetch the tx receipt
4. Finds the USDC Transfer log, checks to address and amount
5. ✅ Passes → runs your handler. ❌ Fails → throws 402 error with payment instructions

Verified tx hashes are cached in-process to allow retry calls without re-verifying.

---

API

payable(options, handler)

Wraps an MCP tool handler with payment verification.

payable(options: PayableOptions, handler: AsyncFunction): AsyncFunction

Options:

Field	Type	Default	Description
usdc	number	required	Amount in USDC (e.g. 0.005)
wallet	string	required	Your Base mainnet wallet address
network	'base'	'base'	Network (Base mainnet only currently)
headerName	string	'x-payment-hash'	Header carrying the tx hash
cache	boolean	true	Cache verified hashes to allow retries
rpcEndpoints	string[]	public endpoints	Override Base RPC nodes

---

verifyPayment(txHash, options)

Standalone payment verification. Use when you want to verify outside of an MCP handler.

const result = await verifyPayment('0xabc...', {
  usdc: 1.49,
  wallet: '0xYOUR_WALLET',
});

if (result.verified) {
  console.log(`Received $${result.amount} USDC`);
  console.log(`Block: ${result.blockNumber}`);
}

---

requirePayment(options)

Express/Fastify middleware for HTTP-level MCP servers.

app.post('/tools/analyze_code',
  requirePayment({ usdc: 0.005, wallet: '0xYOUR_WALLET' }),
  analyzeCodeHandler
);

Returns 402 Payment Required with payment instructions if no valid hash is present.

---

createPaymentRequest(options)

Generate a payment request object to return to clients.

const req = createPaymentRequest({ usdc: 0.005, wallet: '0x...' });
// {
//   protocol: 'x402',
//   network: 'base',
//   wallet: '0x...',
//   amount: 0.005,
//   currency: 'USDC',
//   headerName: 'x-payment-hash',
//   instructions: '...'
// }

---

Pricing ideas

Use case	Suggested price
Code audit	$0.005–$0.01
Web search	$0.001–$0.002
Data enrichment	$0.002–$0.005
Image generation	$0.01–$0.05
Complex analysis	$0.01–$0.10

---

USDC on Base

• USDC contract: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
• 6 decimal places (1 USDC = 1000000)
• Bridge USDC: bridge.base.org
• Buy on Base: app.uniswap.org

---

The x402 protocol

mcp-pay implements x402 — the HTTP 402 Payment Required standard for machine-to-machine micropayments. An AI agent can autonomously decide to pay for a tool, execute the payment, and retry — no human in the loop.

---

Related

• x402-base-verify — standalone USDC verification
• mcp-shield — security middleware for MCP servers
• agent-ledger — track every agent call and cost
• zambo.dev MCP server — 28 live tools using mcp-pay in production

---

License

MIT © Brennan Zambo