Token balances & display

Show a wallet’s native balance and its token holdings — with prices, market values, and spam filtering.

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

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';
}

React

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

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);
  }
}

React

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.

See also

• Connected wallets management — pick which wallet to show balances for
• Transaction confirmation & simulation — spend the balance you display
• Network switching & validation — balances are per network