Get Address Historical Balance#
Retrieve an address's native coin or token balance at a specified block height (historical balance). This is a premium endpoint. Only some chains are supported (BTC, ETH, TRON, BSC, and others).
Supported chains: see Get Block API Supported Chains (apiName: address-balance-history).
Request URL#
GET
https://web3.okx.com/api/v6/explorer/block/address-balance-historyRequest Parameters#
| Parameter | Type | Required | Description |
|---|---|---|---|
| chainIndex | String | Yes | Unique identifier of the chain, e.g., 1 for ETH, 0 for BTC. See Get Block API Supported Chains for supported values. |
| height | String | Yes | Block height (digits only). Returns the balance at that height. |
| address | String | Yes | Address to query the balance for. |
| tokenContractAddress | String | No | Token contract address. When omitted, returns the native coin balance. |
| project | String | No | Project identifier. |
Response Parameters#
| Parameter | Type | Description |
|---|---|---|
| address | String | Address the balance was queried for. |
| height | String | Block height the balance was queried at. |
| balance | String | Balance. |
| balanceRaw | String | Raw balance (no decimals, in the smallest unit). |
| balanceSymbol | String | Balance currency: the native token name for a native coin query, or the token's abbreviated name for a specific token query. |
| tokenContractAddress | String | Token contract address; an empty string "" for a native coin query. |
| blockTime | String | Block time of that block, as a Unix timestamp in milliseconds, e.g., 1597026383085. |
Request Example#
shell
curl --location --request GET 'https://web3.okx.com/api/v6/explorer/block/address-balance-history?chainIndex=1&height=19000000&address=0x28c6c06298d514db089934071355e5743bf21d60' \
--header 'OK-ACCESS-KEY: 37c541a1-****-****-****-10fe7a038418' \
--header 'OK-ACCESS-SIGN: leaV********3uw=' \
--header 'OK-ACCESS-PASSPHRASE: 1****6' \
--header 'OK-ACCESS-TIMESTAMP: 2023-10-18T12:21:41.274Z'
Response Example#
json
{
"code": "0",
"msg": "",
"data": [
{
"address": "0x28c6c06298d514db089934071355e5743bf21d60",
"height": "19000000",
"balance": "123456.735278657822018352",
"balanceRaw": "123456735278657822018352",
"balanceSymbol": "ETH",
"tokenContractAddress": "",
"blockTime": "1705146239000"
}
]
}