From bitcoin-cli --testnet help listreceivedbyaddress:

listreceivedbyaddress ( minconf include_empty include_watchonly "address_filter" )

List balances by receiving address.

The issue is that listreceivedbyaddress does not do this, though it actually does what its name suggests.

Let's take a look at this address.

listreceivedbyaddress shows what corressponds to Total received and not Balance. One can easily verify it by importing the address, bitcoin-cli --testnet importaddress tb1qf9p5mrl2mf4ulae257ewj2rns6hsu2y4p8j0q2, to their wallet. Am I missing something or is it a bug?


The confusion is due to the fact that contrary to how block explorers show information, Bitcoin (and by extension the Bitcoin Core wallet) isn't designed for addresses to hold an individual balance.

This is more a philosophical point than a technical one. Addresses are entry points into a wallet. They are identifiers to be given out for individual payments, and by observing how much was received on them, you can track which payments were completed. However, once received, the coins are managed by the receiving wallet, pooled together with coins received on other addresses for the same wallet. For example, wallets, when constructing payments, will consider all coins received on all addresses, and even move remainder to new change addresses.

Again, there is nothing technically wrong with the notion of "balance of an address" - one might think of coins as belonging to an address until those coins are spent. But this isn't the philosophy used in the Bitcoin Core wallet (and several other wallets).

So what the listreceivedbyaddress RPC does is show the total of what was received on each address; exactly what you need to determine which bills/invoices/items were paid. To determine how much remaining balance you have in your wallet, use getbalance and related RPCs, which show the balance of the entire wallet, taking received coins on all addresses into account, and excluding any coins already spent - on chain or pending.

Given the modern notion of "address balance" popularized by block explorers, I do agree the explanation in the RPC help is confusion, and could be improved.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.