> ## Documentation Index
> Fetch the complete documentation index at: https://developers.zerion.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Zerion CLI and agent skills for AI coding tools

> Analyze wallets, sign, swap, and bridge across EVM chains and Solana from the command line, plus agent skills that ship across every major AI coding agent.

The Zerion CLI is an open-source tool that wraps Zerion API and a local encrypted wallet vault. The same binary powers both humans and AI agents - any agent that can run shell commands can analyze wallets, sign messages, and execute swaps without writing API integration code. Wallet management is built on the [Open Wallet Standard](https://github.com/open-wallet-standard/core).

Six agent skills ship alongside the CLI for AI coding agents (Claude Code, Cursor, Windsurf, Codex, Gemini, OpenCode, and any [agentskills.io](https://agentskills.io) host).

**Repository:** [github.com/zeriontech/zerion-ai](https://github.com/zeriontech/zerion-ai) - CLI and skills ship from the same repo.

<Note>
  **Alpha Preview** - The CLI is under active development. Commands, flags, and output formats may change between releases. Don't depend on current behavior in production workflows.
</Note>

## Installation

One-shot setup - installs the CLI globally, configures your API key, and adds skills across all detected coding agents:

```bash theme={null}
npx zerion-cli init
```

* `-y` runs setup non-interactively
* `--browser` opens [dashboard.zerion.io](https://dashboard.zerion.io) so you can grab an API key and paste it back
* Skills install globally to every detected AI coding agent

Or install the CLI binary on its own:

```bash theme={null}
npm install -g zerion-cli
```

Requires Node.js 20 or later.

## Authentication

Three options. The CLI auto-detects which is active.

### API key (recommended)

Get a free key at [dashboard.zerion.io](https://dashboard.zerion.io). Keys begin with `zk_`.

```bash theme={null}
export ZERION_API_KEY="zk_..."
```

Or persist it via config:

```bash theme={null}
zerion config set apiKey zk_...
```

Required for analysis and trading. Analysis can also use x402 / MPP pay-per-call.

### x402 pay-per-call

No API key needed. Pays \$0.01 USDC per request via the [x402 protocol](https://www.x402.org/). Supports EVM (Base) and Solana.

```bash theme={null}
export WALLET_PRIVATE_KEY="0x..."     # EVM (Base) - 0x-prefixed hex
export WALLET_PRIVATE_KEY="5C1y..."   # Solana - base58 keypair

zerion analyze 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --x402
```

Enable globally:

```bash theme={null}
export ZERION_X402=true
```

Both chains simultaneously:

```bash theme={null}
export EVM_PRIVATE_KEY="0x..."
export SOLANA_PRIVATE_KEY="5C1y..."
export ZERION_X402_PREFER_SOLANA=true
```

<Note>
  Pay-per-call applies to analytics commands only (`portfolio`, `positions`, `history`, `pnl`, `analyze`). Trading commands always use an API key.
</Note>

### MPP pay-per-call

No API key needed. Pays \$0.01 USDC per request via the [MPP protocol](https://mpp.dev) on [Tempo](https://tempo.xyz). EVM only.

```bash theme={null}
export WALLET_PRIVATE_KEY="0x..."     # or a dedicated key:
export TEMPO_PRIVATE_KEY="0x..."

zerion portfolio 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --mpp
```

Enable globally:

```bash theme={null}
export ZERION_MPP=true
```

## Skills

The CLI ships with six agent skills that install into AI coding agents. Each skill is self-contained - your agent loads the relevant one based on your intent.

| Skill | What it does |
| - | - |
| `zerion` | Umbrella entry - install, authentication, routing to capability skills, chains reference |
| `zerion-analyze` | Read-only wallet insights: portfolio, positions, history, PnL, watchlist (supports x402 / MPP) |
| `zerion-trading` | Swap, bridge, send tokens (onchain actions; needs API key + agent token) |
| `zerion-sign` | Off-chain signing - sign-message (EIP-191 / raw), sign-typed-data (EIP-712) |
| `zerion-wallet` | Wallet management - create, import, list, fund, backup, delete, sync |
| `zerion-agent-management` | Agent tokens + policies (the autonomous-trading primitives) |

Install or reinstall skills:

```bash theme={null}
zerion setup skills                          # all detected agents (default: global)
zerion setup skills --agent claude-code      # scope to one agent
zerion setup skills -g                       # force global install
```

Per-host plugin installs (alternative to `setup skills`):

```bash theme={null}
# Claude Code
/plugin marketplace add zeriontech/zerion-ai
/plugin install zerion-agent@zerion

# OpenAI Codex CLI
codex plugin marketplace add zeriontech/zerion-ai
# then run /plugins, choose the zerion marketplace, install zerion-agent

# Cursor
npx skills add zeriontech/zerion-ai --agent cursor

# OpenCode
npx skills add zeriontech/zerion-ai --agent opencode

# Gemini CLI
gemini extensions install https://github.com/zeriontech/zerion-ai

# Any agentskills.io host
npx skills add zeriontech/zerion-ai
```

## Manual setup, agent execution

The CLI splits cleanly into two surfaces, by design.

* **Wallet management and agent token setup are manual.** `wallet create`, `import`, `backup`, and `delete` prompt for a passphrase. `wallet sync` emits a QR code you scan with the Zerion app. `agent create-token` mints a scoped trading credential bound to a specific wallet, and `agent create-policy` attaches the rules it must obey - allowed chains, expiry, transfer/approval gates, contract allowlists. No key material moves and no spending credential widens without you in the loop.
* **Analysis, signing, trading, and discovery are for agents.** `analyze`, `portfolio`, `positions`, `history`, `pnl`, `sign-message`, `sign-typed-data`, `swap`, `bridge`, `send`, `search`, `chains`, and read-only listings emit JSON to stdout, structured errors to stderr, and skip confirmation dialogs. Once an agent token is configured, signing and trading fire immediately.

You stage by hand once - create or import a wallet, set a passphrase, mint an agent token, attach a policy. Then you hand the agent token to an automation that can only do what the policy allows. Treat agent tokens like API keys with spending power.

## Commands

Every command supports `--help` for full flag documentation. Run `zerion --help` for the top-level command list.

### Analyze

Read-only wallet insights. Supports `--x402` and `--mpp` for pay-per-call.

```bash theme={null}
# Full analysis - portfolio, positions, transactions, PnL in parallel
zerion analyze vitalik.eth

# Targeted reads
zerion portfolio 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
zerion positions vitalik.eth --defi                 # grouped by protocol, loans netted
zerion positions vitalik.eth --positions defi       # flat list of DeFi positions
zerion history vitalik.eth --limit 10 --chain ethereum
zerion pnl vitalik.eth
```

#### Analyze options

| Command | Description |
| - | - |
| `zerion analyze <address\|ens>` | Full analysis - portfolio, positions, transactions, PnL in parallel |
| `zerion portfolio <address\|ens>` | Portfolio value and top positions |
| `zerion positions <address\|ens>` | Token + DeFi positions (`--positions all\|simple\|defi`, or `--defi` for grouped-by-protocol view) |
| `zerion history <address\|ens>` | Transaction history (`--limit`, `--chain`) |
| `zerion pnl <address\|ens>` | Profit & loss (realized, unrealized, fees) |
| `zerion search <query>` | Search tokens by name or symbol |
| `zerion chains` | List supported chains |

### Trade

Requires an API key plus an agent token for unattended use. Chain is the first positional argument.

```bash theme={null}
# Same-chain swap - zerion swap <chain> <amount> <from> <to>
zerion swap base 1 USDC ETH
zerion swap ethereum 0.1 ETH USDC
zerion swap solana 0.1 SOL USDC
zerion swap monad 1 USDC MON

# List tokens available for swap on a chain
zerion swap tokens base
zerion swap tokens solana

# Bridge - zerion bridge <from-chain> <from-token> <amount> <to-chain> <to-token>
# Default: list all provider offers (no transaction signed)
zerion bridge base USDC 5 arbitrum USDC

# Execute the highest-output offer
zerion bridge base USDC 5 arbitrum USDC --cheapest

# Execute the fastest offer
zerion bridge base USDC 5 arbitrum USDC --fast

# Bridge + swap on destination
zerion bridge base USDC 5 arbitrum ETH --cheapest

# Cross-format bridge (EVM ↔ Solana) - destination wallet required if source is EVM-only or Solana-only
zerion bridge ethereum USDC 50 solana USDC --to-wallet sol-bot --cheapest
zerion bridge ethereum USDC 50 solana USDC --to-address 8xLdox... --cheapest

# Send - chain auto-detected from recipient format
zerion send USDC 50 --to 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --chain base
zerion send SOL 0.1 --to 2Nsnn...
```

#### Trade options

| Command | Description |
| - | - |
| `zerion swap <chain> <amount> <from-token> <to-token>` | Same-chain swap |
| `zerion swap tokens [chain]` | List tokens available for swap |
| `zerion bridge <from-chain> <from-token> <amount> <to-chain> <to-token>` | List all bridge providers (multi-offer mode; no execute) |
| `zerion bridge ... --cheapest` | Execute the highest-output offer |
| `zerion bridge ... --fast` | Execute the lowest-time offer (falls back to `--cheapest` if no time data) |
| `zerion bridge ... --to-wallet <name>` | Destination wallet for cross-format bridges (Solana ↔ EVM) |
| `zerion bridge ... --to-address <addr>` | Raw destination address (must match destination-chain format) |
| `zerion send <token> <amount> --to <address>` | Send tokens (chain auto-inferred from address format) |
| `zerion send SOL <amount> --to <solana-pubkey>` | Send native SOL on Solana |

<Note>
  `--fast` and `--cheapest` are mutually exclusive. When used, the strategy flag must come last on the command line so flag parsing doesn't consume the next positional as its value. Single-offer routes auto-execute even without a strategy flag.
</Note>

### Sign

Off-chain signatures (EIP-191, EIP-712, Solana raw) - no broadcast. Requires an agent token.

```bash theme={null}
# EIP-191 (EVM) or raw (Solana)
zerion sign-message "Login to dApp" --chain ethereum

# Hex bytes
zerion sign-message 0xdeadbeef --encoding hex --chain ethereum

# EIP-712 typed data
zerion sign-typed-data --data "$(cat permit.json)"
zerion sign-typed-data --file permit.json
cat permit.json | zerion sign-typed-data
```

#### Sign options

| Command | Description |
| - | - |
| `zerion sign-message <message> --chain <chain>` | Sign EIP-191 (EVM) or raw (Solana) message |
| `zerion sign-message <message> --encoding hex` | Treat message as hex bytes |
| `zerion sign-typed-data --data '<json>'` | Sign EIP-712 typed data (EVM only) |
| `zerion sign-typed-data --file <path>` | Read EIP-712 typed data from file |

### Wallet

Encrypted local wallets. EVM + Solana supported. Passphrase required for destructive ops.

```bash theme={null}
zerion wallet create --name trading-bot
zerion wallet import --name old-wallet --evm-key
zerion wallet list
zerion wallet fund --wallet trading-bot
zerion wallet backup --wallet trading-bot
zerion wallet sync --wallet trading-bot
```

#### Wallet options

| Command | Description |
| - | - |
| `zerion wallet create --name <name>` | Create encrypted wallet (EVM + Solana) |
| `zerion wallet import --name <name> --evm-key` | Import from EVM private key (interactive) |
| `zerion wallet import --name <name> --sol-key` | Import from Solana private key (interactive) |
| `zerion wallet import --name <name> --mnemonic` | Import from seed phrase (all chains) |
| `zerion wallet list` | List all wallets |
| `zerion wallet fund` | Show deposit addresses for funding |
| `zerion wallet backup --wallet <name>` | Export recovery phrase |
| `zerion wallet delete <name>` | Permanently delete a wallet |
| `zerion wallet sync --wallet <name>` | Sync wallet to Zerion app via QR code |
| `zerion wallet sync --all` | Sync all wallets |

### Agent

Scoped API tokens for unattended trading. Tokens auto-save to config and are required for `swap`, `bridge`, `send`.

```bash theme={null}
# Create a tight policy first
zerion agent create-policy --name safe-base \
  --chains base \
  --expires 24h \
  --deny-transfers

# Mint a token bound to that policy
zerion agent create-token --name dca-bot \
  --wallet trading-bot \
  --policy safe-base
```

#### Agent token options

| Command | Description |
| - | - |
| `zerion agent create-token --name <bot> --wallet <wallet>` | Create scoped token |
| `zerion agent list-tokens` | List active agent tokens |
| `zerion agent use-token --wallet <wallet>` | Switch active token by wallet |
| `zerion agent revoke-token --name <bot>` | Revoke a token |

#### Agent policy options

| Command | Description |
| - | - |
| `zerion agent create-policy --name <policy>` | Create security policy (flags below) |
| `zerion agent list-policies` | List all policies |
| `zerion agent show-policy <id>` | Show policy details |
| `zerion agent delete-policy <id>` | Delete a policy |

#### Policy flags

| Flag | Description |
| - | - |
| `--chains <list>` | Restrict to specific chains (comma-separated) |
| `--expires <duration>` | Token expiry (e.g. `24h`, `7d`) |
| `--deny-transfers` | Block raw ETH/native transfers |
| `--deny-approvals` | Block ERC-20 approval calls |
| `--allowlist <addresses>` | Only allow listed contract/wallet addresses |

### Watch

Track wallets by name without exposing addresses in commands.

```bash theme={null}
zerion watch 0xFe89Cc7Abb2C4183683Ab71653c4cCd1b9cC194e --name ens-dao
zerion analyze ens-dao
```

#### Watch options

| Command | Description |
| - | - |
| `zerion watch <address> --name <label>` | Add wallet to watchlist |
| `zerion watch list` | List watched wallets |
| `zerion watch remove <name>` | Remove from watchlist |

### Setup

| Command | Description |
| - | - |
| `zerion init` | One-shot onboarding - install CLI globally, configure API key, install agent skills |
| `zerion init -y --browser` | Non-interactive init that opens dashboard.zerion.io for the API key |
| `zerion setup skills` | Install Zerion agent skills into detected coding agents |
| `zerion setup skills --agent claude-code` | Install into a specific agent |

### Config

| Command | Description |
| - | - |
| `zerion config set <key> <value>` | Set config (`apiKey`, `defaultWallet`, `defaultChain`, `slippage`) |
| `zerion config unset <key>` | Remove a config value (resets to default) |
| `zerion config list` | Show current configuration |

## Global options

| Flag | Description |
| - | - |
| `--wallet <name>` | Source wallet (default: from config) |
| `--address <addr\|ens>` | Use raw address or ENS name |
| `--watch <name>` | Use watched wallet by name |
| `--chain <chain>` | Chain for analysis commands (default: `ethereum`) |
| `--to-wallet <name>` | Destination wallet for cross-format `bridge` (Solana ↔ EVM) |
| `--to-address <addr>` | Raw destination address for `bridge` (must match destination-chain format) |
| `--positions all\|simple\|defi` | Filter positions type |
| `--defi` | On `positions`: shorthand for `--positions defi` with output grouped by protocol - LP tokens pooled by `group_id`, loans netted in `net_value` |
| `--limit <n>` | Limit results (default: 20) |
| `--offset <n>` | Skip first N results |
| `--search <query>` | Filter wallets by name or address |
| `--slippage <percent>` | Slippage tolerance (default: 2%, max: 3%) |
| `--timeout <sec>` | Confirmation timeout for trades (default: 120s) |
| `--cheapest` | For `bridge`: execute the highest-output offer |
| `--fast` | For `bridge`: execute the lowest-time offer |
| `--x402` | Pay-per-call on Base or Solana (analytics only) |
| `--mpp` | Pay-per-call on Tempo (analytics only) |
| `--json` | JSON output (default) |
| `--pretty` | Human-readable output |
| `--quiet` | Minimal output |

## Environment variables

| Variable | Description |
| - | - |
| `ZERION_API_KEY` | API key (get at [dashboard.zerion.io](https://dashboard.zerion.io)) |
| `WALLET_PRIVATE_KEY` | Pay-per-call key. `0x...` → x402 on Base; `base58` → x402 on Solana; `0x...` also works for MPP |
| `EVM_PRIVATE_KEY` | EVM key for x402 on Base (overrides `WALLET_PRIVATE_KEY` for EVM) |
| `SOLANA_PRIVATE_KEY` | Solana key for x402 on Solana (overrides `WALLET_PRIVATE_KEY` for Solana) |
| `TEMPO_PRIVATE_KEY` | EVM key for MPP on Tempo (overrides `WALLET_PRIVATE_KEY` for MPP) |
| `ZERION_X402` | `true` enables x402 globally (analytics only) |
| `ZERION_X402_PREFER_SOLANA` | `true` prefers Solana over Base when both keys set |
| `ZERION_MPP` | `true` enables MPP globally (analytics only) |
| `SOLANA_RPC_URL` | Custom Solana RPC endpoint |
| `ETH_RPC_URL` | Custom Ethereum RPC endpoint (used for ENS resolution) |

## Supported chains

`ethereum`, `base`, `arbitrum`, `optimism`, `polygon`, `binance-smart-chain`, `avalanche`, `gnosis`, `scroll`, `linea`, `zksync-era`, `zora`, `blast`, `monad`, `solana`.

Solana supports same-chain swaps and bidirectional bridging to/from EVM chains. Cross-format bridges (Solana ↔ EVM) require an explicit destination via `--to-wallet <name>` or `--to-address <addr>` matching the target chain's format. The exception is a mnemonic-derived source wallet that already has an account on the destination chain.

Run `zerion chains` for the live catalog with metadata.

## Output handling

All commands emit JSON to stdout (default) for agent compatibility. Errors emit JSON to stderr with a `code` field for programmatic handling.

```bash theme={null}
zerion portfolio vitalik.eth                 # JSON (default)
zerion portfolio vitalik.eth --pretty        # human-readable
zerion portfolio vitalik.eth --quiet         # minimal output
```

The CLI surfaces structured error codes for: missing or invalid API key, invalid address or ENS resolution failure, unsupported chain, empty wallets, rate limits (HTTP 429), upstream timeouts, slippage exceeded, and bridge route unavailable.

## Examples

### Quick wallet check

```bash theme={null}
zerion analyze vitalik.eth
```

### DeFi-only positions on a single chain

```bash theme={null}
zerion positions vitalik.eth --positions defi --chain ethereum
```

### Stage an autonomous trading bot

```bash theme={null}
# 1. Create wallet
zerion wallet create --name trading-bot

# 2. Tight policy (Base only, 7-day expiry, no transfers)
zerion agent create-policy --name swap-only \
  --chains base \
  --expires 7d \
  --deny-transfers

# 3. Mint a scoped agent token
zerion agent create-token --name dca-bot \
  --wallet trading-bot \
  --policy swap-only

# 4. Agent can now swap on Base autonomously
zerion swap base 100 USDC ETH
```

### Cross-chain bridge with provider choice

```bash theme={null}
# 1. See every available route
zerion bridge base USDC 5 arbitrum USDC

# 2. Pick the fastest
zerion bridge base USDC 5 arbitrum USDC --fast

# 3. Or pick the highest output
zerion bridge base USDC 5 arbitrum USDC --cheapest
```

### SIWE login for a dapp

```bash theme={null}
zerion sign-message "Sign in to dApp" --chain ethereum
```

### Pay-per-call without an API key

```bash theme={null}
export WALLET_PRIVATE_KEY="0x..."
zerion portfolio vitalik.eth --x402
```

### Compose with `jq`

```bash theme={null}
zerion portfolio vitalik.eth | jq '.totals.positions'
zerion history vitalik.eth --limit 50 | jq '.transactions[] | select(.type == "trade")'
```

## Open source

The CLI and skills are MIT-licensed and open to contribution.

* **CLI + skills:** [github.com/zeriontech/zerion-ai](https://github.com/zeriontech/zerion-ai)
* **API docs:** [developers.zerion.io](https://developers.zerion.io)
* **Get an API key:** [dashboard.zerion.io](https://dashboard.zerion.io)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.