x402 On-Chain Data MCP Server

x402 On-Chain Data MCP Server

MCP (Model Context Protocol) server wrapper for the x402 On-Chain Data API. Provides pay-per-call blockchain data including wallet profiles, token metrics, protocol TVL, and gas prices.

Author

0xEtherial

Features

• Wallet Profiles - ETH balance, transaction history, top tokens ($0.10/call)
• Token Metrics - Price, market cap, volume, liquidity ($0.05/call)
• Protocol TVL - Total value locked, chain breakdown ($0.05/call)
• Gas Prices - Real-time gas estimates ($0.02/call)
• Health Check - API status (free)

Installation

npm install

Configuration

Copy .env.example to .env and configure:

cp .env.example .env

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | API_BASE_URL | x402 On-Chain API base URL | http://localhost:8900 |

Usage

Start the MCP Server

node server.js

Available Tools

1. x402_wallet_score

Get comprehensive wallet profile.

Parameters:

• address (string, required): Ethereum wallet address

Example: ``json { "name": "x402_wallet_score", "arguments": { "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD5e" } } ``

Returns: ETH balance, transaction count, first/last transaction, top 5 tokens

---

2. x402_token_metrics

Get token price and market data.

Parameters:

• address (string, required): Token contract address

Example: ``json { "name": "x402_token_metrics", "arguments": { "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" } } ``

Returns: Price, market cap, 24h volume, liquidity, FDV

---

3. x402_protocol_tvl

Get DeFi protocol TVL data.

Parameters:

• slug (string, required): Protocol identifier (e.g., "uniswap", "aave")

Example: ``json { "name": "x402_protocol_tvl", "arguments": { "slug": "uniswap" } } ``

Returns: TVL, 24h change, chain breakdown

---

4. x402_gas_prices

Get current Ethereum gas prices.

Parameters: None

Example: ``json { "name": "x402_gas_prices", "arguments": {} } ``

Returns: Slow/standard/fast gwei + USD estimates

---

5. x402_health

Check API health status.

Parameters: None

Example: ``json { "name": "x402_health", "arguments": {} } ``

Returns: API health status

Integration with AI Clients

Claude Desktop

1. Open Claude Desktop configuration:

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

1. Add the MCP server to claude_desktop_config.json:

{
  "mcpServers": {
    "x402-onchain": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-wrapper/server.js"],
      "env": {
        "API_BASE_URL": "https://nominated-safe-pairs-favorites.trycloudflare.com"
      }
    }
  }
}

1. Restart Claude Desktop

1. The x402 tools will appear in Claude's available tools

Cursor

1. Open Cursor settings (Cmd+,)
2. Navigate to "Features" → "Model Context Protocol"
3. Add new server:

• Name: x402-onchain
• Command: node /absolute/path/to/mcp-wrapper/server.js
• Environment: API_BASE_URL=https://nominated-safe-pairs-favorites.trycloudflare.com

1. Restart Cursor

Windsurf

1. Open Windsurf settings
2. Go to "AI" → "MCP Servers"
3. Click "Add Server"
4. Configure:

• Name: x402-onchain
• Command: node
• Args: ["/absolute/path/to/mcp-wrapper/server.js"]
• Env: {"API_BASE_URL": "https://nominated-safe-pairs-favorites.trycloudflare.com"}

1. Save and restart Windsurf

Pricing

All endpoints use the x402 payment protocol (pay-per-call):

| Endpoint | Cost | Description | |----------|------|-------------| | /wallet/:address | $0.10 | Wallet profile + top tokens | | /token/:address | $0.05 | Token price + metrics | | /protocol/:slug | $0.05 | Protocol TVL data | | /gas | $0.02 | Gas price estimates | | / | Free | Health check |

Error Handling

The server returns structured error responses:

{
  "error": true,
  "status": 404,
  "message": "Wallet not found"
}

Development

Requirements

• Node.js >= 18.0.0
• npm

Install Dependencies

npm install

Run Locally

API_BASE_URL=http://localhost:8900 node server.js

License

MIT

Links

• x402 Payment Protocol
• Model Context Protocol