zerion

What this skill does

# 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](https://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

```bash
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.

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

Response:
```json
{
  "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 by `group_id` to display LP holdings together.

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:
```json
{
  "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.

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

### GET /v1/subscriptions

List al