This endpoint requires a Growth or Enterprise plan. Learn more.
Returns
Balance!
See Balance
Show Properties
Show Properties
String!
The ID of the wallet (
walletAddress:networkId).String!
The ID of the token (
tokenAddress:networkId).String!
The wallet address.
Int!
The wallet network.
String!
The contract address of the token.
String!
The balance held by the wallet.
Float!
The balance held by the wallet, adjusted by the number of decimals in the token.
Float
The wallet balance expressed for UI display. Defaults to shiftedBalance. For Token-2022 tokens, RAW divides out the active UI amount multiplier. For B20 asset tokens, SCALED multiplies by the active multiplier so the value reflects redeemable units rather than raw token count. IMPORTANT: that B20 adjustment is applied ONLY by the
balances query, which is the one place a uiAmountMode is resolved. Every other source of a Balance — holders, refreshBalances, primeBalance, and the subscriptions — returns the raw shiftedBalance here, so the same holding can read differently across them. Display only: it does not share units with tokenPriceUsd, so do not multiply the two.String
The balance held by the wallet in USD. Computed from
shiftedBalance, NOT from uiBalance — for a B20 asset token those differ by the token’s multiplier, so do not recompute this as uiBalance * tokenPriceUsd.String
The token price in USD, per raw token — the same units as
shiftedBalance. For a B20 asset token this does NOT pair with uiBalance, which is multiplier-adjusted; multiplying the two over-counts by the multiplier. Use balanceUsd for position value.Int
The time that this address first held a token.
Int
The block number at which this balance was last updated. Null when the block is unknown (e.g. native balances) or the underlying balance record cannot be found.
EnhancedToken
Metadata for the token.
See EnhancedToken
String
The token’s route-backed liquidity in USD: the real liquidity supporting the token price, summed across the token’s pairs with valid routing liquidity. Quote assets (a network’s base token and stablecoins) have no route of their own, so they report pool liquidity instead. Null when this stat has not been computed for the token yet.
Int
Unix timestamp (seconds) of the token’s most recent trade/market event across all pools we track. Token-level (not specific to this wallet). Useful for filtering out dead/worthless tokens, e.g. no activity in months.
Wallet
Identity and profile metadata for the wallet holding this balance. Not always available.
See Wallet
String
The economic asset this balance is a view of (
tokenAddress:networkId). On networks where one holding is readable through a native interface and an ERC-20 alias contract, both views share this id. Null elsewhere.Int
The number of decimals
balance is expressed in for this view. A native view reports the native precision (18 on such networks); a contract view reports the alias contract’s decimals (6). token.decimals remains the contract’s metadata. Null elsewhere.Boolean
True when this row is the ERC-20 alias projection (a same-block floor of the native holding, in
balanceDecimals) rather than the authoritative native view; false for the native view. Null elsewhere.Arguments
String!
required
Example
Test this query in the Explorer →subscription {
onBalanceUpdated(walletAddress: "0xADDRESS") {
walletId
tokenId
networkId
balance
shiftedBalance
balanceUsd
tokenPriceUsd
token {
name
symbol
}
}
}