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

Related MCP server: x402-api

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

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:

{
  "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:

{
  "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:

{
  "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:

{
  "name": "x402_gas_prices",
  "arguments": {}
}

Returns: Slow/standard/fast gwei + USD estimates

5. x402_health

Check API health status.

Parameters: None

Example:

{
  "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

2. 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"
      }
    }
  }
}

3. Restart Claude Desktop

4. 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

4. 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"}

5. Save and restart Windsurf

Pricing

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

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