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

# Skill + CLI

> CLI for Zerion Wallet — analyze wallets, sign, swap, and bridge on-chain with agent-managed wallets across EVM chains and Solana, all 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 the 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 -y zerion-cli init -y --browser
```

* `-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 the user's 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 (on-chain 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 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, unless the source wallet is mnemonic-derived and 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)