Bitcoin Core Wallet Management Guide

Descriptor vs Legacy Wallets

Bitcoin Core v23+ creates descriptor wallets by default. Descriptor wallets use output descriptors — a language for describing which scripts and keys the wallet tracks. This is more flexible and explicit than the old legacy wallet format.

Legacy wallets implicitly derive keys from a single HD seed and support older import mechanisms like importprivkey and importaddress. Descriptor wallets use importdescriptors instead, which provides more precise control over what's imported.

For new projects, always use descriptor wallets. Legacy wallets exist for backward compatibility and will eventually be removed from Bitcoin Core.

Creating and Loading Wallets

Create a new wallet with createwallet. Key options include:

wallet_name — the wallet identifier, used to direct RPC calls to the right wallet. disable_private_keys — creates a watch-only wallet, useful for monitoring addresses without the ability to spend. blank — creates an empty wallet with no keys, for manual key management. passphrase — immediately encrypts the wallet on creation. descriptors — set to true (default) for a descriptor wallet.

Bitcoin Core supports multiple wallets simultaneously. Use loadwallet and unloadwallet to manage which wallets are active. When multiple wallets are loaded, specify the target wallet in your RPC calls using the /wallet/walletname endpoint.

listwallets shows all currently loaded wallets, and getwalletinfo gives detailed state for the active wallet.

Backup and Recovery

Always maintain current backups. The backupwallet command creates a safe copy of the wallet file while the node is running. For descriptor wallets, you should also export your descriptors using listdescriptors with private=true — this gives you the master keys in a portable format.

Restore from backup using restorewallet, which loads a backup file and creates a new wallet from it. After restoration, the wallet automatically rescans the blockchain to find your transactions.

For descriptor wallets, you can also recreate a wallet on a fresh node by creating a blank wallet and importing your descriptors with importdescriptors. This is often faster and more flexible than file-based backup.

Wallet Encryption

The encryptwallet command encrypts the wallet's private keys with a passphrase. After encryption, operations that require private keys (sending transactions, signing messages, dumping keys) require you to first unlock the wallet with walletpassphrase.

walletpassphrase takes a timeout parameter — the wallet automatically locks again after this many seconds. Keep unlock durations as short as possible.

Change the passphrase with walletpassphrasechange. Lock the wallet immediately (without waiting for the timeout) using walletlock.

Encryption is one-way — you cannot unencrypt a wallet. If you lose the passphrase, you lose access to the funds. Always test your passphrase immediately after encryption.

Multi-Wallet Architecture

Production Bitcoin applications often use multiple wallets for separation of concerns:

A hot wallet with a small balance for immediate payments. A cold or watch-only wallet for monitoring large holdings. A dedicated change wallet to prevent change outputs from contaminating your main wallet's UTXO set.

Bitcoin Core handles this natively — load multiple wallets and direct RPC calls to the appropriate one. Each wallet has its own keypool, labels, and transaction history.

For automated systems, consider a watch-only wallet for receiving and monitoring, combined with an air-gapped signing wallet using the PSBT workflow. This gives you real-time visibility into incoming payments without exposing signing keys to the network.