<p>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.</p>
<p>This is more a philosophical point than a technical one. Addresses are <strong>entry points</strong> 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.</p>
<p>Again, there is nothing technically wrong with the notion of &quot;balance of an address&quot; - 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).</p>
<p>So what the <code>listreceivedbyaddress</code> RPC does is show the total of what was <em>received</em> on each address; exactly what you need to determine which bills/invoices/items were paid. To determine how much <em>remaining</em> balance you have in your wallet, use <code>getbalance</code> 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.</p>
<p>Given the modern notion of &quot;address balance&quot; popularized by block explorers, I do agree the explanation in the RPC help is confusion, and could be improved.</p>

CC BY-SA 4.0
2021-08-29T17:42:55.397Z
2021-08-30T12:45:08.623Z
2021-08-30T12:45:08.623Z
Pieter Wuille
<p>From <code>bitcoin-cli --testnet help listreceivedbyaddress</code>:</p>
<blockquote>
<p>listreceivedbyaddress ( minconf include_empty include_watchonly &quot;address_filter&quot; )</p>
<p>List <em><strong>balances</strong></em> by receiving address.</p>
</blockquote>
<p>The issue is that <code>listreceivedbyaddress</code> does not do this, though it actually does what its name suggests.</p>
<p>Let's take a look at <a href="https://mempool.space/testnet/address/tb1qf9p5mrl2mf4ulae257ewj2rns6hsu2y4p8j0q2" rel="nofollow noreferrer">this address</a>.</p>
<p><code>listreceivedbyaddress</code> shows what corressponds to <strong>Total received</strong> and not <strong>Balance</strong>.
One can easily verify it by importing the address, <code>bitcoin-cli --testnet importaddress tb1qf9p5mrl2mf4ulae257ewj2rns6hsu2y4p8j0q2</code>,
to their wallet.
Am I missing something or is it a bug?</p>

<bitcoin-cli><balance>
Why is the decription of listreceivedbyaddress misleading and contradictory to what says its name?
John Smith
# Why is the decription of listreceivedbyaddress misleading and contradictory to what says its name?

(Asked by: username_0 on 2021-08-28)

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](https://mempool.space/testnet/address/tb1qf9p5mrl2mf4ulae257ewj2rns6hsu2y4p8j0q2).

`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?

**Tags:** bitcoin-cli, balance


---

## 1 answers

### Answer by username_1 on 2021-08-29. Score: 2 | Accepted answer

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.


---

