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

# React hooks

> Read balances, submit transactions, and switch networks.

## Read hooks

Query hooks return React Query results (`data`, `error`, `isFetching`, `isError`, `refetch`). Use `isFetching` for network spinners; disabled queries can be pending without fetching.

| Hook                                     | Arguments                                     | Data                             | Auto-enabled?                             |
| ---------------------------------------- | --------------------------------------------- | -------------------------------- | ----------------------------------------- |
| `useCToken()`                            | None                                          | `CTokenClient`                   | Context access; throws outside provider.  |
| `useTokens()`                            | None                                          | `TokenConfig[]`                  | Context access.                           |
| `useResolvedTokens()`                    | Optional token list and single-token shortcut | Enriched `TokenConfig[]`         | Context access, no network.               |
| `usePublicBalance(token, options?)`      | `{ enabled? }`                                | `number`                         | Yes when wallet owner exists.             |
| `usePublicBalanceExact(token, options?)` | `{ enabled? }`                                | `ExactBalance`                   | Yes when wallet owner exists.             |
| `usePublicBalances(tokens, options?)`    | `{ enabled? }`                                | `Record<Address, number>`        | Yes with owner and nonempty list.         |
| `useBalance(token, options?)`            | `{ enabled? }`                                | `number`                         | No; enable or refetch intentionally.      |
| `useBalanceExact(token, options?)`       | `{ enabled? }`                                | `ExactBalance`                   | No; enable or refetch intentionally.      |
| `useBalances(tokens, options?)`          | `{ enabled? }`                                | `Record<Address, number>`        | No.                                       |
| `useBalancesSettled(tokens, options?)`   | `{ enabled? }`                                | `Record<Address, BalanceResult>` | No.                                       |
| `useHistory(args?, options?)`            | `HistoryArgs`, `ReadOptions`                  | `TxPage`                         | No; needs an explicit or connected owner. |
| `useAssets(args?, options?)`             | `AssetsArgs`, `ReadOptions`                   | `Asset[]`                        | No; needs an explicit or connected owner. |

Confidential queries disable automatic retry and focus/reconnect refetching; stale time is 15 seconds. Public queries inherit host policies. History/assets retry through the core HTTP layer.

`ReadOptions` applies to history/assets: `enabled?`, `refetchInterval?` (ms), `keepPreviousData?` (same-owner page transitions). Hooks supply React Query’s cancellation signal.

```tsx theme={null}
function BalanceAndActivity({ token }: { token: Address }) {
  const [revealed, setRevealed] = useState(false);
  const balance = useBalanceExact(token, { enabled: revealed });
  const history = useHistory({ limit: 10 }, { enabled: true });
  return (
    <div>
      <button onClick={() => setRevealed(true)}>Reveal</button>
      <p>{balance.error ? humanizeError(balance.error) : balance.data?.formatted ?? "••••"}</p>
      <p>{history.data?.total ?? "—"} transactions</p>
    </div>
  );
}
```

Import the referenced hooks, types, and helpers; render under [React providers](/ctoken/react).

## Mutation hooks

| Hook                            | `mutate` / `mutateAsync` input | Success data               |
| ------------------------------- | ------------------------------ | -------------------------- |
| `useDeposit(options?)`          | `DepositArgs`                  | `{ hash, amount: bigint }` |
| `useApprove(options?)`          | `ApproveArgs`                  | `{ hash }`                 |
| `useConfidentialSend(options?)` | `SendArgs`                     | `{ hash }`                 |
| `useWithdraw(options?)`         | `WithdrawArgs`                 | `{ hash, amount: bigint }` |
| `useDecrypt()`                  | `DecryptArgs`                  | `number`                   |

`WriteOptions<TData, TVars>`: `onSuccess(data, variables)?`, `onError(error, variables)?`. Transaction hooks invalidate client queries on success. `useDecrypt()` supports per-call callbacks only. Disable automatic retries for signing mutations in your QueryClient.

```tsx theme={null}
const deposit = useDeposit({
  onSuccess: ({ hash }) => console.log("Confirmed:", hash),
  onError: (error) => console.error(humanizeError(error)),
});

<button
  disabled={deposit.isPending}
  onClick={() => deposit.mutate({ token: USDC, amount: "1" })}
>
  {deposit.isPending ? "Shielding…" : "Shield 1 USDC"}
</button>
```

## Network guard

```tsx theme={null}
const guard = useChainGuard();
if (guard.wrongNetwork) {
  return (
    <button disabled={guard.switching} onClick={guard.switchNetwork}>
      Switch to {guard.chainName}
    </button>
  );
}
```

`ChainGuard` exposes `wrongNetwork`, `chainId`, `chainName`, `switching`, and `switchNetwork()`. Switching does not submit a transaction.