moonpay-hardware-wallet

Hardware wallet support

Goal

Connect a hardware wallet to the MoonPay CLI. Private keys never leave the device — the CLI stores only cached addresses. All existing commands (swap, transfer, bridge, buy, balance) work transparently with hardware wallets.

First supported device: Ledger (Nano S, Nano X, Nano S Plus, Stax, Flex).

Prerequisites

• Ledger device connected via USB
• Ledger Live installed (for firmware updates)
• Ethereum and/or Solana apps installed on the device

Commands

Add a hardware wallet

# Auto-detect connected device
mp wallet hardware add --name "my-ledger"

# Specify device type explicitly
mp wallet hardware add --name "my-ledger" --device ledger

This connects to the device, derives addresses for all supported chains (Ethereum, Solana), and saves the wallet. No secrets are stored — only addresses.

Refresh addresses

mp wallet hardware refresh --wallet "my-ledger"

Re-derives addresses from the connected device. Use this if you changed the account index in Ledger Live or need to update cached addresses.

List wallets

mp wallet list

Hardware wallets appear alongside software wallets with a [hardware/ledger] tag.

Using hardware wallets

Once added, use --wallet like any other wallet. The CLI automatically connects to the device for signing.

Check balances (no device needed)

mp token balance list --wallet my-ledger --chain ethereum
mp token balance list --wallet my-ledger --chain solana

Swap tokens (signs on device)

mp token swap \
  --wallet my-ledger --chain ethereum \
  --from-token 0x0000000000000000000000000000000000000000 \
  --from-amount 0.01 \
  --to-token 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48

The CLI prompts you to review and confirm the transaction on your Ledger.

Transfer tokens (signs on device)

mp token transfer \
  --wallet my-ledger --chain ethereum \
  --token 0x0000000000000000000000000000000000000000 \
  --amount 0.01 \
  --to 0x1234...

Bridge cross-chain (signs on device)

mp token bridge \
  --from-wallet my-ledger --from-chain ethereum \
  --from-token 0x0000000000000000000000000000000000000000 \
  --from-amount 0.01 \
  --to-chain polygon \
  --to-token 0x0000000000000000000000000000000000000000

How it works

1. wallet hardware add connects via USB, switches Ledger apps automatically, and derives addresses
2. Addresses are cached in the encrypted vault — read-only commands work without the device
3. For signing commands, the CLI connects to the device, opens the correct app, and prompts for on-device approval
4. The device signs the transaction — the private key never leaves the hardware
5. The CLI broadcasts the signed transaction

Supported chains

• Ethereum (+ all EVM: Base, Polygon, Arbitrum, Optimism, BNB, Avalanche)
• Solana
• Bitcoin and Tron are not supported via Ledger

Tips

• The device must be unlocked and on the home screen when connecting
• App switching is automatic — no need to manually open Ethereum or Solana apps
• If signing times out, check the Ledger screen for a pending approval prompt
• wallet export is not available for hardware wallets (there are no secrets to export)

Related skills

• moonpay-auth — Set up the CLI and manage software wallets
• moonpay-swap-tokens — Swap or bridge tokens
• moonpay-check-wallet — Check wallet balances