> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dynamic.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://docs.dynamic.xyz/docs/javascript/reference/client/create-dynamic-client.md), [Initializing the Dynamic client](https://docs.dynamic.xyz/docs/javascript/reference/client/initialize-dynamic-client.md)), have a connected wallet to read from (see [Connecting external wallets](https://docs.dynamic.xyz/docs/javascript/building-ui/connecting-external-wallets.md)), and know which wallet you'll show balances for (see [Connected wallets management](https://docs.dynamic.xyz/docs/javascript/building-ui/connected-wallets-management.md)).

## 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).

> [tab] TypeScript
>
> ```typescript theme={"system"}
> 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';
> }
> ```

> [tab] React
>
> ```tsx theme={"system"}
> 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.

> [tab] TypeScript
>
> ```typescript theme={"system"}
> 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);
>   }
> }
> ```

> [tab] React
>
> ```tsx theme={"system"}
> 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>
>   );
> }
> ```

> [!NOTE]
>
> `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. |

> [!TIP]
>
> 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](https://docs.dynamic.xyz/docs/javascript/building-ui/connected-wallets-management.md) — pick which wallet to show balances for
* [Transaction confirmation & simulation](https://docs.dynamic.xyz/docs/javascript/building-ui/transaction-confirmation.md) — spend the balance you display
* [Network switching & validation](https://docs.dynamic.xyz/docs/javascript/building-ui/network-switching.md) — balances are per network


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.