Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.dynamic.xyz/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
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

PropertyTypeDescription
tokenBalancesTokenBalance[]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.
isLoadingbooleantrue while the initial fetch (or a refetch()) is in flight.
errorstring | undefinedThe 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.
supportsPrivateBalancesbooleantrue 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.