npm package: @mawdbotsonsolana/x402-claude-mcp
Description: x402 payments + discovery MCP server for Claude Code on Solana - Autonomous payments for AI agents
Author: 8bit
Latest version: 0.1.0

# 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](https://x402.org) - 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

```bash
npm install
npx playwright install chromium  # For browser tool
```

### 2. Configure

Create a `.env` file:

```env
# 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`

```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

```env
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](https://x402.org)** - The protocol standard
- **[XGATE](https://xgate.daydreams.systems)** - Service discovery layer
- **[Daydreams](https://github.com/daydreamsai/daydreams)** - AI agent framework
- **[Coinbase x402](https://docs.cdp.coinbase.com/x402)** - Facilitator service
- **[Cloudflare Agents](https://developers.cloudflare.com/agents/x402/)** - 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
```