Ledger Wallet CLI

wallet-cli

USB-based CLI for Ledger wallet flows. Networks: bitcoin, ethereum, solana (mainnet + testnets).

Run from repo root: pnpm --silent wallet-cli start <command> [flags]

Concepts & rationale: for why a command behaves the way it does, or to surface a safety rule that this skill states tersely (genuine check, receive-address verification, sessions, sandbox, device contention), read references/business-logic.md.

Session first: When invoked without a specific task, immediately run session view — do not ask the user what to do first. Show the result, then ask what to do next. If labels exist, skip account discover.

Sandbox: account discover, receive, send, genuine-check, swap execute, ring encrypt, ring decrypt, ring keys, ring destroy must use dangerouslyDisableSandbox: true — the first group is blocked by USB restrictions; the ring commands are blocked by OS keychain access restrictions.

Device contention: Never run two device commands in parallel — they fail with [object Object] or garbled APDU. Run sequentially.

Device readiness: Before running a device command, briefly describe what you're about to do. The CLI prompts for device interaction itself — don't time out or kill the command. Exception: genuine-check exits immediately ([✖] Wrong app. Open Ledger dashboard., exit code 4) if any currency app is open — unlike the other device commands, it targets the dashboard and has no auto-launch path. Ensure the device is on the dashboard before running; if it exits, ask the user to back out to the dashboard and re-run.

Ambiguous requests — ask, don't guess. If a required parameter is missing or unclear (no recipient for send, no network for account discover, an amount with no ticker), stop and ask. A wrong guess on a hardware wallet flow can mean irreversible fund loss.

Intent map

Map informal phrasings to commands. Account references use a session label (e.g. ethereum-1).

Out of scope — say no, don't improvise

If the user asks for any of the following, surface that wallet-cli does not support it yet rather than constructing a command:

• NFTs (mint, transfer, view).
• OpenPGP-compatible output or key-share / multi-recipient encryption (the ring commands encrypt with a per-user Ledger Key Ring, not a sharable key).
• send, receive, operations, or swap execute on testnets and layer 2s (e.g. Base).
• Custom chains not listed in the Networks line above.

Session & labels

account discover persists accounts. Each gets a label: <network>[-derivation][-env]-<n> (e.g. ethereum-1, bitcoin-native-1, ethereum-sepolia-1).

All --account flags accept a session label (e.g. ethereum-1). Run account discover first to populate the session.

Commands

*send, earn deposit, and earn withdraw with --dry-run need no device and no sandbox bypass.

†TTY: whether the command requires an interactive terminal for user input.

‡ring init requires a password to protect the ring. WALLET_PASS must already be provided in the environment by the developer/user before the command runs — the agent never sets or injects it (see Non-TTY password injection).

‡‡ring destroy prompts for typed confirmation ("destroy"). Pipe it in non-interactive shells: echo "destroy" | wallet-cli ring destroy. If a password was set, WALLET_PASS must already be present in the environment (provided by the developer, not the agent).

session view / reset

pnpm --silent wallet-cli start session view
pnpm --silent wallet-cli start session reset

account discover

pnpm --silent wallet-cli start account discover ethereum
pnpm --silent wallet-cli start account discover bitcoin
pnpm --silent wallet-cli start account discover ethereum:sepolia

Networks: bitcoin (mainnet), ethereum, solana, ethereum:sepolia, bitcoin:testnet, solana:devnet.

receive

pnpm --silent wallet-cli start receive ethereum-1
pnpm --silent wallet-cli start receive ethereum-1 --no-verify  # skip device confirmation

If the on-screen address differs from the terminal address: do not share or use the address. Have the user disconnect the device and run genuine-check before retrying. See references/business-logic.md § Receive-address verification for context.

genuine-check

pnpm --silent wallet-cli start genuine-check
pnpm --silent wallet-cli start genuine-check --output json  # only if a downstream caller needs to parse the result

