x402-claude-mcp

╔══════════════════════════════════════════════════════════════════════╗
║  ██╗  ██╗██╗  ██╗ ██████╗ ██████╗                                    ║
║  ╚██╗██╔╝██║  ██║██╔═████╗╚════██╗                                   ║
║   ╚███╔╝ ███████║██║██╔██║ █████╔╝                                   ║
║   ██╔██╗ ╚════██║████╔╝██║██╔═══╝                                    ║
║  ██╔╝ ██╗     ██║╚██████╔╝███████╗                                   ║
║  ╚═╝  ╚═╝     ╚═╝ ╚═════╝ ╚══════╝                                   ║
║                                                                       ║
║  CLAUDE MCP SERVER                                                    ║
║  Autonomous payments for AI agents on Solana                          ║
║                                                                       ║
║  Discovery • Payments • Browser • Terminal                            ║
╚══════════════════════════════════════════════════════════════════════╝

HTTP 402 Payment Required - The status code that's been waiting 30 years for its moment. That moment is now.

What is this?

This is the missing piece that lets Claude Code autonomously:

• 🔍 Discover x402-enabled services via XGATE
• 💸 Pay for API calls with USDC on Solana (~$0.00025 per tx)
• 🌐 Browse websites with Playwright
• 💻 Execute terminal commands
• 💰 Manage wallet and spending limits

Built on the x402 protocol - the internet's native payment standard.

The Vision

          ┌─────────────────────────────────────────────────────────────┐
          │                     CLAUDE CODE                              │
          │                         │                                    │
          │                    ┌────┴────┐                               │
          │                    │   MCP   │                               │
          │                    └────┬────┘                               │
          │                         │                                    │
          │              ┌──────────┼──────────┐                         │
          │              ▼          ▼          ▼                         │
          │         ┌────────┐ ┌────────┐ ┌────────┐                     │
          │         │ x402   │ │Browser │ │Terminal│                     │
          │         │Payments│ │  Tool  │ │  Tool  │                     │
          │         └───┬────┘ └────────┘ └────────┘                     │
          │             │                                                │
          │     ┌───────┴───────┐                                        │
          │     ▼               ▼                                        │
          │ ┌────────┐    ┌──────────┐                                   │
          │ │ XGATE  │    │  Solana  │                                   │
          │ │Registry│    │  USDC    │                                   │
          │ └───┬────┘    └────┬─────┘                                   │
          │     │              │                                         │
          │     ▼              ▼                                         │
          │ ┌───────────────────────────────────────┐                    │
          │ │        x402-Enabled Services          │                    │
          │ │  Firecrawl • Zyte • Gloria • DeFi API │                    │
          │ │  Smart Money • Heurist • + thousands  │                    │
          │ └───────────────────────────────────────┘                    │
          └─────────────────────────────────────────────────────────────┘

Build with Lucid → Distribute through XGATE → Get paid on x402

Quick Start

1. Install

npm install
npx playwright install chromium  # For browser tool

2. Configure

Create a .env file:

# Solana RPC (use a fast RPC for best results)
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com

# Your wallet (base58 private key OR path to keypair file)
SOLANA_PRIVATE_KEY=your-base58-encoded-private-key
# OR
SOLANA_KEYPAIR_PATH=/path/to/keypair.json

# Network: solana-mainnet or solana-devnet
X402_NETWORK=solana-mainnet

# Spending limits (in USDC)
X402_MAX_AUTO_APPROVE=1.0    # Max per single request
X402_DAILY_LIMIT=10.0        # Max per day

3. Add to Claude Code

Add this to your Claude Code MCP configuration:

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "x402": {
      "command": "npx",
      "args": ["tsx", "/path/to/x402-claude-mcp/src/index.ts"],
      "env": {
        "SOLANA_RPC_URL": "https://api.mainnet-beta.solana.com",
        "SOLANA_PRIVATE_KEY": "your-base58-private-key",
        "X402_NETWORK": "solana-mainnet",
        "X402_MAX_AUTO_APPROVE": "1.0",
        "X402_DAILY_LIMIT": "10.0"
      }
    }
  }
}

4. Use It

Now Claude can:

You: Find me services that can scrape websites

Claude: [calls x402_discover with query "scrape"]
        I found 3 x402 services for web scraping:
        - Firecrawl ($0.01/request) - Turn websites into LLM-ready data
        - Zyte ($0.001/request) - Browser rendering and extraction
        ...

You: Use Firecrawl to scrape https://example.com

Claude: [calls x402_call_service with serviceId "firecrawl"]
        [automatically pays 0.01 USDC via Solana]
        Here's the scraped content: ...

Available Tools

Discovery Tools

| Tool | Description | |------|-------------| | x402_discover | Search for x402 services by capability | | x402_list_services | List all registered services |

Payment Tools

| Tool | Description | |------|-------------| | x402_wallet_status | Check USDC/SOL balance and limits | | x402_check_payment | Check if URL requires payment (without paying) |

HTTP Tools (with auto-payment)

| Tool | Description | |------|-------------| | x402_get | GET request with automatic x402 payment | | x402_post | POST request with automatic x402 payment | | x402_call_service | Call a registered service by ID |

Browser Tools

| Tool | Description | |------|-------------| | browser_goto | Navigate to URL | | browser_screenshot | Take screenshot | | browser_extract_text | Extract page text | | browser_click | Click element | | browser_type | Type in input |

Terminal Tools

| Tool | Description | |------|-------------| | terminal_run | Execute shell command |

Architecture

src/
├── index.ts              # Entry point
├── x402/
│   ├── types.ts          # x402 protocol types
│   ├── solana-client.ts  # Solana payment client
│   └── middleware.ts     # Auto-pay fetch middleware
├── discovery/
│   ├── registry.ts       # Local service registry
│   └── xgate.ts          # XGATE discovery integration
├── tools/
│   ├── browser.ts        # Playwright browser
│   ├── terminal.ts       # Command execution
│   └── http.ts           # x402-enabled HTTP
└── mcp/
    └── server.ts         # MCP server implementation

How x402 Works

1. Agent requests resource
   GET https://api.example.com/premium-data

2. Server responds 402
   HTTP/1.1 402 Payment Required
   {
     "scheme": "exact",
     "network": "solana-mainnet",
     "maxAmountRequired": "10000",  // 0.01 USDC (6 decimals)
     "asset": "USDC",
     "payTo": "RecipientAddress..."
   }

3. Agent pays via Solana
   → Creates USDC transfer transaction
   → Signs with wallet
   → Sends to network (~400ms finality)

4. Agent retries with payment proof
   GET https://api.example.com/premium-data
   X-PAYMENT: <base64-encoded-receipt>

5. Server verifies and responds
   HTTP/1.1 200 OK
   { "data": "Premium content here..." }

Security

Spending Limits

X402_MAX_AUTO_APPROVE=1.0   # Won't auto-pay more than $1 per request
X402_DAILY_LIMIT=10.0       # Hard stop at $10/day

Command Blacklist

Terminal tool blocks dangerous commands:

• rm -rf /
• dd if=
• mkfs
• shutdown / reboot

Wallet Isolation

Use a dedicated wallet for agent payments, not your main holdings.

Ecosystem

This integrates with:

• x402.org - The protocol standard
• XGATE - Service discovery layer
• Daydreams - AI agent framework
• Coinbase x402 - Facilitator service
• Cloudflare Agents - x402 for Workers

Contributing

PRs welcome. This is how we build the agentic payments future.

License

MIT

 ██╗   ██╗██████╗ ██╗████████╗
 ██║   ██║██╔══██╗██║╚══██╔══╝
 ██║   ██║██████╔╝██║   ██║   
 ██║   ██║██╔══██╗██║   ██║   
 ╚██████╔╝██████╔╝██║   ██║   
  ╚═════╝ ╚═════╝ ╚═╝   ╚═╝   
                               
 ██████╗ ██╗████████╗
 ██╔══██╗██║╚══██╔══╝
 ██████╔╝██║   ██║   
 ██╔══██╗██║   ██║   
 ██████╔╝██║   ██║   
 ╚═════╝ ╚═╝   ╚═╝   
                               
 Built with 💜 by 8bit
 Powered by x402 on Solana