Zerion: Wallet Intelligence for AI Agents

Zerion provides interpreted, enriched crypto wallet data across 41+ chains including Ethereum, Base, Arbitrum, Optimism, Polygon, Solana, and more.

Unlike raw RPC data, Zerion returns:

• USD values for all positions
• Protocol labels (Uniswap, Aave, Lido, etc.)
• Human-readable transaction types (swap, stake, bridge, mint, burn)
• PnL calculations (realized, unrealized, per-asset, FIFO method)
• DeFi position breakdowns (deposits, borrows, LP positions with

  group_id

  )
• NFT portfolios with floor prices and collection metadata
• Spam filtering built-in

Two ways to access:

• x402 (no account needed): Pay $0.01 USDC per request on Base. No API key, no signup.
• API key: Get a free key instantly at dashboard.zerion.io for higher rate limits.

Research → Execute Pattern

Zerion is the research layer. Use it to analyze wallets, find opportunities, track PnL. Then hand off to Bankr for execution (swaps, stop-losses, DCA).

Zerion (Research)          Bankr (Execute)
─────────────────         ────────────────
Portfolio analysis   →    Rebalance trades
PnL tracking         →    Stop-loss orders
Position monitoring  →    Take-profit orders
Whale watching       →    Copy trades
Swap quotes          →    Execute best route
NFT floor tracking   →    Buy/sell NFTs

CLI Quick Start

npm install -g zerion-cli

# Set API key
export ZERION_API_KEY="zk_..."

# Or use x402 (no key needed)
zerion-cli wallet portfolio 0x... --x402

# Commands
zerion-cli wallet portfolio <address>      # Total USD value
zerion-cli wallet positions <address>      # All token positions
zerion-cli wallet transactions <address>   # Transaction history
zerion-cli wallet pnl <address>            # Profit & loss
zerion-cli wallet analyze <address>        # Full analysis
zerion-cli chains list                     # Supported chains

Wallet Endpoints

GET /v1/wallets/{address}/portfolio

Returns aggregated portfolio value across all chains.

curl "https://api.zerion.io/v1/wallets/0x.../portfolio?currency=usd" \
  -H "Authorization: Basic $(echo -n $ZERION_API_KEY: | base64)"

Response:

{
  "data": {
    "attributes": {
      "total": { "positions": 44469.60 },
      "positions_distribution_by_type": {
        "wallet": 40000,
        "deposited": 3000,
        "staked": 1469.60
      },
      "positions_distribution_by_chain": {
        "base": 27495.06,
        "ethereum": 6216.25,
        "arbitrum": 1234.56
      },
      "changes": {
        "absolute_1d": 305.86,
        "percent_1d": 0.69
      }
    }
  }
}

GET /v1/wallets/{address}/positions

Returns all fungible token and DeFi positions.

Query params:

• filter[positions]

  :

  only_simple

  (tokens only),

  only_defi

  (protocol positions),

  no_filter

  (all)

• filter[chain_ids]

  : Comma-separated chain IDs (e.g.,

  base,ethereum,arbitrum

  )

• filter[trash]

  :

  only_non_trash

  (exclude spam),

  only_trash

  ,

  no_filter

• sort

  :

  value

  or

  -value

Understanding LP Positions: Liquidity pools return multiple positions (one per token) with shared

group_id

group_id

Response includes:

• Token symbol, name, icon URL
• Quantity (int, float, decimals, numeric)
• USD value and price
• Position type:

  wallet

  ,

  deposited

  ,

  borrowed

  ,

  staked

  ,

  locked

• Protocol name and DApp relationship

• group_id

  for LP position grouping

GET /v1/wallets/{address}/transactions

Returns interpreted transaction history.

Query params:

• filter[chain_ids]

  : Filter by chains

• filter[asset_types]

  :

  fungible

  ,

  nft

• filter[trash]

  :

  only_non_trash

  ,

  no_filter

• page[size]

  : Results per page (default 20)

• page[after]

  : Cursor for pagination

Each transaction includes:

• operation_type

  :

  trade

  ,

  send

  ,

  receive

  ,

  approve

  ,

  stake

  ,

  unstake

  ,

  borrow

  ,

  repay

  ,

  bridge

  ,

  mint

  ,

  burn

  ,

  bid

  ,

  execute

• transfers

  array with direction, token info, quantities, USD values

• fee

  with gas cost in native token and USD

• application_metadata

  with contract address and method info
• Related

  dapp

  and

  chain

  relationships

GET /v1/wallets/{address}/pnl

