Learn how to monitor user balances for tokens supported by Aave v4.
User balances provide a comprehensive view of a user's token holdings across different chains, aggregated by token type with supply and borrow APY information.
User Balance Data Structure User balance data provides information about a user's token holdings, including:
Globally unique identifier: for each balance entry
Token identification: name, symbol, icon, decimals
Balance amounts: individual balances per network, total amounts
Yield information: highest and lowest supply/borrow APY for each token
Collateral factors: highest and lowest collateral factors for each token
Fiat valuations: converted amounts in selected currency
The following TypeScript interfaces illustrate the core UserBalance type:
UserBalance TokenInfo TokenAmount ExchangeAmount UserBalance TokenInfo TokenAmount ExchangeAmount interface UserBalance { __typename : "UserBalance" ; id : UserBalanceId ; info : TokenInfo ; balances : TokenAmount [ ] ; totalAmount : DecimalNumber ; exchange : ExchangeAmount ; highestSupplyApy : PercentNumber ; highestBorrowApy : PercentNumber ; lowestSupplyApy : PercentNumber ; lowestBorrowApy : PercentNumber ; highestCollateralFactor : PercentNumber | null ; lowestCollateralFactor : PercentNumber | null ; } Use the useUserBalances
Loading State React Suspense Loading State React Suspense import { type UserBalancesRequest , useUserBalances } from "@aave/react" ;
function UserBalancesList ( { request } : { request : UserBalancesRequest } ) { const { data , loading , error } = useUserBalances ( request ) ;
if ( loading ) return < div > Loading… </ div > ;
if ( error ) return < div > Error: { error . message } </ div > ;
return ( < div > { data . map ( ( balance ) => ( < div key = { balance . id } > < h2 > { balance . info . name } </ h2 > < p > < strong > Total: </ strong > { balance . totalAmount . value . toDisplayString ( 2 ) } { balance . info . symbol } < small > { balance . exchange . symbol } { balance . exchange . value . toDisplayString ( 2 ) } </ small > </ p > < p > < strong > Supply APY: </ strong > { balance . highestSupplyApy . normalized . toFixed ( 2 ) } % </ p > </ div > ) ) } </ div > ) ; } See below some examples of how to use the hook.
Filter by Chains Filter by Hub Filter by Spoke Filter by User Position Filter by Tokens Filter by Chains Filter by Hub Filter by Spoke Filter by User Position Filter by Tokens import { evmAddress , chainId } from "@aave/react" ;
const request : UserBalancesRequest = { user : evmAddress ( "0x456…" ) , filter : { chains : { chainIds : [ chainId ( 1 ) ] , } , } , } ; Sort balances by name or balance value.
import { evmAddress , OrderDirection } from "@aave/react" ;
const request : UserBalancesRequest = { user : evmAddress ( "0x456…" ) , filter : { } , orderBy : { balance : OrderDirection . Desc } , } ; Include tokens with zero balances in the results.
const request : UserBalancesRequest = { user : evmAddress ( "0x456…" ) , filter : { } , includeZeroBalances : true , } ; Specify a different currency for displaying fiat amounts.
import { evmAddress , Currency } from "@aave/react" ;
const { data , loading , error } = useUserBalances ( { user : evmAddress ( "0x456…" ) , filter : { } , currency : Currency . Eur , } ) ;