Token balances & display

Prerequisites

Before this page: create and initialize a Dynamic client (see Creating a Dynamic client, Initializing the Dynamic client), have a connected wallet to read from (see Connecting external wallets), and know which wallet you’ll show balances for (see Connected wallets management).

What you’ll build

Two views most apps need:

Native balance — how much of the chain’s native asset (ETH, SOL, …) the wallet holds.
Token list — every token the wallet holds, optionally with USD prices and market values, and with spam tokens filtered out.

Both read from a WalletAccount that your app supplies — the wallet it’s currently acting on.

Native balance

getNativeBalance returns { balance } where balance is a human-readable string (or null while it’s unavailable).

TypeScript
React

import {
  getNativeBalance,
  type WalletAccount,
} from '@dynamic-labs-sdk/client';

async function renderNativeBalance(
  element: HTMLElement,
  walletAccount: WalletAccount,
) {
  const { balance } = await getNativeBalance({ walletAccount });
  element.textContent = balance ?? 'Unavailable';
}

import { type WalletAccount } from '@dynamic-labs-sdk/client';
import { useGetNativeBalance } from '@dynamic-labs-sdk/react-hooks';

function NativeBalance({ walletAccount }: { walletAccount: WalletAccount }) {
  const { data, isLoading } = useGetNativeBalance({ walletAccount });

  if (isLoading) return <span>Loading…</span>;
  return <span>{data?.balance ?? 'Unavailable'}</span>;
}

The query refetches automatically when the wallet’s network changes, so the balance stays in sync.

Token holdings

getTokenBalances returns one TokenBalance per token, with symbol, name, logoURI, decimals, a human-readable balance, and (when you opt in) price and marketValue. Pass includePrices for USD figures and filterSpamTokens to drop junk tokens.

TypeScript
React

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

async function renderTokens(
  list: HTMLUListElement,
  walletAccount: WalletAccount,
) {
  const tokens = await getTokenBalances({
    walletAccount,
    includePrices: true,
    filterSpamTokens: true,
  });

  list.replaceChildren();
  for (const token of tokens) {
    const item = document.createElement('li');

    const icon = document.createElement('img');
    icon.src = token.logoURI;
    icon.alt = '';
    icon.width = 20;

    const value =
      token.marketValue !== undefined ? ` · $${token.marketValue.toFixed(2)}` : '';
    item.append(
      icon,
      document.createTextNode(`${token.balance} ${token.symbol}${value}`),
    );
    list.append(item);
  }
}

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

function TokenList({ walletAccount }: { walletAccount: WalletAccount }) {
  const { data: tokens = [], isLoading } = useGetTokenBalances({
    walletAccount,
    includePrices: true,
    filterSpamTokens: true,
  });

  if (isLoading) return <p>Loading balances…</p>;

  return (
    <ul>
      {tokens.map((token) => (
        <li key={`${token.networkId}-${token.address}`}>
          <img src={token.logoURI} alt="" width={20} />
          <span>{token.balance} {token.symbol}</span>
          {token.marketValue !== undefined ? (
            <span>${token.marketValue.toFixed(2)}</span>
          ) : null}
        </li>
      ))}
    </ul>
  );
}

balance is already scaled by the token’s decimals for display. When you need the exact integer amount (for a transfer, say), use rawBalanceString — it preserves full precision that a JavaScript number can lose.

Options worth knowing

Option	Effect
`includePrices`	Adds `price` and `marketValue` (USD) to each token.
`filterSpamTokens`	Drops tokens flagged as spam — recommended for user-facing lists.
`includeNative`	Includes the native asset as an entry in the token list.
`networkIds`	Fetch balances across several networks at once (multichain).
`forceRefresh`	Bypass any cached result and refetch.

For a portfolio across chains, pass networkIds (or use getMultichainTokenBalances) instead of calling per network — one request returns every network’s holdings.

Handling errors

Situation	What to do
`balance` is `null`	Treat as “unavailable” and show a placeholder; the fetch may still be resolving or the network RPC may be down.
Request rejects	Keep the last known balances and offer a retry rather than clearing the UI.
Empty token list	The wallet holds nothing on the queried network(s) — show an empty state.

Installation & Configuration

Building UI

Chains & Networks

Authenticate

User & Session Management

Wallets

Flow

Swaps

Funding & Onramp

Events

Token balances & display

Prerequisites

What you’ll build

Native balance

Token holdings

Options worth knowing

Handling errors

See also

​Prerequisites

​What you’ll build

​Native balance

​Token holdings

​Options worth knowing

​Handling errors

​See also

Prerequisites

What you’ll build

Native balance

Token holdings

Options worth knowing

Handling errors

See also