GoldBean x402 Payment SDK

Add x402 USDC micropayments to your MCP Server in 5 lines of code.

Install

npm install @goldbean/x402-sdk

Quick Start

const express = require('express');
const { x402Middleware, createPricing } = require('@goldbean/x402-sdk');

const app = express();
app.use(express.json());

// 1. Set your wallet address
const WALLET = '0x7484b0bca25d2ee56e9b0535572d4cf44a047d98';

// 2. Define pricing
const prices = createPricing({
  'llm-chat':     { amount: '0.03', desc: 'AI Chat' },
  'image-gen':    { amount: '0.03', desc: 'Image Generation' },
  'web-search':   { amount: '0.01', desc: 'Web Search' },
  'ocr':          { amount: '0.01', desc: 'OCR' },
});

// 3. Add x402 payment middleware
app.use('/paid/', x402Middleware({
  wallet: WALLET,
  prices: prices,
  publicPaths: ['/paid/plans', '/paid/status'],
}));

// 4. Your API routes
app.get('/paid/llm-chat', (req, res) => {
  // req.paid === true here (payment verified)
  res.json({ response: 'Hello from AI!' });
});

app.listen(3000);

How It Works

1. Client requests /paid/your-endpoint without payment
2. SDK returns HTTP 402 Payment Required with payment details:

   {
     "x402": { "version": 2 },
     "payment_requirements": {
       "network": "eip155:8453",
       "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
       "amount": "0.01",
       "payTo": "0x7484b0bc..."
     }
   }

3. Client pays USDC on Base L2 and retries with either:
   • x-payment-signature header (EIP-3009 TransferWithAuthorization)
   • txHash in request body (on-chain transfer verification)
4. SDK verifies payment and forwards to your handler

Payment Methods

| Method | Header/Param | How It Works | |--------|-------------|--------------| | x402 (EIP-3009) | x-payment-signature | Signed off-chain authorization, verified via ethers.js | | On-chain tx | body.txHash | Direct USDC transfer, verified via Base RPC |

Both methods check: payment to your wallet, amount meets price, nonce not replayed.

Configuration

x402Middleware({
  wallet: '0x...',           // Your wallet (required)
  prices: {                  // Endpoint pricing (required)
    'my-api': { amount: '0.01', desc: 'My API' }
  },
  usdcAddress: '0x...',      // Default: USDC on Base
  chainId: 8453,             // Default: Base L2
  rpcUrl: 'https://...',     // Default: Base mainnet RPC
  publicPaths: ['/health'],   // Skip payment for these paths
  fiatOptions: {             // Show fiat options in 402 response
    paypal: { type: 'paypal', currency: 'USD' },
    alipay: { type: 'fiat', currency: 'CNY' },
  },
});

Use Cases

• MCP Server monetization — Charge per tool call
• AI API marketplace — Pay-per-request for LLM, image gen, OCR
• Data API — Charge for premium data endpoints
• Crypto-native apps — USDC micropayments, no signup needed

License

MIT © GoldBean