Bitcoin Core getreceivedbyaccount RPC: Deprecated Receipt Guide

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

Deprecated account model

Accounts grouped wallet addresses for bookkeeping inside one wallet. They did not isolate keys, coins or risk. A name could be the empty default account. Preserve the interface only for controlled legacy compatibility and plan migration to labels and explicit transaction records.

Received is not balance

The RPC totals qualifying incoming amounts even if outputs were later spent. It does not subtract outgoing payments or fees and cannot answer how much is currently spendable. Use wallet transaction and UTXO evidence for balances and reconciliation.

Confirmation threshold

minconf defaults to one; zero includes unconfirmed amounts and higher values restrict the total by depth. Record the threshold with every report. Unconfirmed receipts can disappear through replacement or conflict, while confirmed totals can change after reorganisation.

Address assignment boundary

Only addresses linked to the account contribute. Imported addresses, reassignment, historical bookkeeping and change treatment can produce surprising totals. Audit the address set and transactions rather than assuming the account name captures a customer or business unit perfectly.

BTC arithmetic

The historical result is an amount in BTC. Convert to satoshis using decimal-safe arithmetic and preserve the original RPC value for evidence. Binary floating point can create reconciliation errors across many receipts or currency conversions.

Migration strategy

Export account-to-address mappings and transaction evidence, then build an independent ledger keyed by immutable transaction outpoints and business references. Reconcile totals at several confirmation depths before retiring the call. Do not mutate historical wallet assignments merely to make reports match.

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

getreceivedbyaccount is a legacy cumulative receipt report with ambiguous bookkeeping boundaries. Migration should preserve evidence while replacing accounts with explicit addresses, outpoints and confirmation-aware business records.