Bitcoin Core getbalance RPC: Historical Wallet Balance Guide

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

Omitted is not empty

Calling with no account returns total currently available wallet balance. Passing empty string requests the deprecated default account calculation, while star means all account-labelled keys. These paths are not interchangeable. API wrappers must preserve argument omission rather than serialise absent input as an empty string.

Available balance

The default result is what the wallet considers currently spendable under settings such as zero-confirmation change policy. It is not total received, confirmed reserves, accounting equity or proof of liquidity on another node. Record wallet, version, chain tip and relevant spendability settings with any operational snapshot.

Confirmation threshold

minconf defaults to one and filters the historical calculation. Zero includes unconfirmed activity and increases replacement and conflict risk. For settlement, use a written confirmation policy and track individual transactions, maturity and reorganisation rather than relying on one aggregate that changes as the chain advances.

Watch-only inclusion

include_watchonly defaults false. Enabling it can add funds the wallet cannot sign for, so label the resulting figure as monitored rather than spendable. Check solvability and signer availability per UTXO. Never feed a watch-inclusive total into automated withdrawal capacity.

Unreliable account mode

The documentation advises avoiding the account argument because conflicting pending transactions such as fee bumps can count spends twice and produce misleading or negative values. Preserve this warning in legacy integration tests and migrate accounting to transaction and UTXO-level records instead of attempting to smooth negative results.

BTC units and precision

The returned amount is BTC. Convert with fixed decimal arithmetic to integer satoshis at the boundary, reject excess precision and label the unit. Compare aggregates from listunspent or wallet transaction state using exact integers, knowing each surface can answer a different question.

Reconciliation harness

Create confirmed, unconfirmed, conflicted, replaced, watch-only and immature fixtures on regtest. Compare omitted, empty, star and named-account calls across minconf values. Reorganise the chain and confirm the application neither double-counts replacements nor treats monitored funds as spendable reserves.

Conclusion

getbalance can answer a narrow wallet-availability question, but its deprecated account modes are explicitly unreliable. Safe systems define confirmation and spendability, preserve argument semantics and reconcile exact UTXOs outside the account ledger.