Preconditions: device unlocked and on the dashboard (exit any open app); host has internet access (the secure channel reaches Ledger's backend — offline runs fail).

balances

pnpm --silent wallet-cli start balances ethereum-1
pnpm --silent wallet-cli start balances ethereum-1 --output json

operations

pnpm --silent wallet-cli start operations ethereum-1
pnpm --silent wallet-cli start operations ethereum-1 --limit 20 --cursor <cursor>

Pagination: next cursor on stderr (human) or nextCursor in JSON.

send

pnpm --silent wallet-cli start send ethereum-1 --to 0xDEF... --amount '0.5 ETH'
pnpm --silent wallet-cli start send ethereum-1 --to 0xDEF... --amount '100 USDT'  # ERC-20
pnpm --silent wallet-cli start send bitcoin-native-1 --to bc1q... --amount '0.001 BTC' --fee-per-byte 15 --rbf
pnpm --silent wallet-cli start send ethereum-1 --to 0xDEF... --amount '0.5 ETH' --dry-run

Ticker is mandatory in --amount. No --token flag — ticker drives asset resolution.

Bitcoin flags: --fee-per-byte <sats>, --rbf

Solana flags: --mode send|stake.createAccount|stake.delegate|stake.undelegate|stake.withdraw, --validator <addr>, --stake-account <addr>, --memo <text>

EVM flags: --data <hex> — raw calldata for contract calls (0x-prefixed hex, even digit count). Use for contract interactions the CLI has no dedicated command for (e.g. WETH wrap/unwrap below). Omit for plain native/token transfers.

Contract calls with --data (wrap/unwrap example)

Canonical pattern: WETH wrap/unwrap. deposit() (wrap ETH → WETH, no args) is selector 0xd0e30db0, sent with --amount as the ETH value. withdraw(uint256) (unwrap WETH → ETH, one uint256 arg = amount in wei) is selector 0x2e1a7d4d followed by the amount left-padded to 32 bytes.

# wrap 0.5 ETH into WETH
pnpm --silent wallet-cli start send ethereum-1 --to <WETH_CONTRACT_ADDRESS> --amount '0.5 ETH' --data 0xd0e30db0

# unwrap 0.5 WETH back to ETH (0.5 ETH = 500000000000000000 wei = 6f05b59d3b20000 hex, padded to 32 bytes)
pnpm --silent wallet-cli start send ethereum-1 --to <WETH_CONTRACT_ADDRESS> --amount '0 ETH' --data 0x2e1a7d4d00000000000000000000000000000000000000000000000006f05b59d3b20000

Always run with --dry-run first to validate calldata before signing. The CLI cannot verify the semantic correctness of hand-supplied --data — the device screen is the last line of defense, so review the decoded call on-device before approving.

swap quote

Fetches quotes in parallel from the built-in provider list (no device required; addresses are resolved from session accounts).

Currencies: --from / -f and --to / -t are Ledger currency IDs — native assets (e.g. ethereum, bitcoin, solana) or token IDs when the token’s parent chain is a supported native swap currency (same IDs the CLI allows for swap). They are not session account labels — use --from-account / --to-account for accounts.

Default providers queried by swap quote and usable by swap execute: changelly, changelly_v2, cic, cic_v2, exodus, lifi, nearintents, okx, oneinch, swapsxyz, uniswap, velora. Some are CEX/aggregators run through the legacy Exchange-app pipeline; the DEX providers (uniswap, oneinch, velora, okx) execute in the partner's embedded coin app — see swap execute — DEX providers.

Accounts: --from-account and --to-account accept a session label only; the CLI resolves a fresh receive address from the account like receive.

pnpm --silent wallet-cli start swap quote --from ethereum --to bitcoin --amount 0.1 --from-account ethereum-1 --to-account bitcoin-native-1
pnpm --silent wallet-cli start swap quote -f ethereum -t bitcoin --amount 0.1 --from-account ethereum-1 --to-account bitcoin-native-1 --output json

Required: --from, --to, --from-account, --to-account, --amount.

swap execute

Currencies: --from / -f and --to / -t are Ledger currency IDs (same as swap quote): native assets or tokens on an allowed parent chain. They must match the asset of the source --account and of --to-account respectively.

Providers: Valid --provider values are changelly, changelly_v2, cic, cic_v2, exodus, lifi, nearintents, okx, oneinch, swapsxyz, uniswap, velora. Aliases: changelly → changelly_v2, 1inch → oneinch. Use the provider id shown on the quote line you pick from swap quote.

DEX providers (uniswap, oneinch, velora, okx): these run end-to-end in the partner's embedded coin app on the device (via the Device Intent Executor), not the legacy Exchange app. The flow re-fetches a quote for the chosen provider, then drives an on-device approval + swap sequence (sign-approval / sign-permit2 / sign-swap / broadcast), switching device apps as needed — confirm each Open <app> and signing prompt on the device.

• EVM only. DEX execution requires an EVM source account (e.g. ethereum); a non-EVM --account falls through to the legacy pipeline.
• RFQ quotes are not supported in the CLI. If the picked quote resolves to an RFQ plan (rfq-order / approval-then-rfq-order), the embedded flow is skipped and execution falls back to the legacy Exchange-app pipeline (you'll see a falling back to legacy Exchange-app pipeline progress line).

All other providers (changelly, cic, exodus, nearintents, swapsxyz, lifi, …) run the legacy Exchange-app pipeline (nonce → payload → complete exchange → sign/broadcast).

Fee strategy: --fee-strategy accepts slow, medium (default), or fast. On the legacy pipeline it sets the refund-chain transaction fee.

pnpm --silent wallet-cli start swap execute --from ethereum --to bitcoin --account ethereum-1 --to-account bitcoin-native-1 --provider changelly --amount 0.1
pnpm --silent wallet-cli start swap execute -f ethereum -t bitcoin --account ethereum-1 --to-account bitcoin-native-1 --provider changelly --amount 0.1 --fee-strategy fast
pnpm --silent wallet-cli start swap execute --from ethereum --to bitcoin --account ethereum-1 --to-account bitcoin-native-1 --provider changelly --amount 0.1 --output json
# DEX (embedded coin app): EVM-only, source and destination on an EVM chain
pnpm --silent wallet-cli start swap execute --from ethereum --to ethereum/erc20/usd_tether__erc20_ --account ethereum-1 --to-account ethereum-1 --provider uniswap --amount 0.1

Required flags: --from, --to, --account, --to-account, --provider, --amount. Use a --provider value that matches the provider id on the quote line you pick from swap quote.

swap status

pnpm --silent wallet-cli start swap status --swap-id <swapId> --provider changelly
pnpm --silent wallet-cli start swap status --swap-id <swapId> --provider changelly --output json

Required flags: --swap-id, --provider

assets token / token-by-id

Resolve token metadata from the cryptoassets store. No device, no session.

pnpm --silent wallet-cli start assets token ethereum 0xdac17f958d2ee523a2206206994597c13d831ec7
pnpm --silent wallet-cli start assets token-by-id ethereum/erc20/usd_tether__erc20_

Use token when you have the contract address; use token-by-id when you have the id. Exits non-zero if not found.

For non-EVM chains pass --identifier.

The id printed here is the same id accepted by swap quote --from / --to and swap execute --from / --to.

ring — Ledger Key Ring (LKRP)

Trustless, hardware-rooted encryption for files and text. The key ring is provisioned once on your Ledger via the Ledger Sync app; afterwards encrypt/decrypt run without the device — keys derive deterministically via HKDF-SHA256 from the LKRP-shared root and never leave AES-256-GCM. encrypt/decrypt still call the LKRP backend to restore the trustchain on each invocation, so network access is required. The ring is recoverable from your seed on any new machine.

# One-time provisioning (device required). Password comes from WALLET_PASS in the environment (see below); name the machine with --name.
pnpm --silent wallet-cli start ring init
pnpm --silent wallet-cli start ring init --name my-laptop

# File round-trip (no device after init):
pnpm --silent wallet-cli start ring encrypt --key my-oss-project -i .publish-tokens -o .publish-tokens.enc
pnpm --silent wallet-cli start ring decrypt --key my-oss-project -i .publish-tokens.enc -o .publish-tokens

# Text via stdin/stdout (clipboard pattern):
pbpaste | pnpm --silent wallet-cli start ring encrypt --key personal-notes | pbcopy
pbpaste | pnpm --silent wallet-cli start ring decrypt --key personal-notes | pbcopy

# List the keys this machine has used; tear down the ring:
pnpm --silent wallet-cli start ring keys
pnpm --silent wallet-cli start ring destroy

Always provision with a password. The ring must be protected by a password. The user provides it via WALLET_PASS in the environment before running ring init (see Non-TTY password injection) — the agent never provisions a ring without one.

Decrypted output is sensitive. ring decrypt emits secrets — never print them to the terminal, cat a decrypted file, or otherwise surface the decrypted contents, since they land in the agent transcript, logs, and scrollback. Pipe decrypt straight to its destination (a file via -o, another process, or the clipboard as shown above) or capture it into an env var; avoid --output/logging sinks that could echo it back.

--key <name> derives a per-name AES-256-GCM key; matching name at decrypt time is mandatory. Names are free-form (max 253 chars, no whitespace) — common patterns: project slugs (my-oss-project), env tags (openClaw-prod), notebooks (personal-notes).

Non-TTY (CI / agentic) password injection: the ring commands read the password from the WALLET_PASS env var when there is no TTY. The password itself must be provisioned by the developer/user (exported in the environment or stored in the OS keychain) — the agent never chooses, types, or otherwise handles the secret value; it only references what the user has already provisioned.

• Never write the password literally into a command (e.g. WALLET_PASS=hunter2 wallet-cli …, or via a flag). A literal leaks into shell history, ps output, CI logs, and — when an agent runs the command — the agent transcript. This applies to throwaway/test passwords too: make it a habit, because the same command shape is reused with a real secret.
• Always inject via command substitution so the secret never appears in the command text you type:
  • macOS : WALLET_PASS=$(security find-generic-password -a default -s ledger-wallet-cli -w) wallet-cli ring encrypt …
  • Linux : WALLET_PASS=$(secret-tool lookup service ledger-wallet-cli account default) wallet-cli ring encrypt …
• Agents must not handle the secret at all. Ask the user to store the password once in their OS keychain, then reference only the $(…) substitution. If a test or ring init needs a password, store a throwaway value in the keychain first (security add-generic-password -a default -s ledger-wallet-cli -w) and inject it the same way — never type the literal into a tool call.
• Even via substitution the value lives in the child process environment (readable via ps eww by the same user) — acceptable, but prefer the keychain form and avoid --output json sinks or logs that could echo it back.

Rotation limitation: the domain key derives from the ring's wallet-sync encryption key, which the LKRP protocol rotates when a ring member is removed. After a rotation, data encrypted before it can no longer be decrypted (decrypt fails with a "wrong key name, corrupted data, or the Ledger Key Ring rotated" error, and the CLI prints a ⚠ Ledger Key Ring rotated warning). Re-encrypt the affected data under the new ring after a member is removed. ring destroy aborts (no changes) if you enter a wrong password, and also if WALLET_PASS is set but empty (a failed keychain lookup) — this is treated as a mistake, not a skip, so it never orphans the remote ring. To intentionally skip the remote teardown and wipe only local credentials, press Enter at the interactive password prompt.

earn (staking & DeFi yield)

Earn covers two flows: Ethereum ERC-4626 DeFi vaults (deposit/redeem) and Solana native staking (delegate/undelegate). yields and positions are read-only (no device); deposit and withdraw sign on the device.

Only ethereum & solana support deposit/withdraw. Other networks appear in earn yields (informational) but cannot be deposited to via the CLI.

earn yields

Lists yield opportunities (no device). Without --network it prints every network's headline rate. With -n ethereum or -n solana it also prints the concrete deposit targets, each ending with the exact → --product <id> value to pass to earn deposit:

• ethereum → ERC-4626 vault ids (e.g. 1_0x7daeba3f217614e409f85d3014d33923a6b03630).
• solana → validator vote accounts. The CLI surfaces the Ledger-operated validators ("Ledger by Figment", "Ledger by Bitwise") as the recommended targets; any other valid vote account also works as --product.

pnpm --silent wallet-cli start earn yields
pnpm --silent wallet-cli start earn yields -n solana
pnpm --silent wallet-cli start earn yields -n ethereum --output json

There is no separate "list validators / vaults" command — earn yields -n <network> is how you discover a valid --product. In JSON, the value is the vaultId (ETH) or validator (SOL) field on each row.

earn positions

Lists active earn positions for an account (no device). Account-based networks only (solana, ethereum).

pnpm --silent wallet-cli start earn positions solana-1
pnpm --silent wallet-cli start earn positions solana-1 --fresh   # request a background refresh

--fresh flags stale rows for an async backend refresh; the refreshed data shows up on a re-run, not in the same response. Watch for the (stale) marker.

Solana stake accounts: for Solana accounts the command also reads on-chain stake accounts and prints each one's → --stake-account <address>, its state (active / inactive / activating / deactivating), balance, and validator. This is where you get the --stake-account value for earn withdraw. In JSON they're a top-level stakes[] array alongside positions (each entry: stakeAccount, validator, state, stakeBalance, withdrawable); the stakes key is omitted entirely when there are none. Stake accounts show up here right after a deposit even if the backend snapshot is still empty. (Requires a chain sync; if it can't be reached the backend snapshot still prints, with a warning.)

earn deposit

Stakes (Solana) or deposits into a vault (Ethereum). Touches the device to sign — bypass the sandbox. --product comes from earn yields -n <network> (see above). --amount requires a ticker.

# Solana: --product is a validator vote account
pnpm --silent wallet-cli start earn deposit solana-1 --product 26pV97Ce83ZQ6Kz9XT4td8tdoUFPTng8Fb8gPyc53dJx --amount '1.5 SOL'
# Ethereum: --product is a vault id
pnpm --silent wallet-cli start earn deposit ethereum-1 --product 1_0x7daeba3f217614e409f85d3014d33923a6b03630 --amount '100 USDC'
# Validate without signing (no device, no sandbox bypass)
pnpm --silent wallet-cli start earn deposit solana-1 --product 26pV97… --amount '1.5 SOL' --dry-run

Solana stake.createAccount creates and delegates the stake account in one transaction. Ethereum deposits may run two transactions (ERC-20 approve then deposit).

First-time ETH vault deposit — dry-run can't validate the deposit leg. A first deposit into a vault you've never used is approve → deposit, and the deposit can only be built once a non-zero allowance exists on-chain. In --dry-run nothing is broadcast, so when an approve is still required the CLI validates the approve and skips the deposit build (status not-simulated …, overall dry-run: approve validated; deposit needs an on-chain allowance to simulate) rather than surfacing the backend's opaque 500. This is expected — not a balance error. The only way to validate the deposit leg is the real run (broadcast approve, wait for confirmation, then deposit). Treat a clean dry-run here as "approve is fine"; confirm with the user before the live run since it's an irreversible on-device signature. Once the allowance exists, a re-run of --dry-run will simulate the deposit normally.

earn withdraw

Unstakes (Solana) or redeems from a vault (Ethereum). Touches the device — bypass the sandbox.

• Ethereum: --product <vault-id> required; --amount optional. The amount is in the vault's asset units (e.g. '50 USDC'); if a ticker is given it must match the vault asset. Omit --amount for a full exit: the CLI sends amount:"max" and the backend redeems the entire share balance, leaving no dust (don't compute the asset amount yourself for a full exit — the share→asset rate drifts).
• Solana: --stake-account <address> (required). Two-phase: run once to undelegate (deactivate), wait for the deactivation epoch boundary (~2–3 days), then re-run with --finalize to withdraw the now-inactive lamports back to the main account. coin-solana computes the withdrawable amount on-chain, so --amount is ignored on finalize.

# Ethereum vault redeem
pnpm --silent wallet-cli start earn withdraw ethereum-1 --product 1_0x7daeba3f… --amount '50 USDC'
# Solana phase 1: deactivate
pnpm --silent wallet-cli start earn withdraw solana-1 --stake-account <stakeAccountAddr>
# Solana phase 2 (after ~2–3 days): withdraw
pnpm --silent wallet-cli start earn withdraw solana-1 --stake-account <stakeAccountAddr> --finalize

Get the Solana --stake-account address from earn positions <account> (its stakes[] / → --stake-account lines) — that's the stake account created by your earlier earn deposit.

Common errors