ZerionSAFE

Bankr Skills equip builders with plug-and-play tools to build more powerful agents.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: zerion
description: Interpreted crypto wallet data for AI agents. Use when an agent needs portfolio values, token positions, DeFi positions, NFT holdings, transaction history, PnL data, token prices, charts, gas prices, swap quotes, or DApp information across 41+ chains. Zerion transforms raw blockchain data into agent-ready JSON with USD values, protocol labels, and enriched metadata. Supports x402 pay-per-request ($0.01 USDC on Base) and API key access. Triggers on mentions of portfolio, wallet analysis, positions, transactions, PnL, profit/loss, DeFi, token balances, NFTs, swap quotes, gas prices, or Zerion.
---

# 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 positi

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (1)

x402 enables pay-per-request API access without signup or API keys. Agents pay $0.01 USDC on Base per request.

Gates applied: no_behavioural_pass.