zerion-cli
Advanced tools
Zerion for AI agents and developers: wallet-analysis skill bundle and a JSON-first 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. Wallet management is built on the Open Wallet Standard.
[!NOTE] Alpha Preview — This CLI is under active development. Commands, flags, and output formats may change or be removed without notice between releases. Do not depend on current behavior in production workflows.
Set up everything in one command (install CLI globally, configure your API key, and add skills across all detected coding agents):
npx -y zerion-cli init -y --browser
-y runs setup non-interactively--browser opens dashboard.zerion.io so you can grab an API key and paste it backOr just install the CLI without setup:
npm install -g zerion-cli
Requires Node.js 20 or later.
One skill, zerion, under ./skills/zerion/ — follows the agentskills.io open standard. All capabilities and partner integrations live as nested files that load on demand (progressive disclosure), so a single install + single picker entry exposes everything below.
skills/zerion/capabilities/)| File | What it covers |
|---|---|
analyze.md | Portfolio, positions, history, PnL, token search, watchlist (read-only; supports x402 / MPP) |
trading.md | Swap, bridge, send tokens (on-chain actions; needs API key + agent token) |
sign.md | Off-chain signing — sign-message (EIP-191 / raw), sign-typed-data (EIP-712) |
wallet.md | Wallet management — create, import, list, fund, backup, export-key, delete, sync |
agent-management.md | Agent tokens + policies (the autonomous-trading primitives) |
swap-0x.md | Token swaps via 0x API v2 — AllowanceHolder, Permit2, and Gasless flows across 20+ EVM chains |
skills/zerion/partners/)Ecosystem partners that combine their product with the Zerion CLI. See partner-skill-creator.md to contribute one. Loaded only when the user names the partner.
| File | What it covers | Partner |
|---|---|---|
bankr.md | Twitter/X-native trading bot patterns | Bankr |
lifi-earn.md | Cross-chain yield routing | Li.Fi |
monad-addresses.md | Canonical Monad mainnet contract addresses for zerion agent create-policy --allowlist lockdown | Monad |
moonpay-onramp.md | Buy crypto with card or bank transfer via MoonPay, then trade with Zerion | MoonPay |
moonpay-iron.md | USD bank-wire to Iron virtual account (IBAN/ACH) → USDC → DCA via Zerion | MoonPay |
moonpay-predict.md | Trade prediction markets (Polymarket, Kalshi) via MoonPay CLI | MoonPay |
sendai-ideas.md | Crypto idea discovery, validation, competitive landscape, DeFi TVL research | SendAI (MIT) |
somnia-blockchain.md | Somnia L1 reference — network info, gas model, deployment guidance | Somnia |
somnia-reactivity.md | Somnia Reactivity — event-driven pub/sub, WebSocket + Solidity handlers | Somnia |
trails-crosschainswap.md | Cross-chain swaps to/from Polygon via Trails SDK (Widget / Headless / API) | Trails |
trails-deposit.md | Bridge + DeFi vault deposit on Polygon in one intent (Aave, Morpho, ERC-4626) | Trails |
umbra-privatetxn.md | Private (stealth-address) transfers | Umbra |
uniswap-lp.md | Liquidity position management | Uniswap |
uniswap-x402.md | Swap with x402 pay-per-call | Uniswap |
vaultsfyi-*.md | Deposit, market intel, rebalance, risk monitor, strategist, watchlist, yield optimizer | Vaults.fyi |
consolidate.md | Sweep all tokens on a chain into one target | Zerion |
zerion setup skills
Installs globally across all detected coding agents. Use --agent <name> to scope to one agent, or -g to force a global install.
/plugin marketplace add zeriontech/zerion-ai
/plugin install zerion-agent@zerion
codex plugin marketplace add zeriontech/zerion-ai
Then run /plugins in Codex, choose the zerion marketplace, and install zerion-agent.
gemini extensions install https://github.com/zeriontech/zerion-ai
npx skills add zeriontech/zerion-ai
Auto-detects installed agents. Flags: -g (user-wide), -a <agent> (target one host), -y (non-interactive). Full ecosystem: https://agentskills.io/clients.
After install, ask the agent in natural language.
Analyze the wallet
vitalik.eth. Summarize total portfolio value, top 5 holdings, and recent transactions.
What's the PnL on
0xFe89Cc7Abb2C4183683Ab71653c4cCd1b9cC194eover the last 30 days?
Show DeFi positions (lending, staking, LP) for my default wallet.
Swap 100 USDC to ETH on Base.
Bridge 50 USDC from Arbitrum to Optimism.
Send 0.1 ETH on Base to
vitalik.eth.
Create a new encrypted wallet called
bot-1.
Set up an agent token for
bot-1that's allowed to swap on Base only, with a 7-day expiry.
List my wallets and which agent tokens are active.
Sign the EIP-712 message in
typed.jsonusing mybot-1wallet.
The agent reaches for the zerion skill, which routes by task to the right nested file under capabilities/ or partners/. Progressive disclosure means only the matching capability doc loads — context stays clean. A "create wallet, set up agent token, then swap" flow Reads capabilities/wallet.md → capabilities/agent-management.md → capabilities/trading.md in sequence.
Zerion CLI splits into two surfaces, by design.
wallet create, import, backup, export-key, and delete all 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 has to obey — allowed chains, expiry, transfer/approval gates, contract allowlists. The sibling admin commands (agent list-tokens, use-token, revoke-token, list-policies, show-policy, delete-policy) are also gestures you make yourself. No key material moves and no spending credential widens without you in the loop. For CI and headless servers, agent create-token accepts --passphrase-file <path> (file must be mode 0600) so token issuance can be scripted without an interactive TTY — see capabilities/agent-management.md.analyze, portfolio, positions, history, pnl, sign-message, sign-typed-data, swap, bridge, send, swap tokens, search, chains, wallet list, wallet fund, and watch list emit JSON to stdout, structured errors to stderr, and skip confirmation dialogs. Once an agent token is configured, signing and trading fire immediately — the token authorizes operations on behalf of the wallet without a passphrase prompt.Setup gestures (init, setup skills, config set/unset/list, watch add/remove) are one-time configuration steps you run yourself before automation takes over.
The split is the point. 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; use agent policies to scope them down to specific chains, addresses, or expiry windows.
Three options. The CLI auto-detects which is active.
Get a key at dashboard.zerion.io — it's free and takes a minute. Keys begin with zk_.
The fastest way is browser login — like claude or gh auth login, it opens the dashboard, you approve, and the key is captured over a local loopback redirect and saved to config. The key never leaves your machine.
zerion login # pick browser login, paste a key, or pay-per-call
zerion login --browser # go straight to browser authentication
Or set / persist a key manually:
export ZERION_API_KEY="zk_..." # per-session
zerion config set apiKey zk_... # persisted to ~/.zerion/config.json
No API key needed. Pay $0.01 USDC per request via the x402 protocol. Supports EVM (Base) and Solana.
Pay-per-call applies to analytics commands only (
portfolio,positions,history,pnl,analyze). Trading commands always use an API key.
export WALLET_PRIVATE_KEY="0x..." # EVM (Base) — 0x-prefixed hex
export WALLET_PRIVATE_KEY="5C1y..." # Solana — base58 encoded keypair
zerion analyze 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --x402
# or enable globally:
export ZERION_X402=true
Both chains simultaneously:
export EVM_PRIVATE_KEY="0x..."
export SOLANA_PRIVATE_KEY="5C1y..."
export ZERION_X402_PREFER_SOLANA=true # optional, prefers Solana when both set
No API key needed. Pay $0.01 USDC per request via the MPP protocol on Tempo. EVM only.
export WALLET_PRIVATE_KEY="0x..." # EVM key with USDC on Tempo
# or use a dedicated key:
export TEMPO_PRIVATE_KEY="0x..."
zerion portfolio 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --mpp
# or enable globally:
export ZERION_MPP=true
Every command supports --help for full flag documentation. Run zerion --help for the top-level command list.
Read-only. Supports --x402 and --mpp for pay-per-call.
| Command | Description | Example |
|---|---|---|
zerion analyze <address|ens> | Full analysis — portfolio, positions, transactions, PnL in parallel | zerion analyze vitalik.eth |
zerion portfolio <address|ens> | Portfolio value and top positions | zerion portfolio 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 |
zerion positions <address|ens> | Token + DeFi positions (--positions all|simple|defi, or --defi for grouped-by-protocol view with loans netted) | zerion positions vitalik.eth --defi |
zerion history <address|ens> | Transaction history (--limit, --chain) | zerion history vitalik.eth --limit 10 --chain ethereum |
zerion pnl <address|ens> | Profit & loss (realized, unrealized, fees) | zerion pnl vitalik.eth |
zerion search <query> | Search tokens by name or symbol | zerion search USDC |
zerion chains | List supported chains | zerion chains |
Requires an API key (or agent token for unattended use).
| Command | Description | Example |
|---|---|---|
zerion swap <chain> <amount> <from-token> <to-token> | Same-chain swap | zerion swap base 1 USDC ETH |
zerion swap solana <amount> <from-token> <to-token> | Solana same-chain swap | zerion swap solana 0.1 SOL USDC |
zerion swap tokens [chain] | List tokens available for swap | zerion swap tokens solana |
zerion bridge <from-chain> <from-token> <amount> <to-chain> <to-token> | List all bridge providers (no execute, multi-offer case) | zerion bridge base USDC 5 arbitrum USDC |
zerion bridge … --cheapest | Execute highest-output bridge route | zerion bridge base USDC 5 arbitrum USDC --cheapest |
zerion bridge … --fast | Execute lowest-time bridge route | zerion bridge base USDC 5 arbitrum USDC --fast |
zerion bridge … --to-wallet <name> | Bridge with explicit destination wallet (Solana ↔ EVM) | zerion bridge ethereum USDC 5 solana USDC --to-wallet sol-bot --cheapest |
zerion bridge … --to-address <addr> | Bridge to a raw destination address | zerion bridge ethereum USDC 5 solana USDC --to-address 8xLdox… --cheapest |
zerion send <token> <amount> --to <address> [--chain <chain>] | Send tokens (chain auto-detected from address format) | zerion send usdc 50 --to 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --chain base |
zerion send SOL <amount> --to <solana-pubkey> | Send native SOL on Solana | zerion send SOL 0.1 --to 2Nsnn… |
Encrypted local wallets. EVM + Solana supported. Passphrase required for all destructive ops.
| Command | Description | Example |
|---|---|---|
zerion wallet create --name <name> | Create encrypted wallet (EVM + Solana) | zerion wallet create --name trading-bot |
zerion wallet import --name <name> --evm-key | Import from EVM private key (interactive) | zerion wallet import --name old-wallet --evm-key |
zerion wallet import --name <name> --sol-key | Import from Solana private key (interactive) | zerion wallet import --name sol-bot --sol-key |
zerion wallet import --name <name> --mnemonic | Import from seed phrase (all chains) | zerion wallet import --name backup --mnemonic |
zerion wallet list | List all wallets | zerion wallet list |
zerion wallet fund | Show deposit addresses for funding | zerion wallet fund --wallet trading-bot |
zerion wallet backup --wallet <name> | Export recovery phrase | zerion wallet backup --wallet trading-bot |
zerion wallet export-key --wallet <name> [--chain evm|solana|all] [--index N] | Export raw private key(s) derived from mnemonic — EVM (0x hex) and/or Solana (base58 Phantom format + 32-byte ed25519 seed). Output is stderr-only. | zerion wallet export-key --wallet trading-bot --chain evm |
zerion wallet delete <name> | Permanently delete a wallet (requires passphrase) | zerion wallet delete trading-bot |
zerion wallet sync --wallet <name> | Sync wallet to Zerion app via QR code | zerion wallet sync --wallet trading-bot |
zerion wallet sync --all | Sync all wallets to Zerion app | zerion wallet sync --all |
| Command | Description | Example |
|---|---|---|
zerion sign-message <message> --chain <chain> | Sign EIP-191 (EVM) or raw (Solana) message | zerion sign-message "Login to dApp" --chain ethereum |
zerion sign-message <message> --encoding hex | Treat message as hex bytes | zerion sign-message 0xdeadbeef --encoding hex --chain ethereum |
zerion sign-typed-data --data '<json>' | Sign EIP-712 typed data (EVM only) | zerion sign-typed-data --data "$(cat permit.json)" |
zerion sign-typed-data --file <path> | Read EIP-712 typed data from file | zerion sign-typed-data --file permit.json |
cat typed.json | zerion sign-typed-data | Read EIP-712 typed data from stdin | cat permit.json | zerion sign-typed-data |
Scoped API tokens for unattended trading. Token auto-saves to config; required for swap, bridge, send.
| Command | Description | Example |
|---|---|---|
zerion agent create-token --name <bot> --wallet <wallet> | Create scoped token (interactive passphrase) | zerion agent create-token --name dca-bot --wallet trading-bot |
zerion agent create-token … --passphrase-file <path> | Non-interactive: passphrase read from a chmod 600 file (CI / headless) | zerion agent create-token --name dca-bot --wallet trading-bot --policy <id> --passphrase-file /run/zerion/pass |
zerion agent list-tokens | List active agent tokens | zerion agent list-tokens |
zerion agent use-token --wallet <wallet> | Switch active token by wallet | zerion agent use-token --wallet trading-bot |
zerion agent revoke-token --name <bot> | Revoke a token | zerion agent revoke-token --name dca-bot |
Restrict what an agent token can do — chains, expiry, transfers, approvals, allowlists.
| Command | Description | Example |
|---|---|---|
zerion agent create-policy --name <policy> | Create security policy (flags below) | zerion agent create-policy --name safe-base --chains base --expires 24h --deny-transfers |
zerion agent list-policies | List all policies | zerion agent list-policies |
zerion agent show-policy <id> | Show policy details | zerion agent show-policy safe-base |
zerion agent delete-policy <id> | Delete a policy | zerion agent delete-policy safe-base |
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 |
Track wallets by name without exposing addresses in commands.
| Command | Description | Example |
|---|---|---|
zerion watch <address> --name <label> | Add wallet to watchlist | zerion watch 0xFe89Cc7Abb2C4183683Ab71653c4cCd1b9cC194e --name ens-dao |
zerion watch list | List watched wallets | zerion watch list |
zerion watch remove <name> | Remove from watchlist | zerion watch remove ens-dao |
zerion analyze <name> | Analyze a watched wallet by name | zerion analyze ens-dao |
| Command | Description | Example |
|---|---|---|
zerion login | Authenticate — browser (dashboard) login, paste an API key, or pay-per-call | zerion login |
zerion login --browser | Browser auth: opens dashboard.zerion.io, captures the key via loopback | zerion login --browser |
zerion init | One-shot onboarding — install CLI globally, authenticate, install agent skills | zerion init |
zerion init -y --browser | Non-interactive init that opens dashboard.zerion.io for the API key | npx -y zerion-cli init -y --browser |
zerion setup skills | Install Zerion agent skills into detected coding agents | zerion setup skills |
zerion setup skills --agent claude-code | Install into a specific agent | zerion setup skills --agent claude-code |
| Command | Description | Example |
|---|---|---|
zerion config set <key> <value> | Set config (apiKey, defaultWallet, defaultChain, slippage) | zerion config set defaultChain base |
zerion config unset <key> | Remove a config value (resets to default) | zerion config unset defaultChain |
zerion config list | Show current configuration | zerion config list |
| 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 bridge (Solana ↔ EVM) |
--to-address <addr> | 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 for list ops) |
--offset <n> | Skip first N results (pagination) |
--search <query> | Filter wallets by name or address |
--slippage <percent> | Slippage tolerance (default: 2%) |
--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 |
| Variable | Description |
|---|---|
ZERION_API_KEY | API key (get at 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) |
All commands emit JSON to stdout (default) for agent compatibility. Errors emit JSON to stderr with a code field for programmatic handling. Use --pretty for human-readable output, --quiet for minimal.
The CLI handles:
All errors are emitted as structured JSON on stderr with a code field.
npm install
npm test # unit tests (fast, offline)
npm run test:integration # live API tests (requires ZERION_API_KEY, runs serially to avoid rate limits)
npm run test:all # both
node ./cli/zerion.js --help
Development requires npm >=11.10 (see Supply-chain cooldown below); CI and npm publish run on Node 24.
To reduce exposure to npm supply-chain attacks, this repo enforces a release-age cooldown: npm install will only resolve dependency versions that have been published for at least a fixed number of days. Compromised "fresh" releases are usually detected and unpublished within that window.
The cooldown length is set by min-release-age in .npmrc — that line is the single source of truth for the window. It requires npm >=11.10 (older npm silently ignores it); devEngines in package.json pins npm to that range with onFail: error, so an unsupported npm hard-fails instead of quietly skipping the cooldown.
The cooldown only affects version resolution (i.e. updating package-lock.json); a plain install from the existing lockfile — including npm ci in CI — is unaffected.
Overriding for an urgent fix. If you need a security patch newer than the window, bypass it for a single install and commit the result:
npm install <package>@<version> --min-release-age=0
Then commit the updated package-lock.json with a note explaining why.
This repo uses release-please for automated versioning and publishing.
Commit conventions — use Conventional Commits prefixes:
feat: — new feature → minor version bumpfix: — bug fix → patch version bumpfeat!: or fix!: — breaking change → major version bumpdocs:, chore:, test: — no release triggeredRelease flow:
feat: or fix: commits to mainchore(main): release X.Y.Z) with version bump and CHANGELOGnpm publishTo force a specific version, add Release-As: 2.0.0 in a commit message body.
CI setup:
NPM_TOKEN repo secret is required for npm publish (use a granular access token).release-please-manifest.json tracks the current version.github/workflows/release-please.yml handles release PR creation and npm publish.github/workflows/test.yml runs tests on PRs and pushes to main.github/workflows/publish-next.yml publishes prereleases to the next dist-tag (see below)@next)Every push to main (except release commits) publishes a prerelease to npm under the next dist-tag, e.g. 1.5.1-next.20260714093000.g325093a. Regular users are unaffected: npm install zerion-cli keeps resolving the latest tag, which only moves when a release-please release PR is merged.
To try the latest merged-but-unreleased work:
npx zerion-cli@next --help
# or
npm install -g zerion-cli@next
To test an unmerged branch, install straight from git — no publish needed:
npm install -g github:zeriontech/zerion-ai#<branch>
A prerelease can also be published from any branch manually via the Publish next workflow in the Actions tab (workflow_dispatch).
If a next build turns out broken, point the tag back at a known-good version:
npm dist-tag add zerion-cli@<version> next
./skills/ (also installable via npx skills add zeriontech/zerion-ai)MIT — see LICENSE.
FAQs
Zerion for AI agents and developers: wallet-analysis skill bundle and a JSON-first CLI.
The npm package zerion-cli receives a total of 335 weekly downloads. As such, zerion-cli popularity was classified as not popular.
We found that zerion-cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Benign-looking npm packages split malicious functionality across a dependency chain that deploys a cross-platform RAT targeting Alibaba developers.
Research
/Security News
Two Joyfill npm beta releases contain an import-time implant that uses blockchain transactions to retrieve a remote-access trojan.
Security News
Socket releases free Certified Patches for high-severity Nuxt vulnerabilities, including server-side remote code execution through server island props.