Anyblock is now proudly part of Blockdaemon - read the announcement in our blog

Search documentation

Token & Coin Balance Endpoints

Overview

This section describes Anyblock endpoints for retrieving the balances of tokens and native coins. Each of them returns a JSON object with the information on the current or historical balance.

To learn about how these endpoints can be used in real practice, see the Use Cases Token Balance article.

Also note that the information on token and coin balances is available in our Block Explorer tool if you enter or select a token or wallet address

token (Top Holders)

balance

GET /{technology}/{blockchain}/{network}/token/{tokenAddress}/balance

This endpoint retrieves the current balances of the top 500 accounts holding a given token address.

To use it, you need to specify a token address, for example:
0xBA11D00c5f74255f56a5E366F4F77f5A186d7f55

A sample query (Ethereum Mainnet):

https://api.anyblock.tools/ethereum/ethereum/mainnet/token/0xBA11D00c5f74255f56a5E366F4F77f5A186d7f55/balance

A snippet of the output:

[
    {
         "id": "0x3035de3113e6c0bc8f13b499a22ec2b4b2cbfe286b432abc09a2d335b9c71436",
         "account": "0x7a62a7DcF64e1eB94E374ec187AD14BA6e595062",
         "block_hash": "0xf3f1f0e8bd5ef11560f8351a5115f8a098153acc06d4b51fe1ac61b3548055a6",
         "block_number": "11635184",
         "balance": "62387284500000000000000000",
         "balance_scaled": "62387284.5",
         "timestamp": 1610388892
    },
    ...
]

Output fields:

Field Description
id The id of the balance object
account The address of the account
block_hash The hash of the block at which balance was last changed
block_number The number of the block at which balance was last changed
balance The current token balance
balance_scaled The token balance (balance) scaled by the token decimals
timestamp The date and time when balance was last changed (Unix time)

historical

GET /{technology}/{blockchain}/{network}/token/{tokenAddress}/balance/historical

This endpoint retrieves the historical balances of the top 500 accounts holding a given token address. Range queries, however, return all accounts and not only the top 500 – see the description of the query parameters in the table below.

To use the endpoint, you need to specify a token address and one of these parameters:

Parameter Data type Output
block number Top 500 balances changed at a given block number or the latest before it
hash string Top 500 balances changed at a given block hash or the latest before it
timestamp epochSeconds Top 500 balances changed at a given timestamp or the latest before it
fromBlock &
toBlock
number All balances changed between two given block numbers or the latest before fromBlock
fromTimestamp &
toTimestamp
epochSeconds All balances changed between two given timestamps or the latest before fromTimestamp

For example:

  • token 0xBA11D00c5f74255f56a5E366F4F77f5A186d7f55
  • timestamps ?fromTimestamp=1619827200&toTimestamp=1619902800

A sample query (Ethereum Mainnet):

https://api.anyblock.tools/ethereum/ethereum/mainnet/token/0xBA11D00c5f74255f56a5E366F4F77f5A186d7f55/balance/historical/?fromTimestamp=1619827200&toTimestamp=1619902800

A snippet of the output:

[
    {
        "id": "0x37872c10bcc535c086d307a4122a7fc2d4d8f9952ca487e913b824b6cd2c06a6",
        "account": "0x7a62a7DcF64e1eB94E374ec187AD14BA6e595062",
        "block_hash": "0x9771fb8825bf3dbebc3cf9f57424c6d72beeb75f4ed83f437096f19aad897d0d",
        "block_number": "11315081",
        "balance": "63387284500000000000000000",
        "balance_scaled": "63387284.5",
        "timestamp": 1619827200
    },
    ...
]

Output fields:

Field Description
id The id of the balance object
account The address of the account
block_hash The hash of the block at which balance was changed
block_number The number of the block at which balance was changed
balance The token balance at a specific time (see timestamp)
balance_scaled The token balance (balance) scaled by the token decimals
timestamp The date and time when balance was changed (Unix time)

wallet (All Tokens)

tokenbalance

GET /{technology}/{blockchain}/{network}/wallet/{walletAddress}/tokenbalance

This endpoint retrieves all current token balances of a given wallet address and shows the meta information of the tokens.

To use it, you need to specify a wallet address, for example:
0x4b732af53A79636902964012F6655d32ADe81E7F

A sample query (Ethereum Mainnet):

https://api.anyblock.tools/ethereum/ethereum/mainnet/wallet/0x4b732af53A79636902964012F6655d32ADe81E7F/tokenbalance

A snippet of the output:

