api/v2/balancehistory - Bitcoin Cash

Example code for the api/v2/balancehistory REST method. Complete guide on how to use the api/v2/balancehistory REST method in the GetBlock Web3 documentation.

This endpoint returns aggregated balance-change history for an address, extended public key, or descriptor over a time range. Results are grouped into intervals and can include fiat rates.

Parameters

Parameter	Type	Location	Required	Description
address	string	path	Yes	Address, extended public key, or descriptor. URL-encode descriptors
from	integer	query	No	Unix timestamp lower bound
to	integer	query	No	Unix timestamp upper bound
fiatcurrency	string	query	No	Fiat currency code to include in rates
groupBy	integer	query	No	Aggregation interval in seconds. Default 3600

Request

cURL

curl --location --request GET 'https://go.getblock.io/<ACCESS-TOKEN>/api/v2/balancehistory/bitcoincash:qpm2qsznhks23z7629mms6s4cwef74vcwvy22gdx6a?from=1617100000&to=1617300000&fiatcurrency=usd'

JavaScript

example.js

const response = await fetch(
    'https://go.getblock.io/<ACCESS-TOKEN>/api/v2/balancehistory/bitcoincash:qpm2qsznhks23z7629mms6s4cwef74vcwvy22gdx6a?from=1617100000&to=1617300000&fiatcurrency=usd'
);
console.log(await response.json());

Python

example.py

import requests

response = requests.get('https://go.getblock.io/<ACCESS-TOKEN>/api/v2/balancehistory/bitcoincash:qpm2qsznhks23z7629mms6s4cwef74vcwvy22gdx6a?from=1617100000&to=1617300000&fiatcurrency=usd')

print(response.json())

Response

[
    {
        "time": 1617177600,
        "txs": 1,
        "received": "9407625",
        "sent": "0",
        "sentToSelf": "0",
        "rates": {
            "usd": 512.34
        }
    }
]

Response Parameters

Field	Type	Description
time	integer	Start of the interval as a Unix timestamp
txs	integer	Number of transactions in the interval
received	string	Total received in the interval, in satoshis
sent	string	Total sent in the interval, in satoshis
sentToSelf	string	Amount sent back to the same account, in satoshis
rates	object	Fiat rates at the interval, when a currency is requested

Use Cases

• Balance Charts: Plot an address balance over time in intervals

• Fiat Valuation: Attach historical fiat rates to balance changes

• Activity Windows: Aggregate history by day, hour, or custom interval

• Reporting: Produce time-bucketed received and sent totals

Error Handling

HTTP Status	Message	Description
400	Bad request	The address, XPUB, or descriptor is malformed
404	Not found	No indexed data exists for the requested account
500	Internal error	The indexer failed to read account data