Zerion Hosted MCP

This repo treats Zerion's hosted MCP as the primary interface for MCP-native agent environments.

Endpoint

https://developers.zerion.io/mcp

What to use it for

Use the hosted MCP path when:

• your client already supports MCP

• the model should choose and call tools directly

• you want the fastest path for Cursor or Claude-style agent setups

Use the CLI path when your environment expects shell commands returning JSON.

Authentication

Two options:

Option 1: API Key

1. Get a Zerion API key: https://dashboard.zerion.io

2. Export it:

   export ZERION_API_KEY="zk_dev_..."

3. Reuse it in the MCP client config.

This repo's example configs assume an Authorization: Bearer ... header for the hosted MCP and standard Basic Auth for raw REST requests.

Option 2: x402 Pay-per-call

No API key needed. Pay $0.01 USDC per request via the x402 protocol. Supports EVM (Base) and Solana.

Single key — format is auto-detected:

export WALLET_PRIVATE_KEY="0x..."    # EVM (Base) — 0x-prefixed hex
export WALLET_PRIVATE_KEY="5C1y..."  # Solana — base58 encoded keypair
export ZERION_X402=true

Both chains simultaneously:

export EVM_PRIVATE_KEY="0x..."
export SOLANA_PRIVATE_KEY="5C1y..."
export ZERION_X402_PREFER_SOLANA=true  # optional: prefer Solana when both are set
export ZERION_X402=true

The CLI signs the payment automatically using @x402/fetch with @x402/evm or @x402/svm. Your wallet must hold USDC on the corresponding network.

Supported clients in this repo

• Cursor: examples/cursor

• Claude-compatible remote MCP clients: examples/claude

Wallet-analysis walkthrough

Use one of the example wallets:

• vitalik.eth

• 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

Then ask:

Analyze this wallet and summarize:
- total portfolio value
- top holdings
- DeFi positions
- recent transactions
- PnL

The tool catalog in mcp/tools/ documents the concrete wallet capabilities used by the examples and CLI.

Failure modes

Documented and expected:

• missing or invalid API key

• invalid address or ENS resolution failure

• unsupported chain filters

• rate limits

• temporary upstream timeout

• empty wallet or partially bootstrapped wallet state

Relevant Zerion doc notes behind these behaviors:

• wallet portfolio may require polling for fresh wallets

• wallet positions may take time to bootstrap for some tokens

• wallet transactions and positions accept many filters and pagination params

• Solana support has endpoint-specific limitations