solana/docs/src/hardware-wallets

Hardware Wallets

Signing a transaction requires a private key, but storing a private key on your personal computer or phone leaves it subject to theft. Adding a password to your key adds security, but many people prefer to take it a step further and move their private keys to a separate physical device called a hardware wallet. A hardware wallet is a small handheld device that stores private keys and provides some interface for signing transactions.

The Solana CLI has first class support for hardware wallets. Anywhere you use a keypair filepath (denoted as <KEYPAIR> in usage docs), you can pass a keypair URL that uniquely identifies a keypair in a hardware wallet.

Supported Hardware Wallets

The Solana CLI supports the following hardware wallets:

• Ledger Nano S

Specify a Hardware Wallet Key

Solana defines a keypair URL format to uniquely locate any Solana keypair on a hardware wallet connected to your computer.

The keypair URL has the following form, where square brackets denote optional fields:

usb://<MANUFACTURER>[/<WALLET_ID>][?key=<DERIVATION_PATH>]

WALLET_ID is a globally unique key used to disambiguate multiple devices.

DERVIATION_PATH is used to navigate to Solana keys within your hardware wallet. The path has the form <ACCOUNT>[/<CHANGE>], where each ACCOUNT and CHANGE are positive integers.

All derivation paths implicitly include the prefix 44'/501', which indicates the path follows the BIP44 specifications and that any derived keys are Solana keys (Coin type 501). The single quote indicates a "hardened" derivation. Because Solana uses Ed25519 keypairs, all derivations are hardened and therefore adding the quote is optional and unnecessary.

For example, a fully qualified URL for a Ledger device might be:

usb://ledger/BsNsvfXqQTtJnagwFWdBS7FBXgnsK8VZ5CmuznN85swK?key=0/0

Multiple Addresses on a Single Hardware Wallet

You can derive as many wallet addresses as you like. To view them, simply iterate the ACCOUNT and/or CHANGE number when specifying the URL path. Multiple wallet addresses can be useful if you want to transfer tokens between your own accounts for different purposes.

For example, a first address can be viewed with:

solana-keygen pubkey usb://ledger?key=0

A second address can be viewed with:

solana-keygen pubkey usb://ledger?key=1

A third address:

solana-keygen pubkey usb://ledger?key=2

...and so on.

Manage Multiple Hardware Wallets

It is sometimes useful to sign a transaction with keys from multiple hardware wallets. Signing with multiple wallets requires fully qualified keypair URLs. When the URL is not fully qualified, the Solana CLI will prompt you with the fully qualified URLs of all connected hardware wallets, and ask you to choose which wallet to use for each signature.

Instead of using the interactive prompts, you can generate fully qualified URLs using the Solana CLI resolve-signer command. For example, try connecting a Ledger Nano-S to USB, unlock it with your pin, and running the following command:

solana resolve-signer usb://ledger?key=0/0

You will see output similar to:

usb://ledger/BsNsvfXqQTtJnagwFWdBS7FBXgnsK8VZ5CmuznN85swK?key=0/0

but where BsNsvfXqQTtJnagwFWdBS7FBXgnsK8VZ5CmuznN85swK is your WALLET_ID.

With your fully qualified URL, you can connect multiple hardware wallets to the same computer and uniquely identify a keypair from any of them.

Troubleshooting

Keypair URL parameters are ignored in zsh

The question mark character is a special character in zsh. If that's not a feature you use, add the following line to your ~/.zshrc to treat it as a normal character:

unsetopt nomatch

Then either restart your shell window or run ~/.zshrc:

source ~/.zshrc

If you would prefer not to disable zsh's special handling of the question mark character, you can disable it explictly with a backslash in your keypair URLs. For example:

solana-keygen pubkey usb://ledger\?key=0