usePrivateTokenBalances

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

Fetches the private (shielded) token balances held by the primary wallet, for chains that distinguish a public balance from a private one. Today the only such chain in the SDK is Aleo; on every other chain the hook returns an empty list with supportsPrivateBalances: false, so application code can call it unconditionally alongside useTokenBalances.

The return shape mirrors useTokenBalances with an added supportsPrivateBalances discriminator, so the two hooks can be composed with minimal call-site changes.

On Aleo, private balances are derived from owned records (“UTXOs”) fetched through the wallet iframe. The view key never leaves the iframe.

Usage

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

const {
  tokenBalances,
  isLoading,
  error,
  refetch,
  supportsPrivateBalances,
} = usePrivateTokenBalances();

// tokenBalances (Aleo example — credits + a stablecoin record)
[
  {
    "address": "credits.aleo",
    "name": "Aleo Credits",
    "symbol": "ALEO",
    "decimals": 6,
    "isNative": true,
    "logoURI": "https://app.dynamic.xyz/assets/networks/aleo.svg",
    "balance": 12.5,
    "rawBalance": 12500000,
    "rawBalanceString": "12500000",
    "price": 0.42,
    "marketValue": 5.25
  },
  {
    "address": "usad.aleo",
    "name": "USAD",
    "symbol": "USAD",
    "decimals": 6,
    "isNative": false,
    "logoURI": "https://app.dynamic.xyz/assets/tokens/usad.svg",
    "balance": 100,
    "rawBalance": 100000000,
    "rawBalanceString": "100000000",
    "price": 1,
    "marketValue": 100
  }
]

Return value

Property	Type	Description
tokenBalances	TokenBalance[]	One entry per token aggregated across all owned private records on the active wallet’s network. Zero-balance entries are filtered out. Same shape as useTokenBalances, including rawBalanceString for precision-safe encoding.
isLoading	boolean	true while the initial fetch (or a refetch()) is in flight.
error	string | undefined	The message of the last error from the underlying fetch, if any.
refetch	() => Promise<void>	Force-refresh both credits and stablecoin / ARC-21 balances in parallel. Useful after a transaction that changes shielded state.
supportsPrivateBalances	boolean	true when the active wallet’s chain supports private balances and the connector exposes the methods needed to enumerate them. For Aleo this requires a WaaS connector with listOwnedRecords — external Aleo wallets typically don’t expose this and return false.

Refreshing after a transaction

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

const { tokenBalances, refetch } = usePrivateTokenBalances();

// dispatch a shield, send, or any operation that changes shielded state…
await primaryWallet.shieldToken({
  tokenAddress: "credits.aleo",
  isNative: true,
  amount: 1_000_000n,
});

// …then refresh.
await refetch();

On Aleo the SDK applies an optimistic update to both the public and private balances the moment shieldToken resolves, so the UI reacts immediately without waiting for the indexer to surface the new record. A subsequent refetch() reconciles with the server once the record is indexed.

Composing with useTokenBalances

Application code can call both hooks unconditionally and let the chain support flags decide which sections to render:

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

const Balances = () => {
  const { tokenBalances: publicBalances } = useTokenBalances();
  const {
    tokenBalances: privateBalances,
    supportsPrivateBalances,
  } = usePrivateTokenBalances();

  return (
    <>
      <h2>Public</h2>
      {publicBalances?.map((t) => (
        <div key={t.address}>{t.symbol}: {t.balance}</div>
      ))}

      {supportsPrivateBalances && (
        <>
          <h2>Private</h2>
          {privateBalances.map((t) => (
            <div key={t.address}>{t.symbol}: {t.balance}</div>
          ))}
        </>
      )}
    </>
  );
};

See also

• Using Aleo wallets — the broader Aleo guide, including the underlying listOwnedRecords, shieldToken, and proveTransaction primitives.
• useTokenBalances — public token balances on chains where Dynamic supports them.
• Token Balances reference — caching, rate limiting, and supported chains for public balances.