Returns Profit and Loss using FIFO method.

Query params:

• currency

  :

  usd

  (default)

• filter[chain_ids]

  : Comma-separated chain IDs

Response:

{
  "data": {
    "attributes": {
      "total_gain": -15076.15,
      "realized_gain": 45328.28,
      "unrealized_gain": -60404.44,
      "relative_total_gain_percentage": -5.65,
      "relative_realized_gain_percentage": 28.08,
      "relative_unrealized_gain_percentage": -57.36,
      "total_fee": 681.81,
      "total_invested": 266672.34,
      "realized_cost_basis": 161370.01,
      "net_invested": 105302.33,
      "received_external": 128217.01,
      "sent_external": 67415.77,
      "sent_for_nfts": 4333.36,
      "received_for_nfts": 423.01
    }
  }
}

GET /v1/wallets/{address}/chart

Returns portfolio balance chart over time.

Query params:

• currency

  :

  usd

• filter[chain_ids]

  : Filter by chains

• period

  : Time period for chart

GET /v1/wallets/{address}/nft-portfolio

Returns NFT portfolio overview with total estimated value.

GET /v1/wallets/{address}/nft-positions

Returns list of NFT positions held by wallet.

Query params:

• filter[chain_ids]

  : Filter by chains

• sort

  : Sort order
• Pagination supported

GET /v1/wallets/{address}/nft-collections

Returns NFT collections held by wallet with floor prices.

Fungibles (Token) Endpoints

GET /v1/fungibles

Returns paginated list of fungible assets. Supports search.

Query params:

• filter[search_query]

  : Search by name or symbol

• filter[implementation_chain_id]

  : Filter by chain

• filter[implementation_address]

  : Filter by contract address

• sort

  : Sort order

GET /v1/fungibles/{fungible_id}

Returns single fungible asset by ID.

GET /v1/fungibles/implementation/{chain}:{address}

