Fetch Token Balances

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.

Token balances are provided by Zerion and supported across 35+ EVM networks (including Ethereum, Base, Arbitrum, Optimism, Polygon, BNB Chain, and Avalanche) plus Solana. See the full list in the Token Balances reference.

Dynamic supports fetching the top 3000 tokens by market cap.

The Dynamic UI components (DynamicWidget and UserProfile) have a built in UI for displaying multi asset balances, we strongly recommend using those components if you can! Learn more in the Multi-Asset UI section.

Hook

You can fetch token balances for a user’s wallet using the useTokenBalances hook:

React

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

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

Return Value

This hook returns an object for tokenBalances with the following properties:

Property	Type	Description
networkId	integer	The network ID of the token i.e. 1 for Ethereum, 137 for Polygon, etc.
address	string	The address of the token.
name	string	The name of the token.
symbol	string	The symbol of the token.
decimals	integer	The number of decimals the token has.
logoURI	string	The URI of the token’s logo image.
balance	float	The balance of the token in the user’s wallet.
rawBalance	integer	The raw balance of the token in the user’s wallet.
rawBalanceString	string	The raw balance encoded as a base-10 string. Use this when the balance exceeds Number.MAX_SAFE_INTEGER (>= 2^53) to avoid precision loss — e.g. for high-decimal tokens or pre-divisor wei amounts.

Reference

You can find the full reference for the useTokenBalances hook here.

On chains that distinguish a public balance from a private (shielded) one — Aleo today — use the usePrivateTokenBalances hook to render the private balances. It mirrors useTokenBalances and can be called alongside it.

Full Example

React

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

const Balances = () => {
  const { primaryWallet } = useDynamicContext();
  const { tokenBalances, isLoading, isError, error } = useTokenBalances();

  if(!primaryWallet) return <div>No wallet connected</div>;

  if (isLoading) return <div>Loading...</div>;
  if (isError) return <div>Error: {error.message}</div>;

  return (
    <div>
      {tokenBalances.map((token) => (
        <div key={token.address}>
          <img src={token.logoURI} alt={token.symbol} />
          <div>{token.name}</div>
          <div>{token.symbol}</div>
          <div>{token.balance}</div>
        </div>
      ))}
    </div>
  );
};

Using the JavaScript SDK? See Getting Multichain Token Balances for the equivalent guide.