Bitcoin Core getnewaddress RPC: Receiving Address Guide

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

Wallet and network boundary

Call the intended unlocked or appropriately available wallet and verify chain identity before showing an address. Mainnet and test-chain destinations must never share an invoice flow. Restrict RPC credentials because address generation can consume keypool state and expose internal bookkeeping.

Deprecated account argument

The optional account was an address-book grouping, not a separate wallet balance or custody boundary. It could create a named account implicitly and the empty string selected the default account. New designs should use supported labels and wallet separation rather than reproduce account-era accounting.

Address type choice

legacy, p2sh-segwit and bech32 had different compatibility and fee properties in 0.16. Select explicitly when interoperability matters and test the payer. The daemon default can change through configuration, so an omitted type is not a stable integration contract.

Freshness and reuse

Return a new address per invoice and bind it atomically to the order before exposing it. Reuse weakens privacy and complicates reconciliation. If an application crashes between generation and storage, it must safely discover or quarantine the unassigned address rather than issue it twice.

Backup and recovery

HD wallets can derive later addresses from seed material, but recovery still depends on wallet format, birth time, derivation behaviour and complete rescan coverage. Test restoration beyond the current keypool and retain encrypted backups under controlled custody.

Payment validation

Validate address encoding before display, but treat on-chain transaction and output script as authoritative. Monitor the exact script, confirmation depth and reorganisation state. Never mark an order paid because an address was generated or copied successfully.

How specialists test it

Operators test the command on a non-production node first. They check a normal reply, an invalid request, a timeout and a restart. This shows what the response means and prevents one local result from being mistaken for a network-wide outcome.

Conclusion

getnewaddress is a state-changing wallet operation, not a formatting helper. Reliable receiving systems bind fresh destinations atomically, verify network and output scripts and prove recovery across supported address types.