Address Balance History API
The BalanceUpdates API provides information on the balance updates of a specific address for a particular token on a supported blockchain. This API enables developers to retrieve a list of balance updates for a particular token and address, as well as additional information about each balance update.
You can use BalanceUpdates API to get latest balance for an address.
Balance of an address​
Open the query on GraphQL IDE using this link.
query MyQuery {
EVM(dataset: archive, network: eth) {
BalanceUpdates(
where: {BalanceUpdate: {Address: {is: "0xcf1DC766Fc2c62bef0b67A8De666c8e67aCf35f6"}}}
orderBy: {descendingByField: "balance"}
) {
Currency {
Name
}
balance: sum(of: BalanceUpdate_Amount, selectWhere: {gt: "0"})
}
}
}
Parameters
dataset: archive
: This parameter specifies that the combined dataset is being used.network: eth
: This parameter specifies that the Ethereum network is being queried.where: {BalanceUpdate: {Address: {is: "0xcf1DC766Fc2c62bef0b67A8De666c8e67aCf35f6"}}}
: This parameter filters the results of the query based on the Ethereum address "0xcf1DC766Fc2c62bef0b67A8De666c8e67aCf35f6".
Returned Data
Currency { Name }
: This field specifies the currency in which the balance is expressed. In this case, theName
of the currency is retrieved.balance: sum(of: BalanceUpdate_Amount)
: This field retrieves the total balance of the specified Ethereum address, broken down by currency. Thesum
function is used to calculate the total amount, and theof
parameter specifies the field to sum, which isBalanceUpdate_Amount
. The aliasbalance
is used to rename the field tobalance
for readability.
Balance for an address for a specific currency​
You can also get a balance for a specific currency for a given address just by adding Currency Filer. As you know, names on blockchains are not unique; however, addresses are. Therefore, while mentioning currencies, always use their currency address. Open the query on GraphQL IDE using this link.
query MyQuery {
EVM(dataset: archive, network: eth) {
BalanceUpdates(
where: {BalanceUpdate: {Address: {is: "0x3416cf6c708da44db2624d63ea0aaef7113527c6"}}, Currency: {SmartContract: {is: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"}}}
) {
Currency {
Name
SmartContract
}
balance: sum(of: BalanceUpdate_Amount)
}
}
}
Parameters
dataset: archive
: This parameter specifies that the combined dataset is being used.network: eth
: This parameter specifies that the Ethereum network is being queried.where: {BalanceUpdate: {Address: {is: "0x3416cf6c708da44db2624d63ea0aaef7113527c6"}}, Currency: {SmartContract: {is: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"}}}
: This parameter filters the results of the query based on the Ethereum address "0x3416cf6c708da44db2624d63ea0aaef7113527c6" and the smart contract address "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48". TheCurrency
field specifies the currency to filter by, and theSmartContract
field specifies the smart contract address to filter by.
Returned Data
Currency { Name, SmartContract }
: This field specifies the currency in which the balance is expressed. In this case, theName
andSmartContract
of the currency are retrieved.balance: sum(of: BalanceUpdate_Amount)
: This field retrieves the total balance of the specified Ethereum address, broken down by currency. Thesum
function is used to calculate the total amount, and theof
parameter specifies the field to sum, which isBalanceUpdate_Amount
. The aliasbalance
is used to rename the field tobalance
for readability
Balance updates of an address​
Here's the query to retrieve the balance updates for a particular address for a specific token on the Ethereum Mainnet blockchain:
query MyQuery {
EVM(dataset: archive, network: eth) {
BalanceUpdates(
where: {BalanceUpdate: {Address: {is: "0x3416cf6c708da44db2624d63ea0aaef7113527c6"}}, Block: {Date: {after: "2023-02-15"}}}
orderBy: {descending: BalanceUpdate_Amount}
) {
Currency {
Name
}
Block {
Date
}
BalanceUpdate {
Amount
Type
}
}
}
}
In this query, replace 0x3416cf6c708da44db2624d63ea0aaef7113527c6 with the address for which you want to retrieve balance updates, and adjust the date and other parameters to fit your specific needs. The GraphQL link is here.
Name
: The name of the token.Date
: The timestamp of the update.Amount
: The amount of the token involved in the balance update.Type
: The type of the balance update
Here's an example response for the query:
"BalanceUpdates": [
{
"BalanceUpdate": {
"Amount": "9901.287338",
"Type": "transfer"
},
"Block": {
"Date": "2023-02-27"
},
"Currency": {
"Name": "Tether USD"
}
},
{
"BalanceUpdate": {
"Amount": "989.010990",
"Type": "transfer"
},
"Block": {
"Date": "2023-02-27"
},
"Currency": {
"Name": "Tether USD"
}
},
Balance of a Pool : Uniswap V3​
In the below query, we will get the balance of the Uniswap V3: WBTC-USDT Pool. To do this, we will set the filter{Address: {is: "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599"}
and pass the smart contract 0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599
.
You can run the query here
query MyQuery {
EVM(dataset: archive, network: eth) {
BalanceUpdates(
where: {BalanceUpdate: {Address: {is: "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599"}}}
orderBy: {descendingByField: "balance"}
) {
Currency {
Name
}
balance: sum(of: BalanceUpdate_Amount, selectWhere: {gt: "0"})
BalanceUpdate {
Address
}
}
}
}