x402-paywall-pattern

x402 Paywall Pattern for MCP Servers and APIs

When this skill applies

Trigger when the user describes any of:

• "Add a paywall to my MCP server"
• "Charge per tool call"
• "Monetize my AI agent's API"
• "Accept USDC micropayments"
• "x402 implementation"
• "How do I get paid for my MCP tools?"

Architecture overview

x402 is Coinbase's HTTP 402 payment protocol. When a client (typically an AI agent) calls a paywalled endpoint without payment, the server returns HTTP 402 with a JSON manifest. The client signs an EIP-3009 transferWithAuthorization USDC transfer, embeds the signed payload in the X-Payment header, and retries.

Client → GET /api/my-tool
Server → 402 { amount, currency, recipient, facilitator, ... }
Client → signs EIP-3009 with USDC
Client → GET /api/my-tool, header X-Payment: <base64>
Server → verifies, executes, returns 200 with result

Reference implementation

// src/middleware/x402-paywall.ts
import type { NextApiRequest, NextApiResponse } from 'next';

const USDC_BASE = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
const FACILITATOR = process.env.X402_FACILITATOR_URL || 'https://x402.org/facilitator';

interface PaywallConfig {
  price: string;          // USDC amount, e.g. "0.01"
  recipient: string;      // Your wallet address
  description?: string;
}

export function withPaywall(handler: (req: NextApiRequest, res: NextApiResponse) => Promise<void>, config: PaywallConfig) {
  return async (req: NextApiRequest, res: NextApiResponse) => {
    const paymentHeader = req.headers['x-payment'] as string | undefined;

    if (!paymentHeader) {
      res.setHeader('Content-Type', 'application/json');
      return res.status(402).json({
        amount: config.price,
        currency: 'USDC',
        currencyAddress: USDC_BASE,
        chain: 'base',
        chainId: 8453,
        recipient: config.recipient,
        facilitator: FACILITATOR,
        description: config.description || 'Payment required',
      });
    }

    let proof: any;
    try {
      proof = JSON.parse(Buffer.from(paymentHeader, 'base64').toString('utf-8'));
    } catch {
      return res.status(400).json({ error: 'invalid_payment_header' });
    }

    if (!proof.signature || !proof.payer || !proof.amount) {
      return res.status(402).json({ error: 'invalid_payment' });
    }
    if (proof.expiresAt && proof.expiresAt < Date.now() / 1000) {
      return res.status(402).json({ error: 'payment_expired' });
    }

    return handler(req, res);
  };
}