Bitcoin Core encryptwallet RPC: First-Time Encryption Guide

This guide explains Bitcoin Core encryptwallet RPC in plain English. It shows what the command does, what its result means and what it cannot prove.

First-time-only boundary

The RPC is for a wallet that is not yet encrypted. Route to the exact wallet, confirm encryption state and stop all signing, withdrawal and wallet-backup jobs before use. Attempting to treat it as a routine passphrase rotation confuses lifecycle states; encrypted wallets require the dedicated change call and their own recovery process.

Passphrase quality

Historical help only enforced at least one character but advised a long passphrase. Use a high-entropy unique secret generated and stored through an approved recovery system, not a memorable phrase reused elsewhere. Confirm keyboard layout, encoding and entry on a disposable encrypted test wallet before applying the procedure to production.

RPC secret transmission

The passphrase crosses the RPC boundary. Keep RPC local or inside a protected administrative channel and prevent shell history, process arguments, terminal logging, monitoring traces, screen recordings and support tools from capturing it. Never place the secret in scripts, configuration repositories or article evidence. Only a fingerprinted recovery record should identify custody.

Expected shutdown

The 0.16.0 command shuts down bitcoind after encryption. Treat that as part of the planned change, not a crash. Drain dependent services, monitor clean termination, verify no supervisor restart races and inspect the wallet only after a controlled restart. A call timing out while the server exits is not enough evidence of failure or success.

Unlock and relock workflow

walletpassphrase creates a timed private-key unlock and walletlock removes it early. Use the shortest practical duration, bind signing to an approved request and alert on unexpectedly long unlocked state. Lock after the operation and test that later signing fails. Encryption offers little protection if automation leaves the wallet unlocked continuously.

Backup and recovery

Create verified backups before and after encryption under the release’s wallet rules. Store the passphrase separately from encrypted files and retain compatible software and migration notes. In isolation, restore the encrypted wallet, prove wrong-passphrase rejection, unlock briefly, sign disposable data and relock without exposing the passphrase in evidence.

Threat boundary

Encryption mitigates theft of a locked wallet file. It does not stop malware on an unlocked node, keylogging, RPC compromise, unauthorised transactions during an unlock or loss of both wallet and passphrase. Combine host isolation, least-privilege RPC, withdrawal limits, offline recovery and monitoring rather than presenting encryption as complete custody security.

Conclusion

encryptwallet changes wallet custody and deliberately stops the node. Safe use requires protected secret entry, a planned restart, short unlock windows and a separately stored, tested recovery path for both the wallet and passphrase.