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

# usePrivateTokenBalances

<Card title="Recommended: JavaScript SDK with React Hooks" icon="react" color="#4779FE">
  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)](/javascript/reference/react-quickstart) to get started.
</Card>

### 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`](/react/reference/hooks/usetokenbalances).

The return shape mirrors [`useTokenBalances`](/react/reference/hooks/usetokenbalances) with an added `supportsPrivateBalances` discriminator, so the two hooks can be composed with minimal call-site changes.

<Note>
  On Aleo, private balances are derived from owned records ("UTXOs") fetched through the wallet iframe. The view key never leaves the iframe.
</Note>

### Usage

```jsx theme={"system"}
import { usePrivateTokenBalances } from "@dynamic-labs/sdk-react-core";

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

```json theme={"system"}
// 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`](/react/reference/hooks/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

```jsx theme={"system"}
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();
```

<Note>
  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.
</Note>

### Composing with `useTokenBalances`

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

```jsx theme={"system"}
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](/react/wallets/using-wallets/aleo/aleo-wallets) — the broader Aleo guide, including the underlying `listOwnedRecords`, `shieldToken`, and `proveTransaction` primitives.
* [`useTokenBalances`](/react/reference/hooks/usetokenbalances) — public token balances on chains where Dynamic supports them.
* [Token Balances reference](/react/reference/token-balances) — caching, rate limiting, and supported chains for public balances.