Returns fungible by chain:address pair (e.g.,

ethereum:0xa5a4...

GET /v1/fungibles/{fungible_id}/chart

Returns price chart for fungible asset.

Query params:

• filter[period]

  :

  hour

  ,

  day

  ,

  week

  ,

  month

  ,

  year

  ,

  max

NFT Endpoints

GET /v1/nfts

Returns list of NFTs with metadata.

Query params:

• Filter and pagination supported

GET /v1/nfts/{nft_id}

Returns single NFT by ID with full metadata, traits, and collection info.

DApp Endpoints

GET /v1/dapps

Returns list of DApps (protocols) indexed by Zerion.

GET /v1/dapps/{dapp_id}

Returns single DApp with metadata, supported chains, and categories.

Chain Endpoints

GET /v1/chains

Returns all 41+ supported chains with metadata.

GET /v1/chains/{chain_id}

Returns single chain by ID.

Gas Prices

GET /v1/gas-prices

Returns real-time gas prices across all supported chains.

Useful for:

• Estimating transaction costs
• Choosing optimal chain for execution
• Timing transactions for lower fees

Swap & Bridge Quotes

GET /v1/swap/offers

Returns swap/bridge quotes from multiple providers (aggregator).

Query params:

• Input/output tokens
• Amount
• Slippage tolerance

Returns quotes from 0x, 1inch, Uniswap, and more. Zerion charges 0.5% on L2/alt-L1 trades (waived with Genesis NFT).

Note: Response time is 5-10 seconds due to multi-provider aggregation.

GET /v1/swap/fungibles

Returns fungibles available for bridge exchange (cross-chain swaps).

Webhooks (Subscriptions)

Real-time notifications for wallet activity.

POST /v1/subscriptions/wallet-transactions

Create subscription for wallet transactions.

{
  "data": {
    "type": "subscriptions",
    "attributes": {
      "wallet_addresses": ["0x...", "0x..."],
      "chain_ids": ["base", "ethereum"],
      "callback_url": "https://your-server/webhook"
    }
  }
}

GET /v1/subscriptions

List all subscriptions.

GET /v1/subscriptions/{id}

Get subscription by ID.

DELETE /v1/subscriptions/{id}

Delete subscription.

POST /v1/subscriptions/{id}/enable

Enable a disabled subscription.

POST /v1/subscriptions/{id}/disable

Disable subscription (pause notifications).

PATCH /v1/subscriptions/{id}/wallets

Add/remove wallets from subscription.

PUT /v1/subscriptions/{id}/wallets

Replace all wallets in subscription.

PUT /v1/subscriptions/{id}/callback-url

Update callback URL.

PUT /v1/subscriptions/{id}/chain-ids

Update monitored chains.

GET /v1/subscriptions/{id}/wallets

List wallets in subscription.

GET /v1/subscriptions/{id}/wallets/count

Count wallets in subscription.

Webhook Payload:

• Signed with X-Signature header (RSA, verify with certificate)
• Includes X-Timestamp and X-Certificate-URL headers
• Transaction data with full interpretation
• Prices are

  null

  in webhooks (query transactions endpoint for prices)

Limits:

• Dev key: 1 subscription, 5 wallets max
• Production: Contact api@zerion.io for whitelist

API Key Access

Get a free API key instantly — no credit card required:

1. Go to dashboard.zerion.io
2. Sign up with email or connect wallet
3. Click "Create API Key" — key starts with

   zk_...

4. Copy and use immediately

export ZERION_API_KEY="zk_your_api_key"

curl "https://api.zerion.io/v1/wallets/0x.../portfolio" \
  -H "Authorization: Basic $(echo -n $ZERION_API_KEY: | base64)"

Rate Limits

x402 has no rate limits — pay per request ($0.01 USDC each).

x402 Access (Recommended for Agents)

x402 allows agents to pay per request without API keys. Payment is $0.01 USDC on Base.

// Using x402 HTTP flow
const response = await fetch('https://api.zerion.io/v1/wallets/0x.../portfolio', {
  headers: {
    'X-402-Payment': signedPaymentHeader // ERC-3009 signature
  }
});

With zerion-cli:

zerion-cli wallet portfolio 0x... --x402

Testnet Support

Add

X-Env: testnet

curl "https://api.zerion.io/v1/wallets/0x.../portfolio" \
  -H "Authorization: Basic ..." \
  -H "X-Env: testnet"

Integration with Bankr

Example: PnL Guardian

Monitor positions and auto-set stop-losses:

#!/bin/bash
# Research with Zerion
positions=$(zerion-cli wallet positions $WALLET --json)

# Find volatile tokens on Base
risky=$(echo $positions | jq '[.data[] | select(.relationships.chain.data.id == "base") | select(.attributes.value > 500)]')

# Execute with Bankr
for token in $(echo $risky | jq -r '.[].attributes.fungible_info.symbol'); do
  bankr "set stop loss on $token at -20%"
done

Example: Whale Copy Trading

Watch a whale wallet and mirror trades:

// Webhook handler
app.post('/webhook/zerion', async (req, res) => {
  const { type, data } = req.body;

  if (type === 'transaction' && data.operation_type === 'trade') {
    const { transfers } = data;
    const bought = transfers.find(t => t.direction === 'in');

    if (bought && bought.value > 1000) {
      // Mirror the trade via Bankr
      await bankr(`buy $100 of ${bought.fungible_info.symbol}`);
    }
  }
});

Example: Best Swap Route

Get quotes from Zerion, execute via Bankr:

// Get swap quote from Zerion
const quote = await zerion.get('/v1/swap/offers', {
  params: { from: 'USDC', to: 'ETH', amount: '1000' }
});

const bestRate = quote.data[0];
console.log(`Best rate: ${bestRate.rate} from ${bestRate.provider}`);

// Execute via Bankr
await bankr(`swap $1000 USDC to ETH on base`);

Supported Chains

All 41+ chains including:

ethereum

base

arbitrum

optimism

polygon

solana

zksync-era

linea

scroll

blast

zora

degen

berachain

monad

abstract

Full list: https://developers.zerion.io/reference/supported-blockchains

MCP Server

Connect Claude, Cursor, or any MCP client:

{
  "mcpServers": {
    "zerion": {
      "command": "npx",
      "args": ["zerion-mcp-server"],
      "env": {
        "ZERION_API_KEY": "zk_..."
      }
    }
  }
}

Error Handling

Note: 202 responses mean data is being indexed. Retry every few seconds until 200. Stop after 2 minutes if still 202.

Resources

• Get API Key: https://dashboard.zerion.io (free, instant, no credit card)
• API Documentation: https://developers.zerion.io
• Supported Chains: https://developers.zerion.io/reference/supported-blockchains
• CLI Repository: https://github.com/zeriontech/zerion-cli
• MCP Server: https://github.com/zeriontech/zerion-mcp-server
• x402 Protocol: https://developers.zerion.io/reference/x402
• Zerion for Agents: https://zerion.io/agents
• Spam Filtering: https://developers.zerion.io/reference/token-spam-filtering
• FAQs: https://developers.zerion.io/reference/faqs