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

# Balances

# Balance Management

This guide covers querying and displaying token balances using the Privacy Boost React SDK.

## Basic Usage

```tsx theme={null}
import { useBalances } from '@sunnyside-io/privacy-boost-react';

function BalanceDisplay() {
  const { balances, loading } = useBalances();

  if (loading) return <div>Loading balances...</div>;

  return (
    <ul>
      {balances.map((balance) => (
        <li key={balance.tokenAddress}>
          {balance.symbol}: {balance.formattedShielded} (shielded)
        </li>
      ))}
    </ul>
  );
}
```

## useBalances Return Value

| Property             | Type                                 | Description                               |
| -------------------- | ------------------------------------ | ----------------------------------------- |
| `balances`           | `FormattedBalance[]`                 | All token balances with formatted strings |
| `loading`            | `boolean`                            | Whether balances are loading              |
| `lastSynced`         | `number \| null`                     | Timestamp of last sync                    |
| `getBalance`         | `(tokenAddress) => FormattedBalance` | Get balance for a specific token          |
| `getShieldedBalance` | `(tokenAddress) => bigint`           | Get raw shielded balance                  |
| `getWalletBalance`   | `(tokenAddress) => bigint`           | Get raw wallet balance                    |
| `totalShielded`      | `bigint`                             | Total shielded balance across all tokens  |
| `tokenCount`         | `number`                             | Number of tokens with balances            |

## Balance Types

```typescript theme={null}
interface FormattedBalance {
  tokenAddress: Hex;
  shielded: bigint;
  wallet: bigint;
  symbol?: string;
  decimals?: number;
  formattedShielded: string;
  formattedWallet: string;
}
```

## Refreshing Balances

```tsx theme={null}
import { useVault, useBalances } from '@sunnyside-io/privacy-boost-react';

function SyncButton() {
  const { refreshBalances } = useVault();
  const [syncing, setSyncing] = useState(false);

  const handleSync = async () => {
    setSyncing(true);
    await refreshBalances();
    setSyncing(false);
  };

  return (
    <button onClick={handleSync} disabled={syncing}>
      {syncing ? 'Refreshing...' : 'Refresh Balances'}
    </button>
  );
}
```

## Complete Example

```tsx theme={null}
import { useBalances, useVault } from '@sunnyside-io/privacy-boost-react';

function BalanceList() {
  const { balances, loading, lastSynced, tokenCount } = useBalances();
  const { refreshBalances } = useVault();
  const [syncing, setSyncing] = useState(false);

  const handleRefresh = async () => {
    setSyncing(true);
    await refreshBalances();
    setSyncing(false);
  };

  return (
    <div>
      <div className="header">
        <h3>Balances ({tokenCount} tokens)</h3>
        <button onClick={handleRefresh} disabled={syncing}>
          {syncing ? 'Refreshing...' : 'Refresh'}
        </button>
      </div>

      {lastSynced && (
        <small>Last synced: {new Date(lastSynced).toLocaleTimeString()}</small>
      )}

      {loading ? (
        <div>Loading...</div>
      ) : (
        <table>
          <thead>
            <tr>
              <th>Token</th>
              <th>Shielded</th>
              <th>Wallet</th>
            </tr>
          </thead>
          <tbody>
            {balances.map((balance) => (
              <tr key={balance.tokenAddress}>
                <td>{balance.symbol}</td>
                <td>{balance.formattedShielded}</td>
                <td>{balance.formattedWallet}</td>
              </tr>
            ))}
          </tbody>
        </table>
      )}
    </div>
  );
}
```

## Best Practices

### 1. Use Formatted Values for Display

The `formattedShielded` and `formattedWallet` strings are already human-readable. Use them directly instead of manually formatting.

### 2. Refresh After Operations

Always sync balances after deposits, withdrawals, or transfers.

### 3. Show Loading States

Balance syncing requires network calls. Always show a loading indicator.

## Next Steps

* [Deposits Guide](./deposits)
* [Withdrawals Guide](./withdrawals)
* [Transactions Guide](./transactions)
* [Error Handling](./error-handling)