diff --git a/packages/react/src/index.ts b/packages/react/src/index.ts
index 2541172..b723b18 100644
--- a/packages/react/src/index.ts
+++ b/packages/react/src/index.ts
@@ -72,6 +72,7 @@ import type {
   TransactionListParams,
   TransferInput,
   Wallet,
+  WalletBalance,
   WebhookEventEnvelope,
   WebhookEventName,
 } from '@astroid/types';
@@ -238,9 +239,54 @@ export function useWallet(
 }
 
 /**
- * List agents.
- * @param params  Filter params.
- * @param options Custom query options (`queryKey`, `staleTime`, `refetchInterval`, `gcTime`, etc.).
+ * Fetch the live on-chain balance of a single wallet, with a sensible
+ * stale-time default so balances stay fresh without hammering the API.
+ *
+ * The query is automatically **disabled** when `walletId` is `undefined` or
+ * empty. Balances are inherently volatile, so by default the result is marked
+ * stale after 15s; pass `options.staleTime` to tune, or set
+ * `refetchInterval` (e.g. `30_000`) to poll while mounted.
+ *
+ * @param walletId The wallet to read balances for. Pass `undefined` to skip.
+ * @param options  Extra TanStack Query options (`enabled`, `staleTime`,
+ *                 `refetchInterval`, etc.). The `queryKey`/`queryFn` are set
+ *                 internally and cannot be overridden.
+ * @returns       A TanStack Query result with `data` (a {@link WalletBalance}),
+ *                `isLoading`, `isError`, `error`, etc.
+ *
+ * @example
+ * ```tsx
+ * const { data: balance, isStale } = useWalletBalance(activeWalletId, {
+ *   refetchInterval: 30_000,
+ * });
+ * ```
+ */
+export function useWalletBalance(
+  walletId: string | undefined,
+  options?: ReadOptions<WalletBalance>,
+): UseQueryResult<WalletBalance, Error> {
+  const astroid = useAstroid();
+  return useQuery({
+    queryKey: queryKeys.wallets.balance(walletId ?? ''),
+    queryFn: () => astroid.wallets.balance(walletId as string),
+    enabled: Boolean(walletId) && options?.enabled !== false,
+    staleTime: 15_000, // balances go stale quickly; refresh on refocus/interval
+    ...options,
+  });
+}
+
+/**
+ * Fetch a paginated list of AI agents.
+ *
+ * @param params  Optional filters: `page`, `pageSize`, `walletId`, etc.
+ * @param options Extra TanStack Query options.
+ * @returns       A TanStack Query result with `data` (a {@link Paginated} of
+ *                {@link Agent}), `isLoading`, `isError`, `error`, etc.
+ *
+ * @example
+ * ```tsx
+ * const { data } = useAgents({ walletId: 'wal_123' });
+ * ```
  */
 export function useAgents(
   params?: AgentListParams,