Skip to content

wallet.md

Latest commit

 

History

History
130 lines (92 loc) · 5.27 KB

wallet.md

File metadata and controls

130 lines (92 loc) · 5.27 KB
Raw

Zerion — Wallet Management

Encrypted local wallets stored in the Open Wallet Standard (OWS) vault at ~/.ows/, AES-256-GCM. Keys never leave the device.

Setup

If a zerion command fails with command not found, install once:

npm install -g zerion-cli

Requires Node.js ≥ 20. For auth see the parent SKILL.md (Setup + Authentication).

When to use

  • "Create a new wallet"
  • "Import my wallet from a private key / mnemonic"
  • "Show my wallets" / "list deposit addresses"
  • "Back up my recovery phrase"
  • "Export the raw private key" / "give me the 0x hex key" / "give me the Phantom-format secret"
  • "Delete this wallet"
  • "Sync my wallet to the Zerion mobile app"

For on-chain actions with a wallet → capabilities/trading.md. For agent-token setup on a wallet → capabilities/agent-management.md.

Wallets and chains

A mnemonic-derived wallet (created via wallet create or wallet import --mnemonic) holds both an EVM and a Solana account, so the same wallet can sign on either chain and act as a destination for cross-chain bridges in either direction.

A wallet imported from a single private key holds only one chain's account:

Import flag Account type Can swap on Can be cross-chain destination for
--mnemonic EVM + Solana both both
--evm-key EVM only EVM chains EVM chains
--sol-key Solana only Solana Solana

wallet list shows which accounts each wallet has. Use this when picking --to-wallet for a cross-chain bridge — the destination wallet must have an account on the target chain.

Agent vs manual operations

Operation Type Notes
wallet list, wallet fund Agent Read-only. Safe to invoke autonomously.
wallet create, wallet import, wallet backup, wallet export-key, wallet delete, wallet sync Manual Require passphrase or interactive input. Humans must run these directly — agents must not call them.

Read-only — agents may invoke freely

zerion wallet list                        # All wallets, addresses, active policies
zerion wallet list --search <query>       # Filter by name or address
zerion wallet list --limit <n> --offset <n>   # Paginate
zerion wallet fund --wallet <name>        # Show EVM + Solana deposit addresses

Manual — humans only

These prompt for a passphrase, secret key, or confirmation. Do not invoke from an agent loop.

# Create a fresh encrypted wallet (EVM + Solana, generated locally)
zerion wallet create --name <name>

# Import from existing keys (interactive secret prompts — never expose keys in shell history)
zerion wallet import --name <name> --evm-key
zerion wallet import --name <name> --sol-key
zerion wallet import --name <name> --mnemonic

# Export the recovery phrase (passphrase required)
zerion wallet backup --wallet <name>

# Export raw private key(s) derived from the mnemonic (passphrase required)
# Output goes to stderr only — same safety stance as `wallet backup`.
zerion wallet export-key --wallet <name>                       # both chains, derivation index 0
zerion wallet export-key --wallet <name> --chain evm           # EVM only — m/44'/60'/0'/0/0, 0x hex
zerion wallet export-key --wallet <name> --chain solana        # Solana only — m/44'/501'/0'/0', base58 (Phantom format) + 32-byte ed25519 seed
zerion wallet export-key --wallet <name> --chain evm --index 1 # different derivation index

# Permanently delete (passphrase + confirmation)
zerion wallet delete <name>

# Sync to the Zerion mobile app via a one-time QR code
zerion wallet sync --wallet <name>
zerion wallet sync --all

Setting defaults

Wallet-related config is set with zerion config:

zerion config set defaultWallet <name>    # Used when --wallet is omitted
zerion config get defaultWallet
zerion config unset defaultWallet         # Resets to "no default"
zerion config list                        # Show all config (sensitive values redacted)

~/.zerion/config.json is created with mode 0o600.

Typical setup flow (human runs these in order)

# 1. Create wallet (passphrase prompt; offers agent-token setup at the end)
zerion wallet create --name agent-bot

# 2. Fund it
zerion wallet fund --wallet agent-bot
# → prints EVM and Solana deposit addresses

# 3. Set as default so future commands omit --wallet
zerion config set defaultWallet agent-bot

# 4. (Optional) sync to mobile
zerion wallet sync --wallet agent-bot

After step 1's agent-token prompt, the wallet is ready for autonomous trading via capabilities/trading.md. To configure agent tokens or policies later → capabilities/agent-management.md.

Common errors

Code Cause Fix
wallet_exists Wallet name already taken Choose a different name or wallet delete first
wallet_not_found Name not in OWS vault zerion wallet list to see existing
bad_passphrase Wrong passphrase entered Retry; passphrase is set at creation
bad_mnemonic Invalid recovery phrase format Re-enter; must be valid BIP-39
bad_evm_key Invalid 0x-prefixed hex Should be 64 hex chars after 0x
bad_sol_key Invalid base58 keypair Solana keys are base58, ≥87 chars