I want to see the balance of some address using bitcoind.

I set txindex=1 and did a -reindex to get all transactions indexed.

But still, there doesn't seem to be a way to get balances of an address. getreceivedbyaddress doesn't work with addresses out of your own wallet (I hoped it would after a -txindex=1 -reindex, but it didn't).

I'm wondering why blockexplorer.com's getreceivedbyaddress can do this for any address but the default client cannot. If you download and sync the whole blockchain, you should be able to query it for any information, right?

  • While I don't know the answer to your question, I would like to point out that txindex is not relevant here, as the client does not need the full index to get the balance for any given address. – Tom van der Woerdt Apr 22 '13 at 14:24
  • I thought it might, but indeed it doesn't seem to be so. – Steven Roose Apr 22 '13 at 15:26
  • found any solution ? – coding_idiot Feb 25 '14 at 6:34
  • @coding_idiot It's not possible (intentionally) to query for any information using bitcoind. It only maintains an index for transactions that are relevant for your wallet. – Steven Roose Feb 26 '14 at 12:05
  • You can use api of some bitcoin exploer like api.blockcypher.com/v1/btc/main/addrs/…. There is also some opensource exploer like github.com/blockcypher/explorer – LF00 Apr 2 '18 at 2:58

By default, what is maintained by the 0.8 blockchain engine is:

  • All blocks
  • A database with all block headers, and the positions on disk for each block
  • A database that represents all unspent transaction outputs (UTXOs), indexed by txid, at the current tip of the block chain
  • Undo files that allow rewinding the effects of blocks on this set of UTXOs.

Nothing related to addresses or balances exists at this level. That is just a client-side representation of the data. The balance of a wallet is the sum of the values of the UTXOs that are spendable with the set of keys in the wallet. You could define the balance of an address as the sum of the values of the UTXOs assigned to a script matching a given address (and this is what several sites do), but presenting it this way is quite confusing - it makes many people think that Bitcoin transactions transfer value from one address to another. This is not true, they consume specific outputs of a previous transaction, and merge and split those into new outputs.

The -txindex option you mention, adds one more thing that is maintained by the validation engine:

  • A database with the positions on disk for each transaction, indexed by txid.

This was added to make the getrawtransaction command work with historical transactions, but again, this has nothing to do with addresses. A database that indexes the UTXO set by address, or even the entire block chain history by address would be possible, but it would be relatively expensive to maintain, and shouldn't be necessary for normal operations (though it is quite useful for debugging...).

Where such things do belong, is in the wallet. The wallet as presented by the reference client does not use "balance of an address" - it rather sees addresses as entry points into the wallet, but manages the coins in the entire wallet together, regardless of what address they were last sent to. This also confuses people who are used to look at blockexplorer-like websites, when they realize that for example change is always sent to a fresh address.

So, to give a real answer: if you really want to track a balance, you need the wallet interface. Right now, this is quite unflexible, but there are plans to improve this situation soon. We'll hopefully soon get support for multiple wallets, and watch-only wallets, where you can just add addresses you'd like to track, without having their keys.

  • Maybe you should add a small section on how to calculate the information I am looking for using the current bitcoind functionality. I suppose I have to use listunspent or something like that? Or is it really just impossible? – Steven Roose Apr 23 '13 at 10:17
  • It's just impossible, unless you have a wallet with the keys in it. – Pieter Wuille Apr 23 '13 at 19:46
  • 1
    Well, not impossible in theory: if you have -txindex enabled, you can iterate through all blocks using getblockhash and getblock, iterate through all transactions in each block using getrawtransaction, and look for outputs crediting the address you want, or being consumed in an input. This would likely take hours... – Pieter Wuille Apr 23 '13 at 19:48
  • 1
    It doesn't index any address balances at all, but for addresses known to the wallet, it tracks them (during download/sync/rescan of the blockchain). And this is indeed a shortcoming. There's a planned feature to allow "watch-only wallets", which would allow importing addresses instead of keys. – Pieter Wuille Apr 23 '13 at 22:05
  • 1
    Yes, use watch-only addresses. – Pieter Wuille Jun 9 '17 at 23:29
  1. import all address using "importaddress"
  2. you can get balance using "listunspent", but you must sum all unspent amount per an address.

This comes from the Original Bitcoin client/API calls list regarding the command getreceivedbyaddress.

Returns the total amount received by in transactions with at least [minconf] confirmations. While some might consider this obvious, value reported by this only considers receiving transactions. It does not check payments that have been made from this address. In other words, this is not "getaddressbalance". Works only for addresses in the local wallet, external addresses will always show 0. [Boldness added by me.]

Technically you are right; the blockchain carries the information you are looking for. The original client however does not have the function to compute it.

  • I knew that it was noted like this, but I wanted to know why it was so and if there is a workaround method to eventually achieve what getreceivedbyaddress cannot. – Steven Roose Apr 23 '13 at 20:18
  • I'm sorry, but how is it that you're using getaddressbalance? What version of bitcoind are you using? – earthmeLon Oct 13 '13 at 15:44
  • How can I use getreceivedbyaddress? To what should I send it? Is there any simple example of this command or any other? – アレックス Sep 10 '14 at 12:39
  • @earthmeLon - I presume that the getaddressbalance @jorijnsmit mentioned was just a hypothetical command. – Priidu Neemre Feb 4 '15 at 12:46
  • I think it does exists via RPC: bitcoin.org/en/developer-reference#getreceivedbyaddress – danger89 Oct 6 '19 at 21:02

The concept of an "address balance" is based on confusion.

The way Bitcoin is designed, there are three different concepts related: addresses, wallets, and accounts. Wallets are comprised of one or more accounts, each having a balance (which may even be negative). The wallet as a whole has a balance totalling the sum of all accounts (which must always be positive).

Addresses are merely entry points to a wallet; they do not have balances, and should only ever* be used once. Addresses are associated with an account: when coins are received on the address, it credits that account - note that this is a one-way association: the account is not associated with the address, nor the coin received; its balance is simply increased by the amount received. When you spend bitcoins, your wallet chooses coins to spend at (more or less) random, with no concern for how they were received, and will usually use a completely new invisible address internally with itself, that you will not see as an end-user. Overall, these are some of the reasons why it makes little sense to talk about an "address balance".

* While it is fairly common that people reuse addresses for deposits or donations, doing so is harmful to yourself and others using Bitcoin in a number of ways which are outside the scope of this question.

  • 20
    On the contrary, accounts and wallets are not real, while only addresses are. I'd say all unspent outputs with a given address constitute the address's balance. There needs to be a way in bitcoind to query the list of unspent outputs for a given address (irrespective of whether it is in my "wallet" or "account") – Jus12 Jul 2 '13 at 20:53
  • 1
    @Jus12 You can use the scantxoutset RPC for that now, which scans the UTXO set instead of the entire blockchain. – Pieter Wuille Jan 30 '20 at 3:33

"We'll hopefully soon get support for (...) watch-only wallets, where you can just add addresses you'd like to track, without having their keys." –Pieter Wuille

From what I've seen, Pieter Wuille and others included this feature in Bitcoin Core release 0.10.0, so that now it is possible to use Bitcoin Core to get the balance of whatever address just by following these steps:

1) Create a new wallet (stop the program, rename the old wallet.dat file, restart the program and it will create a new empty wallet.dat).

2) Start Bitcoin Core, and go to Help > Debugging Window > Console.

3) On the console's command line, execute the following command:

importaddress the_address_you_are_interested_in

Note that this will cause the program to rescan the entire block chain, which can take several minutes.

Then you can close the debugging window. Now the main window of the program shows two columns of balances, the first one is the balance of the normal addresses in the wallet (the ones whose bitcoins you can spend), and the second one is the balance of the watch-only addresses in the wallet. This last one is what you were looking for.

Once you are done, you can stop the program, delete or rename the wallet or move it somewhere esle, and rename the old wallet back to "wallet.dat".

Note that the Bitcoin client must have an updated copy of the entire block chain, as the default rescan=true option of importaddress doesn't accept pruned block chains, and rescan=false won't show the current balance.

I have not tried this and I'm no bitcoin expert, so take this answer with caution.

  • Interesting to know. Would this also be possible on the command-line only? How would I be able to query for the output after the indexing finished? – Ben Dec 17 '20 at 15:02

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.