useTokenBalances

Recommended: JavaScript SDK with React Hooks

For new React apps, we recommend the JavaScript SDK with React Hooks (@dynamic-labs-sdk/react-hooks) instead of the legacy React SDK documented here. The JS SDK comes with many benefits such as a much smaller bundle size and other optimizations. Use the React quickstart (JavaScript SDK) to get started.

Summary

Used to fetch the token balances of an account on a specified network. The default behavior is to return the token balances of the primary account on the current network, but optionally the account, network, includeFiat and includeNativeBalance can be specified.

Chain support includes 66 EVM networks, Solana Mainnet and Devnet, Eclipse Mainnet and Bitcoin Ruins. You can checkout the full list here

This will return all tokens with at least 10,000 USD in liquidity unless using filterSpamTokens: false in the hook parameters. This applies to total token liquidity.

Usage

import { useTokenBalances } from "@dynamic-labs/sdk-react-core";

const { tokenBalances, isLoading, isError, error } = useTokenBalances();

// tokenBalances
[
  {
    "networkId": 1,
    "address": "0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0",
    "name": "Polygon",
    "symbol": "MATIC",
    "decimals": 18,
    "logoURI": "https://assets.coingecko.com/coins/images/4713/thumb/polygon.png?1698233745",
    "balance": 0.7851804304793578,
    "rawBalance": 785180430479357800,
    "rawBalanceString": "785180430479357800",
    "price": 0.703229,
    "marketValue": 0.5521616489455683
  },
  {
    "networkId": 1,
    "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "name": "USDC",
    "symbol": "USDC",
    "decimals": 6,
    "logoURI": "https://assets.coingecko.com/coins/images/6319/thumb/usdc.png?1696506694",
    "balance": 50,
    "rawBalance": 50000000,
    "rawBalanceString": "50000000",
    "price": 1,
    "marketValue": 50
  }
]

With arguments

Parameter	Type	Description
networkId	Number	The network ID
chainName	ChainEnum	The chain used
tokenAddresses	String[]	The token addresses
includeFiat	Boolean	Should include Fiat prices
includeNativeBalance	Boolean	Should include native balance
forceRefresh	Boolean	Refreshes the cached balances
filterSpamTokens	Boolean	Defaults to true to filter spam tokens out
whitelistedContracts	String[]	Return these contracts, even when originally filtered

Optionally, you can pass an object with the account address and network id specified. Additionally, you can pass an array of token addresses to filter the results.

import { useTokenBalances } from "@dynamic-labs/sdk-react-core";

const { tokenBalances, isLoading, isError, error } = useTokenBalances({
  networkId: 1,
  accountAddress: "0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0",
  includeFiat: true,
  includeNativeBalance: true,
});

return (
  <ul>
    {tokenBalances?.map((tokenBalance) => (
      <li key={tokenBalance.address}>
        {tokenBalance.name} {tokenBalance.balance} {tokenBalance.symbol} ($
        {tokenBalance.price}) | ${tokenBalance.marketValue}
      </li>
    ))}
  </ul>
);

Refresh token balances after a transaction

import { useTokenBalances } from "@dynamic-labs/sdk-react-core";
import { ChainEnum } from "@dynamic-labs/sdk-api-core";

const { fetchAccountBalances, tokenBalances, isLoading, isError, error } = useTokenBalances({
  chainName: ChainEnum.Evm,
  accountAddress: address,
  includeFiat: true,
  includeNativeBalance: true,
});

// send transaction
const txHash = await sendTransaction({...});
// wait for transaction receipt
await publicClient.waitForTransactionReceipt(txHash);
// refresh token balances once the transaction receipt has resolved
fetchAccountBalances(true);

// with token addresses filter
import { useTokenBalances } from "@dynamic-labs/sdk-react-core";

const { tokenBalances, isLoading, isError, error } = useTokenBalances({
  networkId: 1,
  accountAddress: "0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0",
  tokenAddresses: ["0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0"],
});

Solana support with Fiat prices (with SDK version 2.2.9)

import { useTokenBalances } from "@dynamic-labs/sdk-react-core";
import { ChainEnum } from "@dynamic-labs/sdk-api";

const { tokenBalances, isLoading, isError, error } = useTokenBalances({
  chainName: ChainEnum.Sol,
  accountAddress: address,
  includeFiat: true,
  includeNativeBalance: true,
});