@goldbean/x402-mcp-adapter

x402 client adapter for MCP (Model Context Protocol) — lets standard MCP clients automatically handle 402 Payment Required responses and retry with payment.

Why?

GoldBean API uses the x402 pay-per-request protocol. When you call a paid endpoint without payment, the server returns 402 Payment Required with payment instructions. This adapter:

1. Auto-handles 402 responses — parses payment options and retries automatically
2. IP free quota — 50 free calls/day per IP, no signup needed
3. Auto-register — if no API key, automatically registers for 20 free credits
4. x402 USDC payment — signs and sends USDC payment on Base L2
5. MCP stdio proxy — wraps any MCP client (Claude Desktop, Cursor, Windsurf)

Install

npm install @goldbean/x402-mcp-adapter

Quick Start

As MCP Server (Claude Desktop / Cursor)

Add to your MCP config:

{
  "mcpServers": {
    "goldbean": {
      "command": "npx",
      "args": ["@goldbean/x402-mcp-adapter"],
      "env": {
        "GOLDBEAN_API_KEY": "your-api-key"
      }
    }
  }
}

Register for Free Credits

npx @goldbean/x402-mcp-adapter register
# → API Key: usr_xxx, Free Credits: 20

One-shot API Call

# Free call (uses IP quota)
npx @goldbean/x402-mcp-adapter call /paid/weather-now

# With API key
GOLDBEAN_API_KEY=usr_xxx npx @goldbean/x402-mcp-adapter call /paid/baidu-ocr '{"image":"base64..."}'

Programmatic Usage

const { X402MCPAdapter } = require('@goldbean/x402-mcp-adapter');

const adapter = new X402MCPAdapter({
  baseUrl: 'https://goldbean-api.xyz',
  paymentMethod: 'auto',  // auto-detect best method
});

// Register for free credits
const reg = await adapter.register('[email protected]');
console.log(reg.apiKey); // usr_xxx

// Call any API endpoint
const result = await adapter.call('/paid/baidu-ocr', {
  image: 'base64-encoded-image-data'
});

// Call by MCP tool name
const weather = await adapter.callTool('weather_now', { city: 'Tokyo' });

// List available tools
const tools = await adapter.listTools();

Payment Methods

| Method | Description | Setup | |--------|-------------|-------| | auto | Auto-detect best available method | Default | | prepaid | Use registered API key credits | Set GOLDBEAN_API_KEY | | x402 | Pay per call with USDC on Base | Set GOLDBEAN_WALLET_KEY | | paypal | Redirect to PayPal | Manual via /buy-credits.html |

Free Tier

• 50 free API calls/day per IP — no signup needed
• 20 free credits on registration — no credit card
• Register at: POST https://goldbean-api.xyz/paid/user/register

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | GOLDBEAN_API_KEY | API key from registration | — | | GOLDBEAN_PAYMENT_METHOD | Payment method | auto | | GOLDBEAN_WALLET_KEY | EVM wallet private key | — | | GOLDBEAN_WALLET_ADDRESS | Wallet address | — | | GOLDBEAN_BASE_URL | API base URL | https://goldbean-api.xyz |

License

MIT © GoldBean