[
    {
        "id": "0xc121ae914bbb53ea850f6e83026fc8d2b47d937d29d7c69cd2c913b35697aa38",
        "token": {
            "symbol": "FTM",
            "address": "0x4E15361FD6b4BB609Fa63C81A2be19d873717870",
            "name": "Fantom Token"
        },
        "block_hash": "0x5433975119f2d0419114d562bc165869ccef015aa626c5d22b56faf275c6ba8c",
        "block_number": "13486236",
        "balance": "0",
        "balance_scaled": "0",
        "timestamp": 1635160121
    },
    ...
]

Output fields:

Field Description
id The id of the balance object
token The token meta information
├── symbol The symbol of the token
├── address The address of the token
└── name The name of the token
block_hash The hash of the block at which balance was last changed
block_number The number of the block at which balance was last changed
balance The current token balance
balance_scaled The token balance (balance) scaled by the token decimals
timestamp The date and time when balance was last changed (Unix time)

historical

GET /{technology}/{blockchain}/{network}/wallet/{walletAddress}/tokenbalance/historical

This endpoint retrieves all historical token balances of a given wallet address and shows the meta information of the tokens.

To use it, you need to specify a wallet address and one of these parameters:

Parameter Data type Output
block number All balances changed at a given block number or the latest before it
hash string All balances changed at a given block hash or the latest before it
timestamp epochSeconds All balances changed at a given timestamp or the latest before it
fromBlock &
toBlock
number All balances changed between two given block numbers or the latest before fromBlock
fromTimestamp &
toTimestamp
epochSeconds All balances changed between two given timestamps or the latest before fromTimestamp

For example:

  • token 0x4b732af53A79636902964012F6655d32ADe81E7F
  • timestamps ?fromTimestamp=1619827200&toTimestamp=1625086800

A sample query (Ethereum Mainnet):

https://api.anyblock.tools/ethereum/ethereum/mainnet/wallet/0x4b732af53A79636902964012F6655d32ADe81E7F/tokenbalance/historical/?fromTimestamp=1619827200&toTimestamp=1619902800

A snippet of the output:

[
    {
        "id": "0x2a4d11c719c23ddb4f30c0d1cad1af0a5b7c87e7b14a8f0a3ad632a133af9ca2",
        "token": {
            "symbol": "UNI-V2",
            "address": "0x37b4Cae8d2581E81140e2e172d4D7Aed3A675bc7",
            "name": "Uniswap V2"
        },
        "block_hash": "0x13f12defbaf1fe683ed6367e83aa3f7f16912248eb7747a029dfe2be2f44c90a",
        "block_number": "12036452",
        "balance": "0",
        "balance_scaled": "0",
        "timestamp": 1619827200
    },
    ...
]

Output fields:

Field Description
id The id of the balance object
token The token meta information
├── symbol The symbol of the token
├── address The address of the token
└── name The name of the token
block_hash The hash of the block at which balance was changed
block_number The number of the block at which balance was changed
balance The token balance at a specific time (see timestamp)
balance_scaled The token balance (balance) scaled by the token decimals
timestamp The date and time when balance was changed (Unix time)

wallet (Specific Token)

tokenbalance

GET /{technology}/{blockchain}/{network}/wallet/{walletAddress}/tokenbalance/{tokenAddress}

This endpoint retrieves current balance of a given token address for a given wallet address.

To use it, you need to specify a wallet address and a token address, for example:

  • wallet 0x4b732af53A79636902964012F6655d32ADe81E7F
  • token 0xBA11D00c5f74255f56a5E366F4F77f5A186d7f55

A sample query (Ethereum Mainnet):

https://api.anyblock.tools/ethereum/ethereum/mainnet/wallet/0x4b732af53A79636902964012F6655d32ADe81E7F/tokenbalance/0xBA11D00c5f74255f56a5E366F4F77f5A186d7f55

The output:

[
    {
        "id": "0xb914756e82da8dd56119c959bf1daaa17fe4bb5e1c0f3225c8bd147db601039f",
        "block_hash": "0x8b6b9addee76991464f82f705fe98ac35192abbea03c37ca277e8d6d87b57116",
        "block_number": "13508090",
        "balance": "200000000000000000000",
        "balance_scaled": "200",
        "timestamp": 1635456360
    }
]

Output fields:

Field Description
id The id of the balance object
block_hash The hash of the block at which balance was last changed
block_number The number of the block at which balance was last changed
balance The current token balance
balance_scaled The token balance (balance) scaled by the token decimals
timestamp The date and time when balance was last changed (Unix time)

historical

GET /{technology}/{blockchain}/{network}/wallet/{walletAddress}/tokenbalance/{tokenAddress}/historical

This endpoint retrieves the historical balances of a given token address for a given wallet address.

To use it, you need to specify a wallet address, a token address, and one of these parameters:

