# Zerion MCP Server
A production-ready [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that provides AI assistants with access to the Zerion API for cryptocurrency portfolio management, DeFi positions, NFTs, and market data.
## Features
- 🔌 **Auto-generated Tools**: Automatically exposes Zerion API endpoints as MCP tools via OpenAPI specification
- ⚙️ **Flexible Configuration**: YAML config files with environment variable overrides
- 📝 **Structured Logging**: JSON and text formats with sensitive data redaction
- 🛡️ **Robust Error Handling**: Custom exceptions with detailed context and troubleshooting hints
- 🔁 **Automatic Retry Logic**: Exponential backoff for rate limits (429) and wallet indexing (202)
- 📄 **Pagination Support**: Manual and automatic pagination for large result sets (5000+ items)
- 🚦 **Rate Limit Management**: Transparent retry handling with configurable backoff strategies
- 🔍 **Advanced Filtering**: Chain filtering, DeFi positions, spam filtering, transaction types, and more
- 🧪 **Testnet Support**: Test applications on testnets (Sepolia, Monad, etc.) via X-Env header
- 💱 **Multi-Currency**: Portfolio values in USD, ETH, EUR, or BTC denomination
- ✅ **Comprehensive Tests**: Unit and integration tests with pytest
- 🚀 **Async HTTP**: Non-blocking API calls with httpx
## Operational Capabilities
The Zerion API provides three powerful operational capabilities that make it stand out from traditional blockchain data providers:
### 1. Multi-Chain Aggregation
**100+ blockchains in one API call** - Zerion automatically aggregates data across all supported blockchain networks without requiring multiple API requests.
**How it works:**
- No special parameters needed - multi-chain aggregation is automatic
- Single call to `getWalletPortfolio` returns balances across Ethereum, Base, Polygon, Arbitrum, Optimism, Solana, and 100+ other chains
- Eliminates the need for per-chain API providers (Alchemy, Infura, Moralis)
**Supported chains include:**
- **EVM chains**: Ethereum, Polygon, Arbitrum, Optimism, Base, BNB Chain, Avalanche, Fantom, Gnosis, zkSync, StarkNet
- **L2s**: Optimism, Arbitrum, Base, zkSync Era, Polygon zkEVM, Linea, Scroll
- **Non-EVM**: Solana
- **100+ total chains** (see `listChains` for complete list)
**Examples:**
```
Get wallet portfolio across all chains:
Use getWalletPortfolio with:
- address: "0x42b9dF65B219B3dD36FF330A4dD8f327A6Ada990"
- currency: "usd"
```
Result: Portfolio data aggregated from all 100+ supported chains in a single response.
```
Get positions across all chains:
Use listWalletPositions with:
- address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
- filter[positions]: "only_complex"
- currency: "usd"
```
Result: DeFi positions from Ethereum, Base, Arbitrum, and all other chains in one call.
**Benefits vs. per-chain APIs:**
- **Zerion**: 1 API call for cross-chain portfolio
- **Per-chain APIs**: 10+ separate API calls needed (one per chain)
- **Quota savings**: 90% reduction in API requests
- **Simplified logic**: No manual chain aggregation required
**Use cases:**
- Cross-chain portfolio dashboards
- DeFi aggregators (track positions across all chains)
- Multi-chain wallet analytics
- Cross-chain transaction history
### 2. DeFi Protocol Coverage
**8,000+ DeFi protocols tracked** - Zerion provides comprehensive protocol metadata for lending, staking, LP, and yield farming positions.
**Available protocol metadata:**
- `relationships.dapp.data.id` - Protocol identifier (e.g., "uniswap-v3", "aave-v3")
- `attributes.position_type` - Position category (staked, deposit, loan, reward, etc.)
- DApp data following JSON:API relationship format
**Protocol categories covered:**
- **DEX**: Uniswap, Curve, Balancer, SushiSwap, PancakeSwap
- **Lending**: Aave, Compound, MakerDAO, Euler
- **Staking**: Lido, Rocket Pool, StakeWise
- **Yield aggregators**: Yearn, Beefy, Convex
**Examples:**
```
Get all DeFi positions with protocol data:
Use listWalletPositions with:
- address: "0x42b9dF65B219B3dD36FF330A4dD8f327A6Ada990"
- filter[positions]: "only_complex"
- filter[trash]: "only_non_trash"
- currency: "usd"
```
Result: Returns positions with `relationships.dapp` containing protocol metadata (Uniswap, Aave, Curve, etc.).
```
Filter positions by specific protocol:
Use listWalletPositions with:
- address: "0x..."
- filter[dapp_ids]: "aave-v3,compound-v2"
- filter[positions]: "only_complex"
```
Result: Only Aave V3 and Compound V2 positions.
**Use cases:**
- DeFi protocol analytics dashboards
- Position aggregation by protocol
- Protocol yield tracking
- Risk management (track exposure by protocol)
### 3. NFT Metadata Completeness
**Comprehensive NFT metadata** - Zerion provides rich metadata for ERC-721 and ERC-1155 tokens, enabling full-featured NFT displays.
**Available metadata fields:**
- `metadata.name` - NFT name
- `metadata.description` - NFT description
- `metadata.content.preview` - Thumbnail/preview image URL
- `metadata.content.detail` - High-resolution image URL
- `market_data.prices.floor` - Collection floor price (where available)
- `metadata.attributes` - NFT traits and properties
- `relationships.nft_collection` - Collection relationship data
**Image URLs:**
- Preview URLs for thumbnails/gallery views
- Detail URLs for full-size displays
- URLs may be IPFS gateways
**Floor price availability:**
- Available for most established collections
- New/small collections may lack floor data
- Measured in requested currency (USD, ETH, EUR, BTC)
**Examples:**
```
Get NFT with full metadata:
Use getNFTById with:
- nft_id: "ethereum:0x74ee68a33f6c9f113e22b3b77418b75f85d07d22:10"
- currency: "usd"
```
Result: Complete NFT metadata including name, description, images, floor price, traits, and collection data.
```
Get wallet NFT positions:
Use listWalletNFTPositions with:
- address: "0x..."
- filter[trash]: "only_non_trash"
```
Result: NFT positions with metadata for rich NFT gallery displays.
**Use cases:**
- NFT gallery applications
- NFT marketplace displays
- Collection analytics (floor price tracking)
- Trait-based filtering and rarity analysis
---
## Available Functions
### Wallet & Portfolio
- **getWalletPortfolio**: Returns the portfolio overview of a web3 wallet.
- **listWalletPositions**: Returns a list of wallet positions (supports `filter[positions]=only_complex` for DeFi).
- **getWalletChart**: Returns a portfolio balance chart for a wallet.
- **getWalletPNL**: Returns the Profit and Loss (PnL) details of a web3 wallet.
- **listWalletTransactions**: Returns a list of transactions associated with the wallet (supports advanced filters).
### NFTs
- **getWalletNftPortfolio**: Returns the NFT portfolio overview of a web3 wallet.
- **listWalletNFTCollections**: Returns a list of the NFT collections held by a specific wallet.
- **listWalletNFTPositions**: Returns a list of the NFT positions held by a specific wallet.
- **getNFTById**: Returns a single NFT by its unique identifier.
- **listNFTs**: Returns a list of NFTs by using different parameters.
### Webhooks & Real-Time Notifications (NEW!)
- **createTxSubscription**: Create webhook subscription for real-time transaction notifications.
- **listTxSubscriptions**: List all active transaction subscriptions.
- **getTxSubscription**: Get subscription details by ID.
- **updateTxSubscription**: Update subscription addresses, callback URL, or chain filters.
- **deleteTxSubscription**: Delete a transaction subscription.
### Market Data
- **getFungibleById**: Returns a fungible asset by its unique identifier.
- **getFungibleChart**: Returns the chart for a fungible asset for a selected period.
- **listFungibles**: Returns a paginated list of fungible assets supported by Zerion.
- **listGasPrices**: Provides real-time information on the current gas prices across all supported blockchain networks.
- **listChains**: Returns a list of all chains supported by Zerion.
- **getChainById**: Returns a chain by its unique chain identifier.
### Swaps & Bridges
- **swapFungibles**: Provides a list of fungibles available for bridge exchange.
- **swapOffers**: Provides a comprehensive overview of relevant trades and bridge exchanges.
## Requirements
### For Docker (Recommended)
- Docker 20.10 or higher
- Docker Compose V2
- Zerion API key ([Get one here](https://developers.zerion.io/))
### For Native Python Installation
- Python 3.11 or higher
- Zerion API key ([Get one here](https://developers.zerion.io/))
## Installation
### Using Docker (Recommended)
```bash
# Clone the repository
git clone https://github.com/SAK1337/myzerionmcp.git
cd myzerionmcp
# Create .env file with your API key
cp .env.example .env
# Edit .env and set ZERION_API_KEY
# Start with Docker Compose
docker-compose up -d
# View logs
docker-compose logs -f
```
See [DOCKER.md](DOCKER.md) for detailed Docker deployment guide.
### From Source
```bash
# Clone the repository
git clone https://github.com/SAK1337/myzerionmcp.git
cd myzerionmcp
# Install the package
pip install -e .
# For development (includes testing dependencies)
pip install -e ".[dev]"
```
### From PyPI (when published)
```bash
pip install zerion-mcp-server
```
## Quick Start
### 1. Set up your API key
```bash
export ZERION_API_KEY="Bearer your-api-key-here"
```
### 2. Run the server
```bash
zerion-mcp-server
```
### 3. Connect with an MCP client
The server will start and listen for MCP protocol connections. You can connect it to AI assistants like Claude Desktop.
#### Claude Desktop Configuration
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"zerion": {
"command": "zerion-mcp-server",
"env": {
"ZERION_API_KEY": "Bearer your-api-key-here"
}
}
}
}
```
## Configuration
### Configuration File
Create a `config.yaml` file in your working directory:
```yaml
# Server configuration
name: "Zerion API"
base_url: "https://api.zerion.io"
oas_url: "https://raw.githubusercontent.com/smart-mcp-proxy/zerion-mcp-server/main/zerion_mcp_server/openapi_zerion.yaml"
# API authentication
api_key: "${ZERION_API_KEY}" # Environment variable substitution
# Logging configuration
logging:
level: "INFO" # DEBUG, INFO, WARN, ERROR
format: "text" # text or json
```
See [`config.example.yaml`](config.example.yaml) for a complete example.
### Environment Variables
Environment variables override config file values:
| Variable | Description | Default |
|----------|-------------|---------|
| `ZERION_API_KEY` | Zerion API key (required) | - |
| `ZERION_BASE_URL` | Zerion API base URL | `https://api.zerion.io` |
| `ZERION_OAS_URL` | OpenAPI spec URL | GitHub raw URL |
| `CONFIG_PATH` | Path to config.yaml | `./config.yaml` |
| `LOG_LEVEL` | Logging level | `INFO` |
| `LOG_FORMAT` | Logging format (text/json) | `text` |
## Usage Examples
Once connected to an MCP client (like Claude), you can query Zerion data:
### Portfolio Balance
```
Get the portfolio balance for wallet 0x1234...
```
The server exposes tools like `getWalletChart`, `getWalletPositions`, etc.
### DeFi Positions
```
Show me the DeFi positions for address 0xabcd...
```
### NFT Collections
```
List NFTs owned by 0x5678...
```
All Zerion API endpoints are automatically available as MCP tools. See the [Zerion API documentation](https://developers.zerion.io/reference) for available operations.
## Webhooks - Real-Time Transaction Notifications
The Zerion MCP Server now supports **transaction subscription webhooks** for real-time wallet activity monitoring. This is critical for production applications because webhooks eliminate inefficient polling, conserve API quotas, and enable sub-second notification latency.
### Why Use Webhooks?
- **Rate Limit Conservation**: Polling wastes API quota (~5K requests/day on free tier). Webhooks push updates only when transactions occur.
- **Real-Time**: Sub-second notifications when monitored wallets transact
- **Scalability**: Monitor hundreds of wallets without quota waste
- **Cost Efficiency**: On paid tiers ($149/mo Builder), webhooks eliminate redundant polling requests
### Architecture Overview
```
┌──────────────┐
│ AI Client │ (Claude Desktop)
└──────┬───────┘
│ stdio (MCP protocol)
▼
┌──────────────┐
│ MCP Server │ - Manages subscriptions via API calls
└──────┬───────┘
│ HTTPS
▼
┌──────────────┐
│ Zerion API │
└──────┬───────┘
│ Webhooks (HTTP POST)
▼
┌──────────────┐
│ Your HTTP │ - Receives webhook payloads (separate service)
│ Receiver │
└──────────────┘
```
**Important**: The MCP server manages webhook subscriptions but does NOT receive webhook payloads. You must deploy a separate HTTP service to receive webhook POST requests from Zerion.
### Available Tools
- **`createTxSubscription`** - Create new webhook subscription
- **`listTxSubscriptions`** - List all active subscriptions
- **`getTxSubscription`** - Get subscription details by ID
- **`updateTxSubscription`** - Update addresses, callback URL, or chain filters
- **`deleteTxSubscription`** - Delete subscription
### Example: Create Subscription for Ethereum Address
```
Use the createTxSubscription tool with:
- addresses: ["0x42b9dF65B219B3dD36FF330A4dD8f327A6Ada990"]
- callback_url: "https://webhook.site/your-unique-url"
- chain_ids: ["ethereum", "base"]
```
This creates a subscription that sends webhook notifications to your callback URL whenever the specified address has transactions on Ethereum or Base.
### Example: Create Subscription for Solana Address
```
Use the createTxSubscription tool with:
- addresses: ["8BH9pjtgyZDC4iAQH5ZiYDZ1MDWC98xki2V8NzqqKW3K"]
- callback_url: "https://your-server.com/webhooks/zerion"
- chain_ids: ["solana"]
```
### Webhook Payload Structure
When a monitored address has a new transaction, Zerion sends a POST request to your callback URL with this structure:
```json
{
"data": {
"type": "callback",
"id": "bf300927-3f57-4d00-a01a-f7b75bd9b8de",
"attributes": {
"address": "0x42b9dF65B219B3dD36FF330A4dD8f327A6Ada990",
"callback_url": "https://webhook.site/test",
"timestamp": "2025-10-16T10:56:50Z"
},
"relationships": {
"subscription": {
"id": "61f13641-443e-4068-932b-c28edeaefd85",
"type": "tx-subscriptions"
}
}
},
"included": [
{
"type": "transactions",
"id": "13de850a-bfa4-54c7-a7bb-fd6371d98894",
"attributes": {
"operation_type": "trade",
"hash": "0x...",
"mined_at": "2025-10-16T10:56:48Z",
"status": "confirmed",
"fee": { ... },
"transfers": [ ... ]
},
"relationships": {
"chain": { "id": "ethereum", "type": "chains" },
"dapp": { "id": "uniswap", "type": "dapps" }
}
}
]
}
```
The `included` array contains full transaction details using the same schema as the `listWalletTransactions` endpoint.
### Setting Up a Webhook Receiver
#### Option 1: Testing with webhook.site (Recommended for Development)
1. Visit https://webhook.site
2. Copy your unique URL (e.g., `https://webhook.site/abc-123-def`)
3. Use that URL as `callback_url` when creating subscriptions
4. View incoming webhooks in real-time on the webhook.site page
#### Option 2: Python Flask Receiver (Production)
```python
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/webhooks/zerion', methods=['POST'])
def handle_zerion_webhook():
payload = request.json
# Extract transaction data
callback_data = payload['data']
transactions = payload.get('included', [])
for tx in transactions:
if tx['type'] == 'transactions':
print(f"New transaction: {tx['attributes']['hash']}")
print(f"Operation: {tx['attributes']['operation_type']}")
print(f"Chain: {tx['relationships']['chain']['id']}")
return jsonify({"status": "received"}), 200
if __name__ == '__main__':
app.run(host='0.0.0.0', port=8080)
```
Deploy this to a public server (Heroku, Vercel, AWS Lambda, etc.) and use the public HTTPS URL as your callback.
#### Option 3: Node.js Express Receiver
```javascript
const express = require('express');
const app = express();
app.use(express.json());
app.post('/webhooks/zerion', (req, res) => {
const { data, included } = req.body;
const transactions = included.filter(item => item.type === 'transactions');
transactions.forEach(tx => {
console.log(`New ${tx.attributes.operation_type}: ${tx.attributes.hash}`);
});
res.status(200).json({ status: 'received' });
});
app.listen(8080, () => console.log('Webhook receiver running on port 8080'));
```
### Webhook Best Practices
1. **Respond Quickly**: Zerion expects < 5 second response time. Do heavy processing asynchronously.
2. **Idempotency**: Webhooks may be delivered multiple times. Check for duplicate transaction IDs.
3. **Retry Policy**: Zerion retries delivery up to 3 times on failure.
4. **HTTPS Required**: Callback URLs must use HTTPS (not HTTP).
5. **No Guaranteed Order**: Don't assume webhook delivery order matches blockchain order.
### Security Considerations
- **Signature Verification**: Future enhancement - webhook payload signing (check Zerion docs)
- **IP Whitelisting**: Consider restricting webhook receiver to Zerion's IP ranges
- **HTTPS Only**: Never use HTTP callback URLs in production
### Troubleshooting Webhooks
#### Webhooks Not Arriving
1. **Check callback URL is publicly accessible**: Test with `curl -X POST https://your-url.com`
2. **Verify subscription is active**: Use `listTxSubscriptions` to confirm subscription exists
3. **Check Zerion dashboard**: Verify API key has webhook permissions
4. **Test with webhook.site first**: Confirm Zerion can reach your infrastructure
#### Rate Limits on Subscription Management
- Developer keys: Limited subscriptions (1-5)
- Contact api@zerion.io for enterprise webhook quotas
---
## Advanced Filtering - Query Optimization
The Zerion API supports powerful filter parameters that are already available in the MCP server but often underutilized. Using filters **reduces API quota usage**, **improves response times**, and enables **precise data queries**.
### Filter Applicability Matrix
| Filter | Endpoints | Use Case |
|--------|-----------|----------|
| **`filter[positions]`** | `getWalletPortfolio`, `listWalletPositions` | Isolate DeFi positions from simple balances |
| **`filter[chain_ids]`** | `listWalletPositions`, `listWalletTransactions`, `getWalletChart`, `listWalletNFTPositions` | Query specific blockchains only |
| **`filter[trash]`** | `listWalletPositions`, `listWalletTransactions`, `listWalletNFTPositions` | Hide spam/dust |
| **`filter[operation_types]`** | `listWalletTransactions` | Filter by transaction type (trade, transfer, execute) |
| **`filter[position_types]`** | `listWalletPositions` | Filter by DeFi category (staked, deposit, loan, reward) |
| **`filter[fungible_ids]`** | `listWalletPositions`, `listWalletTransactions` | Track specific tokens only |
### DeFi Position Filtering (`only_complex`)
**Problem**: By default, `listWalletPositions` returns simple token balances. DeFi protocols (staking, LPs, lending) are excluded.
**Solution**: Use `filter[positions]=only_complex` to get **only DeFi positions**.
#### Example: Get DeFi Positions Only
```
Use listWalletPositions with:
- address: "0x42b9dF65B219B3dD36FF330A4dD8f327A6Ada990"
- filter[positions]: "only_complex"
- filter[trash]: "only_non_trash"
- currency: "usd"
```
**Result**: Returns staking positions (e.g., staked ETH), liquidity pool tokens (Uniswap, Curve), lending positions (Aave, Compound), and yield farming positions. Excludes simple ERC-20 balances.
**Use Cases**:
- DeFi analytics dashboards
- Institutional risk management (track complex positions separately)
- Yield farming trackers
- Portfolio categorization for tax reporting
#### Filter Options
- **`only_simple`** (default): Only wallet-type positions (basic token balances)
- **`only_complex`**: Only DeFi protocol positions (staking, LP, lending)
- **`no_filter`**: Both simple and complex positions
### Chain Filtering (`filter[chain_ids]`)
**Problem**: Fetching positions across all 50+ chains wastes quota and returns irrelevant data.
**Solution**: Use `filter[chain_ids]` to query specific blockchains.
#### Example: Ethereum + Base Only
```
Use listWalletTransactions with:
- address: "0x..."
- filter[chain_ids]: "ethereum,base"
- filter[trash]: "only_non_trash"
```
**Result**: Only transactions on Ethereum and Base. Ignores activity on Polygon, Arbitrum, Optimism, etc.
#### Example: Single Chain (Optimism)
```
Use listWalletPositions with:
- address: "0x..."
- filter[chain_ids]: "optimism"
```
**Use Cases**:
- L2-focused analytics (Base, Optimism, Arbitrum)
- Cross-chain comparison (Ethereum vs. L2s)
- Mainnet-only queries
**Valid Chain IDs**: `ethereum`, `base`, `optimism`, `arbitrum`, `polygon`, `solana`, `binance-smart-chain`, `avalanche`, `fantom`, `gnosis`, etc. Use `listChains` to see all supported chains.
### Spam Filtering (`filter[trash]`)
**Problem**: Wallet transaction history polluted with spam tokens, dust, and airdrop scams.
**Solution**: Use `filter[trash]=only_non_trash` to hide spam.
#### Example: Clean Transaction History
```
Use listWalletTransactions with:
- address: "0x..."
- filter[trash]: "only_non_trash"
- page[size]: 100
```
**Result**: Clean transaction history without spam tokens or dust transfers.
#### Filter Options
- **`only_non_trash`**: Hide spam/dust (recommended for user-facing apps)
- **`only_trash`**: Show only spam/dust (for security monitoring)
- **`no_filter`** (default): Show all transactions
**Use Cases**:
- User-facing wallets (clean UI)
- Portfolio analytics (exclude noise)
- Tax reporting (ignore spam airdrops)
### Transaction Type Filtering (`filter[operation_types]`)
**Problem**: Need to analyze specific transaction types (e.g., only swaps, only transfers).
**Solution**: Use `filter[operation_types]` to isolate transaction categories.
#### Example: Trades Only
```
Use listWalletTransactions with:
- address: "0x..."
- filter[operation_types]: "trade"
- filter[chain_ids]: "ethereum,base"
```
**Result**: Only DEX swaps and trades. Excludes transfers, approvals, contract executions.
#### Available Operation Types
- **`trade`**: Token swaps (Uniswap, 1inch, etc.)
- **`transfer`**: Simple token transfers
- **`execute`**: Smart contract interactions
- **`approve`**: Token approvals
- **`deposit`**: Protocol deposits
- **`withdraw`**: Protocol withdrawals
**Use Cases**:
- Trading analytics (volume, frequency)
- Transfer tracking (payroll, payments)
- Smart contract interaction audits
### Position Type Filtering (`filter[position_types]`)
**Problem**: DeFi positions span many categories (staking, lending, rewards). Need to isolate specific types.
**Solution**: Use `filter[position_types]` for granular DeFi categorization.
#### Example: Staking + Rewards Only
```
Use listWalletPositions with:
- address: "0x..."
- filter[positions]: "only_complex"
- filter[position_types]: "staked,reward"
```
**Result**: Only staked assets and claimable rewards. Excludes LP positions, loans, deposits.
#### Available Position Types
- **`wallet`**: Simple balance
- **`deposit`**: Lending protocol deposits (Aave, Compound)
- **`loan`**: Borrowed assets
- **`staked`**: Staked tokens (ETH staking, governance staking)
- **`reward`**: Claimable rewards
- **`locked`**: Vested/locked tokens
- **`margin`**: Margin trading positions
- **`airdrop`**: Airdrop eligibility
**Use Cases**:
- Staking dashboards
- Yield optimization
- Loan/collateralization tracking
- Rewards harvesting
### Query Optimization Best Practices
#### 1. Use Filters to Reduce Quota Usage
**Bad** (fetches all data, filters client-side):
```
- Get all positions for address
- Filter out spam in your app
- Filter to Ethereum-only in your app
```
**Cost**: ~1000 positions returned, large response
**Good** (filter at API level):
```
Use listWalletPositions with:
- filter[chain_ids]: "ethereum"
- filter[trash]: "only_non_trash"
```
**Cost**: ~50 positions returned, 20x smaller response
#### 2. Combine Filters for Precision
**Example: DeFi-Only, Ethereum, No Spam**
```
Use listWalletPositions with:
- filter[positions]: "only_complex"
- filter[chain_ids]: "ethereum"
- filter[trash]: "only_non_trash"
- currency: "usd"
- sort: "value"
```
**Result**: High-value Ethereum DeFi positions only. Perfect for risk dashboards.
#### 3. Page Size Control
```
Use listWalletTransactions with:
- page[size]: 50
- filter[trash]: "only_non_trash"
```
Smaller pages = faster responses, less quota per request.
### Common Filter Combinations
| Use Case | Filters |
|----------|---------|
| **Clean transaction feed** | `filter[trash]=only_non_trash`, `filter[operation_types]=trade,transfer` |
| **DeFi risk dashboard** | `filter[positions]=only_complex`, `filter[chain_ids]=ethereum`, `sort=value` |
| **L2 trading analytics** | `filter[chain_ids]=base,optimism,arbitrum`, `filter[operation_types]=trade` |
| **Staking tracker** | `filter[positions]=only_complex`, `filter[position_types]=staked,reward` |
| **NFT portfolio (no spam)** | `filter[trash]=only_non_trash` on `listWalletNFTPositions` |
---
## Pagination - Fetching Large Result Sets
The Zerion API uses cursor-based pagination for endpoints that return lists (transactions, positions, NFTs). The MCP server provides both manual and automatic pagination support.
### Why Pagination Matters
Active wallets can have **thousands of transactions**. Without pagination:
- API quota exhausted quickly (Developer tier: ~5K requests/day)
- Incomplete data (default page size: 100 items)
- Slow responses (large payloads)
### Manual Pagination
All list endpoints support `page[size]` and `page[after]` parameters:
```
Use listWalletTransactions with:
- address: "0x..."
- page[size]: 100
- filter[trash]: "only_non_trash"
```
The response includes a `links.next` URL for fetching the next page:
```json
{
"data": [...],
"links": {
"next": "https://api.zerion.io/v1/wallets/.../transactions?page[after]=cursor123"
}
}
```
**To fetch the next page**, extract the cursor from `links.next` and use it as `page[after]`:
```
Use listWalletTransactions with:
- address: "0x..."
- page[size]: 100
- page[after]: "cursor123"
```
Continue until `links.next` is absent (last page reached).
### Automatic Pagination (Python SDK)
For programmatic access, use the auto-pagination helper to fetch all pages automatically:
```python
from zerion_mcp_server.pagination import fetch_all_pages
from zerion_mcp_server import RetryAsyncClient
# Create client
client = RetryAsyncClient(
base_url="https://api.zerion.io",
headers={"Authorization": "Bearer your-key"}
)
# Define your API call
async def get_transactions(address, **kwargs):
response = await client.get(
f"/v1/wallets/{address}/transactions",
params=kwargs
)
return response.json()
# Fetch all transactions (up to max_pages)
all_transactions = await fetch_all_pages(
api_call=lambda **kw: get_transactions("0x123...", **kw),
max_pages=50, # Safety limit
page_size=100
)
print(f"Total transactions: {len(all_transactions)}")
```
### Pagination Configuration
Control pagination behavior in `config.yaml`:
```yaml
pagination:
# Default page size (max: 100)
default_page_size: 100
# Safety limit for auto-pagination
max_auto_pages: 50
```
**Example calculations**:
- 50 pages × 100 items = 5,000 results (covers 99% of wallets)
- 50 API requests consumed (watch your quota!)
### Pagination Best Practices
#### 1. Use Filters to Reduce Results
**Bad** (fetches everything):
```
listWalletTransactions:
- address: "0x..."
- page[size]: 100
```
**Result**: 2,000 transactions (20 pages)
**Good** (filter first):
```
listWalletTransactions:
- address: "0x..."
- filter[chain_ids]: "ethereum"
- filter[trash]: "only_non_trash"
- page[size]: 100
```
**Result**: 300 transactions (3 pages) - 85% quota savings!
#### 2. Choose Appropriate Page Sizes
- **Small pages (25-50)**: Faster individual requests, more total requests
- **Large pages (100)**: Fewer requests, larger payloads (recommended)
- **Default**: 100 items per page
#### 3. Monitor Auto-Pagination Limits
The auto-pagination helper logs warnings at key thresholds:
```
INFO: Fetched 10 pages - quota impact may be significant
WARNING: Fetched 25 pages - high quota usage
WARNING: Reached max page limit (50) - results may be incomplete
```
If you see "results may be incomplete", increase `max_auto_pages` or use manual pagination.
### Quota Impact Example
**Scenario**: Fetch all transactions for an active wallet (5,000 transactions)
| Approach | Requests | Quota Impact (Developer Tier) |
|----------|----------|-------------------------------|
| Manual (1 page) | 1 | ~0.02% of daily quota |
| Auto-paginate (50 pages) | 50 | ~1% of daily quota |
| Without filters (200 pages) | 200 | ~4% of daily quota |
**Takeaway**: Use filters + reasonable `max_pages` limits to avoid quota exhaustion.
---
## Rate Limiting - Automatic Retry with Backoff
The Zerion API enforces rate limits based on your subscription tier:
| Tier | Rate Limit | Daily Requests | Price |
|------|------------|----------------|-------|
| **Developer** (free) | 2 RPS | ~5,000/day | $0 |
| **Builder** | 50 RPS | ~500,000/day | $149/mo |
| **Pro** | 150 RPS | ~1.5M/day | $599/mo |
| **Enterprise** | Custom | Custom | Contact sales |
When you exceed your quota, the API returns `429 Too Many Requests` with a `Retry-After` header.
### Automatic Retry Behavior
The MCP server **automatically retries** rate-limited requests using exponential backoff with jitter:
```
Request → 429 (rate limit)
↓ Wait 1 second
Retry 1 → 429
↓ Wait 2 seconds (exponential backoff)
Retry 2 → 429
↓ Wait 4 seconds
Retry 3 → 200 OK (success!)
```
**You don't need to handle retries manually** - the server handles them transparently.
### Retry Configuration
Customize retry behavior in `config.yaml`:
```yaml
retry_policy:
# Maximum retry attempts before raising error
max_attempts: 5
# Base delay for exponential backoff (seconds)
base_delay: 1
# Maximum delay between retries (seconds)
max_delay: 60
# Exponential backoff multiplier
exponential_base: 2
```
**Delay sequence** (with exponential_base=2):
- Retry 1: 1 second
- Retry 2: 2 seconds
- Retry 3: 4 seconds
- Retry 4: 8 seconds
- Retry 5: 16 seconds
Total maximum wait: ~31 seconds (if all retries needed).
### Rate Limit Error Messages
If retries are exhausted, you'll see an actionable error:
```
RateLimitError: Rate limit exceeded after 5 retry attempts.
Retry after 60 seconds. Consider upgrading tier or reducing
request frequency. See: https://zerion.io/pricing
```
**Next steps**:
1. Wait for the `retry_after` duration (from error message)
2. Reduce request frequency in your app
3. Upgrade to a higher tier if needed
### Rate Limiting Best Practices
#### 1. Use Webhooks Instead of Polling
**Bad** (polling):
```python
# Check for new transactions every 10 seconds
while True:
transactions = get_transactions(address)
time.sleep(10)
```
**Cost**: 8,640 requests/day (exceeds Developer tier quota!)
**Good** (webhooks):
```python
# Webhook delivers new transactions as they happen
# 0 polling requests, only create subscription once
create_webhook_subscription(addresses=[address])
```
**Cost**: 1 request total 🎯
#### 2. Implement Client-Side Caching
```python
from functools import lru_cache
import time
@lru_cache(maxsize=100)
def get_portfolio(address, ttl_hash):
return fetch_wallet_portfolio(address)
# Cache for 5 minutes
def get_ttl_hash(seconds=300):
return round(time.time() / seconds)
# Usage
portfolio = get_portfolio(address, get_ttl_hash())
```
#### 3. Use Filters to Reduce Data Volume
Smaller responses = faster processing = fewer timeout retries:
```
Use listWalletTransactions with:
- filter[chain_ids]: "ethereum"
- filter[trash]: "only_non_trash"
- page[size]: 50
```
### Monitoring Rate Limit Status
The server logs rate limit events:
```
WARNING: Rate limit exceeded (url=/v1/wallets/.../transactions, retry_after=30s)
INFO: Retrying request after rate limit (attempt=2)
INFO: Request succeeded after 2 retry attempts
```
Enable **DEBUG** logging to see detailed retry information:
```yaml
logging:
level: "DEBUG"
```
### Disabling Automatic Retry
To disable automatic retry (e.g., for testing):
```yaml
retry_policy:
max_attempts: 0 # Disable retries
```
Now `429` responses will immediately raise `RateLimitError`.
---
## Error Handling - 202 Accepted (Wallet Indexing)
When you query a **newly created wallet** (first request for that address), Zerion may return `202 Accepted` instead of `200 OK`. This means:
> "Wallet is being indexed. Data will be ready in 2-10 seconds."
### Automatic 202 Retry
The MCP server **automatically retries** `202` responses with a fixed delay:
```
Request → 202 Accepted (indexing...)
↓ Wait 3 seconds
Retry 1 → 202 Accepted (still indexing...)
↓ Wait 3 seconds
Retry 2 → 200 OK (indexing complete!)
```
**You don't see `202` responses** - the server handles them transparently.
### When Does 202 Occur?
- **First request to a new wallet address**: Zerion hasn't indexed it yet
- **Recently created on-chain wallet**: Blockchain confirmed, Zerion indexing in progress
- **Rare edge case**: Heavy load on Zerion's indexing service
**Typical indexing time**: 2-10 seconds (usually 3-5 seconds).
### 202 Configuration
Customize retry behavior in `config.yaml`:
```yaml
wallet_indexing:
# Delay between retries (seconds)
retry_delay: 3
# Maximum retry attempts
max_retries: 3
# Automatically retry (recommended: true)
auto_retry: true
```
**Total wait time**: `retry_delay × max_retries` (e.g., 3s × 3 = 9 seconds).
### 202 Error Messages
If indexing times out after max retries:
```
WalletIndexingError: Wallet is still being indexed by Zerion.
Tried 3 times over 9 seconds. Please retry in 30-60 seconds.
```
**Next steps**:
1. Wait 30-60 seconds for Zerion to complete indexing
2. Retry your request
3. If issue persists, contact api@zerion.io
### Disabling 202 Auto-Retry
To disable automatic retry (e.g., for instant feedback):
```yaml
wallet_indexing:
auto_retry: false
```
Now `202` responses will immediately raise:
```
WalletIndexingError: Wallet indexing in progress. This is a
new wallet address for Zerion. Enable auto_retry in
configuration or wait and retry manually.
```
### 202 Logging
The server logs indexing events:
```
INFO: Wallet indexing in progress, will retry (retry_delay=3s, max_retries=3)
INFO: Retrying wallet indexing request (attempt=1/3)
INFO: Wallet indexing completed successfully (attempts=2, total_wait=6s)
```
Or if timeout:
```
WARNING: Wallet indexing timeout (attempts=3, total_wait=9s)
```
### Troubleshooting 202 Errors
#### "Indexing timeout after 3 retries"
**Cause**: Wallet indexing taking longer than expected (>9 seconds).
**Solution**:
1. Increase `max_retries` or `retry_delay`:
```yaml
wallet_indexing:
retry_delay: 5
max_retries: 5
```
New total wait: 5s × 5 = 25 seconds
2. Wait 1-2 minutes and retry manually
#### "This is a new wallet address"
**Cause**: Normal behavior for first request to a wallet.
**Solution**: No action needed if `auto_retry: true` (default). The server will retry automatically.
---
## Testnet Support
Certain Zerion API endpoints support testnet data through the `X-Env` header parameter. This allows developers to test applications on testnets before deploying to mainnet.
### Supported Testnet Endpoints
The following endpoints accept the `X-Env` header:
- **`listWalletPositions`** - Get wallet positions on testnets
- **`getWalletPortfolio`** - Get portfolio data for testnet wallets
- **`listWalletTransactions`** - Fetch testnet transaction history
- **`listWalletNFTPositions`** - Get NFT positions on testnets
- **`listWalletNFTCollections`** - List NFT collections on testnets
- **`getWalletNftPortfolio`** - Get NFT portfolio for testnets
- **`listFungibles`** - List fungible assets on testnets
- **`getFungibleById`** - Get specific fungible on testnets
- **`listChains`** - List chains (including testnets)
### Using Testnet Data
To query testnet data, include `X-Env: testnet` when calling supported endpoints:
```
Use listWalletPositions with:
- address: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
- X-Env: "testnet"
- currency: "usd"
```
This will return positions for the specified address on testnet chains (e.g., Ethereum Sepolia, Monad Testnet).
### Testnet API Access
**Important**: Testnet access may require special API credentials or specific tier access. Check your API key capabilities:
- Contact api@zerion.io for testnet API access
- Verify your tier includes testnet support
- Some testnets may have limited data availability
### Testnet Development Workflow
**Recommended workflow for testnet-first development:**
1. **Create Test Wallet on Testnet** (e.g., Sepolia)
2. **Fund with Testnet Tokens** (use faucets)
3. **Test MCP Tools** with `X-Env: testnet`
4. **Verify Data Accuracy** on testnet
5. **Deploy to Mainnet** after validation
**Example - Testing Portfolio Fetch**:
```
# Test on Sepolia first
Use getWalletPortfolio with:
- address: "0x..."
- X-Env: "testnet"
- currency: "usd"
# Then move to mainnet
Use getWalletPortfolio with:
- address: "0x..."
- currency: "usd"
```
### Supported Testnet Chains
Use `listChains` with `X-Env: testnet` to see all available testnet chains. Common testnets include:
- **Ethereum Sepolia** (`sepolia`)
- **Monad Testnet** (`monad-testnet`)
- **Base Sepolia** (`base-sepolia`)
- **Optimism Sepolia** (`optimism-sepolia`)
- **Arbitrum Sepolia** (`arbitrum-sepolia`)
**Note**: Testnet chain availability may vary. Use the `listChains` endpoint to get the current list.
### Testnet Limitations
- **Data Freshness**: Testnet indexing may be slower than mainnet
- **Historical Data**: Some testnets have limited historical data
- **Protocol Coverage**: Not all DeFi protocols deployed on testnets
- **Price Data**: Testnet tokens typically have no market price
---
## Multi-Currency Support
The Zerion API supports multiple currencies for price denomination. You can request portfolio values, position prices, and charts in USD, ETH, EUR, or BTC.
### Supported Currencies
| Currency | Code | Use Case |
|----------|------|----------|
| **US Dollar** | `usd` | Default, most common for general users |
| **Ethereum** | `eth` | DeFi analytics, ETH-native communities |
| **Euro** | `eur` | European users, EU compliance requirements |
| **Bitcoin** | `btc` | Bitcoin-maximalist perspectives |
### Currency-Compatible Endpoints
The `currency` parameter is supported on these endpoints:
- **`getWalletPortfolio`** - Portfolio total value in specified currency
- **`listWalletPositions`** - Position values in specified currency
- **`getWalletChart`** - Historical balance chart in specified currency
- **`getWalletPNL`** - Profit/Loss calculations in specified currency
- **`getFungibleChart`** - Asset price charts in specified currency
### Using Different Currencies
**USD (Default)**:
```
Use getWalletPortfolio with:
- address: "0x..."
- currency: "usd"
```
**ETH Denomination**:
```
Use getWalletPortfolio with:
- address: "0x..."
- currency: "eth"
```
This returns portfolio value in ETH. For example, if a wallet is worth $10,000 and ETH is $2,000, the value would be shown as 5 ETH.
**EUR Denomination**:
```
Use listWalletPositions with:
- address: "0x..."
- currency: "eur"
- filter[chain_ids]: "ethereum"
```
All position values will be shown in EUR instead of USD.
**BTC Denomination**:
```
Use getWalletChart with:
- address: "0x..."
- currency: "btc"
- period: "month"
```
Historical portfolio values will be shown in BTC equivalent.
### Currency Parameter Behavior
**Default Behavior**: If `currency` parameter is omitted, USD is used by default.
**Price Fields Affected**: The currency parameter affects:
- `attributes.value` - Total value
- `attributes.price` - Individual asset prices
- `attributes.changes` - Value changes over time
- `attributes.floor_price` - NFT floor prices (where applicable)
**Exchange Rates**: Zerion uses real-time exchange rates for currency conversion. Rates are updated continuously.
### Multi-Currency Examples
**Example 1: DeFi Portfolio in ETH**
```
Use listWalletPositions with:
- address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
- filter[positions]: "only_complex"
- currency: "eth"
```
Result: All DeFi position values shown in ETH denomination.
**Example 2: European User Portfolio**
```
Use getWalletPortfolio with:
- address: "0x..."
- currency: "eur"
```
Result: Portfolio value and all asset prices in EUR.
**Example 3: Historical Performance in BTC**
```
Use getWalletChart with:
- address: "0x..."
- currency: "btc"
- period: "year"
```
Result: Year-long portfolio performance chart denominated in BTC.
### Currency Best Practices
1. **Use USD for General Applications** - Most users expect USD pricing
2. **Use ETH for DeFi Dashboards** - DeFi users often think in ETH terms
3. **Use EUR for EU Compliance** - Required for some European regulatory reporting
4. **Use BTC for Bitcoin Communities** - Aligns with Bitcoin-centric worldview
---
## Development
### Setup Development Environment
```bash
# Clone and install with dev dependencies
git clone https://github.com/SAK1337/myzerionmcp.git
cd myzerionmcp
pip install -e ".[dev]"
# Set up API key
export ZERION_API_KEY="Bearer your-test-key"
```
### Running Tests
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=zerion_mcp_server --cov-report=html
# Run specific test file
pytest tests/test_config.py
# Run with verbose output
pytest -v
```
### Code Quality
```bash
# Type checking (if mypy is installed)
mypy zerion_mcp_server
# Linting (if ruff is installed)
ruff check zerion_mcp_server
```
## Troubleshooting
### Common Issues
#### "Configuration error: Missing required configuration: api_key"
**Solution**: Set the `ZERION_API_KEY` environment variable:
```bash
export ZERION_API_KEY="Bearer your-api-key-here"
```
#### "Timeout loading OpenAPI specification"
**Solution**: Check your internet connection. The server needs to download the OpenAPI spec from GitHub.
#### "Unauthorized: Invalid or missing API key"
**Solution**: Verify your API key is correct and includes the "Bearer " prefix:
```bash
export ZERION_API_KEY="Bearer your-actual-key"
```
#### "Rate limit exceeded"
**Solution**: Wait for the rate limit window to reset. Check the error message for `retry_after_sec` value.
### Debug Mode
Enable debug logging for detailed information:
```bash
export LOG_LEVEL="DEBUG"
zerion-mcp-server
```
Or in `config.yaml`:
```yaml
logging:
level: "DEBUG"
format: "json" # Structured logs for analysis
```
### Log Interpretation
- **INFO**: Normal operation (startup, requests)
- **WARN**: Potential issues (slow operations)
- **ERROR**: Failures (API errors, network issues)
- **DEBUG**: Detailed traces (request/response bodies)
## Architecture
```
┌─────────────────┐
│ MCP Client │ (e.g., Claude Desktop)
│ (AI Assistant) │
└────────┬────────┘
│ MCP Protocol
│
┌────────▼────────┐
│ FastMCP Server │
│ │
│ ┌───────────┐ │
│ │ Config │ │ (YAML + Env)
│ │ Manager │ │
│ └───────────┘ │
│ │
│ ┌───────────┐ │
│ │ Logger │ │ (Structured)
│ └───────────┘ │
│ │
│ ┌───────────┐ │
│ │ Error │ │ (Custom Exceptions)
│ │ Handler │ │
│ └───────────┘ │
│ │
│ ┌───────────┐ │
│ │ HTTP │ │ (httpx AsyncClient)
│ │ Client │ │
│ └─────┬─────┘ │
└────────┼────────┘
│
│ HTTPS
│
┌────────▼────────┐
│ Zerion API │
│ │
│ - Portfolios │
│ - DeFi │
│ - NFTs │
│ - Transactions │
└─────────────────┘
```
## Tech Stack
- **Python 3.11+**: Core language
- **FastMCP**: MCP server framework with OpenAPI integration
- **httpx**: Async HTTP client
- **PyYAML**: Configuration parsing
- **pytest**: Testing framework
## Contributing
Contributions are welcome! Please follow these guidelines:
1. **Fork the repository**
2. **Create a feature branch**: `git checkout -b feature/your-feature`
3. **Write tests** for your changes
4. **Ensure tests pass**: `pytest`
5. **Submit a pull request**
### Development Workflow
- Follow PEP 8 style guidelines
- Add type hints to function signatures
- Write docstrings for modules and functions
- Update tests for any code changes
- Keep commits focused and atomic
## License
MIT License - see [LICENSE](LICENSE) file for details
## Support
- **Issues**: [GitHub Issues](https://github.com/SAK1337/myzerionmcp/issues)
- **Zerion API Docs**: [developers.zerion.io](https://developers.zerion.io/)
- **MCP Specification**: [modelcontextprotocol.io](https://modelcontextprotocol.io/)
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for version history and changes
