User Balances

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
Fiat valuations: converted amounts in selected currency

TypeScript
GraphQL

The following TypeScript interfaces illustrate the core UserBalance type:

interface UserBalance {  __typename: "UserBalance";  id: UserBalanceId;  info: TokenInfo;  balances: TokenAmount[];  totalAmount: DecimalNumber;  fiatAmount: FiatAmount;  highestSupplyApy: PercentNumber;  highestBorrowApy: PercentNumber;  lowestSupplyApy: PercentNumber;  lowestBorrowApy: PercentNumber;}

Fetching User Balances

React
TypeScript
GraphQL

Use the useUserBalances hook to fetch user token balances.

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>;
  // data: UserBalance[]  return (    <div>      {data.map((balance) => (        <div key={balance.info.symbol}>          <h2>{balance.info.name}</h2>          <p>            Total: {balance.totalAmount.value} {balance.info.symbol}          </p>          <p>            Value: {balance.fiatAmount.symbol}            {balance.fiatAmount.value}          </p>          <p>Supply APY: {balance.highestSupplyApy.normalized}</p>        </div>      ))}    </div>  );}

See below some examples of how to use the hook.

import { evmAddress, chainId } from "@aave/react";
const { data, loading, error } = useUserBalances({  user: evmAddress("0x456…"),  filter: {    chains: {      chainIds: [chainId(1)],    },  },});

Sort balances by name or balance value.

import { evmAddress, OrderDirection } from "@aave/react";
// …
const { data, loading, error } = useUserBalances({  user: evmAddress("0x456…"),  filter: {    // your filter criteria  },  orderBy: { balance: OrderDirection.Desc },});

Include tokens with zero balances in the results.

Include Zero Balancesconst { data } = useUserBalances({  user: evmAddress("0x456…"),  filter: {    // your filter criteria  },  includeZeroBalances: true,});

Specify a different currency for displaying fiat amounts.

Custom Currencyimport { evmAddress, Currency } from "@aave/react";
// …
const { data, loading, error } = useUserBalances({  user: evmAddress("0x456…"),  filter: {    // your filter criteria  },  currency: Currency.Eur,});