Parameter Data type Output
block number The balance at a given block number or the latest before it
hash string The balance at a given block hash or the latest before it
timestamp string The balance at a given timestamp or the latest before it
fromBlock &
toBlock
number All balance changes between two given block numbers or the latest before fromBlock
fromTimestamp &
toTimestamp
epochSeconds All balance changes between two given timestamps or the latest before fromTimestamp

For example:

  • wallet 0x4b732af53A79636902964012F6655d32ADe81E7F
  • token 0xBA11D00c5f74255f56a5E366F4F77f5A186d7f55
  • timestamps ?fromTimestamp=1619827200&toTimestamp=1625086800

A sample query (Ethereum Mainnet):

https://api.anyblock.tools/ethereum/ethereum/mainnet/wallet/0x4b732af53A79636902964012F6655d32ADe81E7F/tokenbalance/0xBA11D00c5f74255f56a5E366F4F77f5A186d7f55/historical/?fromTimestamp=1619827200&toTimestamp=1619902800

A snippet of the output:

[
    {
        "id": "0x41ab425ebbc8a62f3ee04e7a784a1db5127598ab2118ab810570eab2056273d8",
        "block_hash": "0x8c3ec45ca13ad654b120f7c98d3d1d1163b588f0ad4f43e48a13a407d20751aa",
        "block_number": "12639641",
        "balance": "543238500230805543064",
        "balance_scaled": "543.238500230805543064",
        "timestamp": 1623768117
    },
    ...
]

Output fields:

Field Description
id The id of the balance object
block_hash The hash of the block at which balance was changed
block_number The number of the block at which balance was changed
balance The token balance at a specific time (see timestamp)
balance_scaled The token balance (balance) scaled by the token decimals
timestamp The date and time when balance was changed (Unix time)

wallet (Native Coin)

coinbalance

GET /{technology}/{blockchain}/{network}/wallet/{walletAddress}/coinbalance

This endpoint retrieves current native coin balance of a given wallet address.

To use it, you need to specify a wallet address, for example:
wallet 0x4b732af53A79636902964012F6655d32ADe81E7F

A sample query (Ethereum Mainnet):

https://api.anyblock.tools/ethereum/ethereum/mainnet/wallet/0x4b732af53A79636902964012F6655d32ADe81E7F/coinbalance

The output:

[
    {
        "id": "0xae7fd6083194f4a1a60813c22564607b8591ac2190f9d60a7dd2a6c4941ac5e8",
        "block_hash": "0xd19568300fd493f99efd15b3ebab73475808e212f362b519f8309e6dd028d6cb",
        "block_number": "13718812",
        "balance": "149192353841872605",
        "timestamp": 1638330425
    }
]

Output fields:

Field Description
id The id of the balance object
block_hash The hash of the block at which balance was last changed
block_number The number of the block at which balance was last changed
balance The current coin balance
timestamp The date and time when balance was last changed (Unix time)

historical

GET /{technology}/{blockchain}/{network}/wallet/{walletAddress}/coinbalance/historical

This endpoint retrieves all historical native coin balances of a given wallet address.

To use it, you need to specify a wallet address and one of these parameters:

Parameter Data type Output
block number The balance at a given block number or the latest before it
hash string The balance at a given block hash or the latest before it
timestamp string The balance at a given timestamp or the latest before it
fromBlock &
toBlock
number All balance changes between two given block numbers or the latest before fromBlock
fromTimestamp &
toTimestamp
epochSeconds All balance changes between two given timestamps or the latest before fromTimestamp

For example:

  • wallet 0x4b732af53A79636902964012F6655d32ADe81E7F
  • timestamps ?fromTimestamp=1619827200&toTimestamp=1625086800

A sample query (Ethereum Mainnet):

https://api.anyblock.tools/ethereum/ethereum/mainnet/wallet/0x4b732af53A79636902964012F6655d32ADe81E7F/coinbalance/historical/?fromTimestamp=1619827200&toTimestamp=1619902800

A snippet of the output:

[
    {
        "id": "0xe04ed8d91bc71fc89f393f785b20f284fb808b9de7a98ca81d1fca3507b1372c",
        "block_hash": "0x3b834fce1aac935bbbe7f26e74e4381a540a4f0eba4f05bd724cbe84b412ef4c",
        "block_number": "12345241",
        "balance": "3006380304769689740",
        "timestamp": 1619831036
    },
    ...
]

Output fields:

Field Description
id The id of the balance object
block_hash The hash of the block at which balance was changed
block_number The number of the block at which balance was changed
balance The coin balance at a specific time (see timestamp)
timestamp The date and time when balance was changed (Unix time)

Interested or questions?

 

Sascha Göbel
(Co-Founder & Chief Technology Officer)
sascha@anyblockanalytics.com
+49 6131 3272372

    

Pin It on Pinterest