From 0c100b6a841c22c0da701e772f09096cea1a6620 Mon Sep 17 00:00:00 2001
From: codexhange <304653718+codexhange@users.noreply.github.com>
Date: Sun, 30 Aug 2026 01:11:18 +0200
Subject: [PATCH] feat(react): add useWalletBalance query hook
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a TanStack Query hook for reading a wallet's live on-chain balance,
disabled when walletId is empty with a 15s stale-time default.

Closes #129

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
---
 packages/react/src/index.ts | 38 +++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/packages/react/src/index.ts b/packages/react/src/index.ts
index 0750e43..162357b 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';
@@ -247,6 +248,43 @@ export function useWallet(
   });
 }
 
+/**
+ * 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.
  *