Getting Token Balances

Retrieve token balances for a wallet account on one chain (one or more networks).

For most apps, prefer getMultichainTokenBalances — it batches token balances across chains, networks, and addresses in a single call. Reach for getTokenBalances only when you have one wallet on one chain (still fine across multiple networks of that chain) and want a simpler call shape.

You can get the token balances for a wallet account by calling the getTokenBalances function. This returns native and token balances for a single chain (one or more networks of that chain), unlike getMultichainTokenBalances which queries across multiple chains in one call.

If you only need the native token balance, use getNativeBalance instead.

Usage

import { getTokenBalances } from '@dynamic-labs-sdk/client';

const balances = await getTokenBalances({ walletAccount });

With options

import { getTokenBalances } from '@dynamic-labs-sdk/client';

const balances = await getTokenBalances({
  walletAccount,
  networkId: 137,
  includePrices: true,
  includeNative: true,
  filterSpamTokens: true,
  forceRefresh: true,
  whitelistedContracts: ['0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174'],
});

Parameters

Parameter	Type	Required	Description
walletAccount	WalletAccount	Yes	The wallet account to get the balances for
networkId	number	No	The network ID to query. Defaults to the active network
includePrices	boolean	No	Include token prices in the response
includeNative	boolean	No	Include the native token balance
filterSpamTokens	boolean	No	Filter out spam tokens (default: true)
forceRefresh	boolean	No	Force a refresh instead of using cached values
whitelistedContracts	string[]	No	Only return balances for these contract addresses

React

useGetTokenBalances stays disabled until walletAccount is defined, then re-fetches when it changes:

import { useGetTokenBalances } from '@dynamic-labs-sdk/react-hooks';

function TokenBalances({ walletAccount }) {
  const { data: tokenBalances } = useGetTokenBalances({ walletAccount, includePrices: true });

  return (
    <ul>
      {tokenBalances?.map((token) => (
        <li key={token.address ?? 'native'}>
          {token.symbol}: {token.balance}
        </li>
      ))}
    </ul>
  );
}

Response

Returns a Promise<TokenBalance[]> — an array of token balance objects.

Related functions

• Getting Multichain Token Balances - Recommended default for token balances across chains
• Getting Native Balance - Native gas balance only
• Getting the Wallet Account Given an Address and Chain
• Getting Active Network