Search code examples
rpchedera-hashgraphhedera

How to get the HBAR balance of an account on Hedera at a specific time in the past?

I can query the current balance from the mirror node using this request:

curl --request GET \
    'https://testnet.mirrornode.hedera.com/api/v1/balances?account.id=0.0.3996280' \
    --header 'Content-Type: application/json'

Based on the documentation found here, for /api/v1/balances. However, the only query params available for this endpoint are account.id, account.balance, account.publickey, limit, and order. Is there an alternative way to do this?

Note: I have thought of a possible alternative way to do this, using eth_getBalance over JSON-RPC instead of the Mirror node APIs, like so:

curl -X POST \
    --data-raw '{
        "jsonrpc": "2.0",
        "method": "eth_getBalance",
        "params":
        [
            "0x7394111093687e9710b7a7aeba3ba0f417c54474",
            "latest"
        ],
        "id": 0
    }'

... however, I'm not sure how I would need specify:

  • a native-Hedera (non-EVM) address like 0.0.3996280 as the first parameter in params
  • a block number as the 2nd parameter in params, since Hedera does not have blocks AFAICT
Solution

  • The docs are not very clear about this, but there is indeed a timestamp parameter for the /api/v1/balances API endpoint.

    The swagger UI for the same /api/v1/balances endpoint is much clearer about this, defining it as:

    The consensus timestamp in seconds.nanoseconds format with an optional comparison operator

    ... and it even has several example values with equals, less than, and greater than operators on it.

    Example queries

    If you specify a timestamp from before when this account was created:

    curl --request GET \
    'https://testnet.mirrornode.hedera.com/api/v1/balances?account.id=0.0.3996280&timestamp=1083013493.000000000' \
    --header 'Content-Type: application/json'

    You will get a response showing that it had a zero/ empty balance:

    {"timestamp":null,"balances":[],"links":{"next":null}}

    However, if you specify a timestamp that is from after this account was created (and funded):

    curl --request GET \
    'https://testnet.mirrornode.hedera.com/api/v1/balances?account.id=0.0.3996280&timestamp=1683013493.000000000' \
    --header 'Content-Type: application/json'

    You will get a response showing that it does indeed have a balance, and the value at the time, of 1000000000000 tinybars, which is equal to 100 HBAR:

    {"timestamp":"1683012600.190869000","balances":[{"account":"0.0.3996280","balance":1000000000000,"tokens":[]}],"links":{"next":null}}

    Hope that helps!