@b3dotfun/sdk 0.1.70-alpha.18 → 0.1.70-alpha.19

package/src/global-account/react/components/ManageAccount/ContentTokens.tsx

@@ -5,7 +5,7 @@ import {
   toast,
   TransitionPanel,
   useAnalytics,
-  useSimBalance,
+  usePortfolioBalance,
   useUnifiedChainSwitchAndExecute,
 } from "@b3dotfun/sdk/global-account/react";
 import { formatDisplayNumber, formatTokenAmount } from "@b3dotfun/sdk/shared/utils/number";
@@ -16,7 +16,7 @@ import { NumericFormat } from "react-number-format";
 
 import { useActiveAccount } from "thirdweb/react";
 import { encodeFunctionData, erc20Abi, isAddress, parseUnits } from "viem";
-import { SimBalanceItem } from "../../hooks/useSimBalance";
+import type { B3TokenBalance } from "@b3dotfun/sdk/shared/utils/zerionPositions";
 
 // Panel view enum for managing navigation between token list and send form
 enum TokenPanelView {
@@ -45,7 +45,7 @@ export function ContentTokens({ activeTab }: ContentTokensProps) {
   const [tokenPanelView, setTokenPanelView] = useState<TokenPanelView>(TokenPanelView.LIST);
 
   // === SEND FORM STATE ===
-  const [selectedToken, setSelectedToken] = useState<SimBalanceItem | null>(null);
+  const [selectedToken, setSelectedToken] = useState<B3TokenBalance | null>(null);
   const [recipientAddress, setRecipientAddress] = useState("");
   const [sendAmount, setSendAmount] = useState("");
   const [isSending, setIsSending] = useState(false);
@@ -58,7 +58,12 @@ export function ContentTokens({ activeTab }: ContentTokensProps) {
 
   // === DATA FETCHING ===
   const account = useActiveAccount();
-  const { data: simBalance, refetch: refetchSimBalance, isLoading: isLoadingBalance } = useSimBalance(account?.address);
+  const {
+    data: balances,
+    refetch: refetchBalances,
+    isLoading: isLoadingBalance,
+    isError: isBalanceError,
+  } = usePortfolioBalance(account?.address);
 
   // === BLOCKCHAIN INTERACTION ===
   const { switchChainAndExecute } = useUnifiedChainSwitchAndExecute();
@@ -96,14 +101,14 @@ export function ContentTokens({ activeTab }: ContentTokensProps) {
   // === HELPER FUNCTION ===
   // Get current version of selected token from fresh balance data
   // 🔧 FIX: Prevents auto-navigation back to token list when balance refreshes
-  // The useSimBalance hook refreshes data, creating new token object references
+  // The balance hook refreshes data, creating new token object references
   // This helper ensures we always get the fresh token data instead of stale references
-  const getCurrentSelectedToken = (): SimBalanceItem | null => {
-    if (!selectedToken || !simBalance?.balances) {
+  const getCurrentSelectedToken = (): B3TokenBalance | null => {
+    if (!selectedToken || !balances) {
       return null;
     }
 
-    const found = simBalance.balances.find(
+    const found = balances.find(
       token => token.chain_id === selectedToken.chain_id && token.address === selectedToken.address,
     );
 
@@ -184,11 +189,16 @@ export function ContentTokens({ activeTab }: ContentTokensProps) {
           args: [recipientAddress, amountInWei],
         });
 
-        const tx = await switchChainAndExecute(displayToken.chain_id, {
-          to: displayToken.address === "native" ? recipientAddress : displayToken.address,
-          data: sendTokenData,
-          value: displayToken.address === "native" ? amountInWei : BigInt(0),
-        });
+        // A native send carries value and no calldata; an ERC-20 send carries calldata and no
+        // value. Branch on the explicit flag, never on the address: the native sentinel is a
+        // display detail, and taking the ERC-20 path for a native coin spends gas without moving
+        // anything.
+        const tx = await switchChainAndExecute(
+          displayToken.chain_id,
+          displayToken.is_native
+            ? { to: recipientAddress, value: amountInWei }
+            : { to: displayToken.address, data: sendTokenData, value: BigInt(0) },
+        );
 
         if (tx) {
           // Track successful send
@@ -215,7 +225,7 @@ export function ContentTokens({ activeTab }: ContentTokensProps) {
         // Wait 1 second to make sure the tx is indexed on sim api.
         setTimeout(async () => {
           // Force refetch to bypass cache and get fresh balance data
-          await refetchSimBalance();
+          await refetchBalances();
         }, 1000);
         setIsSending(false);
       }
@@ -409,8 +419,28 @@ export function ContentTokens({ activeTab }: ContentTokensProps) {
       return <LoadingIndicator />;
     }
 
-    // Show empty state when no account or no balance data
-    if (!account?.address || !simBalance) {
+    // A wallet IS connected here — only the read failed. Prompting the user to connect would send
+    // them to fix something that is not broken.
+    // `isBalanceError` as well as the absent list: after a first success a later refetch failure
+    // keeps `data` populated, so `!balances` alone would show stale numbers as if they were fresh.
+    if (account?.address && (isBalanceError || !balances)) {
+      return (
+        <div className="flex flex-col items-center justify-center py-12 text-center">
+          <div className="bg-b3-line/50 mb-4 rounded-full p-4">
+            <Loader2 className="text-b3-foreground-muted h-8 w-8" />
+          </div>
+          <h3 className="text-b3-grey font-neue-montreal-semibold mb-2">Couldn&apos;t load your tokens</h3>
+          <button
+            onClick={() => refetchBalances()}
+            className="text-b3-foreground-muted font-neue-montreal-medium text-sm underline"
+          >
+            Try again
+          </button>
+        </div>
+      );
+    }
+
+    if (!account?.address) {
       return (
         <div className="flex flex-col items-center justify-center py-12 text-center">
           <div className="bg-b3-line/50 mb-4 rounded-full p-4">
@@ -426,8 +456,7 @@ export function ContentTokens({ activeTab }: ContentTokensProps) {
 
     // === SMART FILTERING LOGIC ===
     // Filter tokens with value >= $1 to reduce noise from dust tokens
-    const filteredTokens =
-      simBalance?.balances.filter(token => token.value_usd !== undefined && token.value_usd >= 1) || [];
+    const filteredTokens = balances?.filter(token => token.value_usd !== undefined && token.value_usd >= 1) || [];
 
     // 🧠 INTELLIGENT DISPLAY LOGIC:
     // Show all tokens automatically when filtering would be unhelpful:
@@ -435,11 +464,11 @@ export function ContentTokens({ activeTab }: ContentTokensProps) {
     // 2. No tokens with value >= $1 (user has only dust), OR
     // 3. 5 or fewer tokens with value >= $1 (not enough to warrant filtering)
     const shouldShowAllTokens = showAllTokens || filteredTokens.length === 0 || filteredTokens.length <= 5;
-    const tokensToShow = shouldShowAllTokens ? simBalance?.balances || [] : filteredTokens;
-    const hasHiddenTokens = !shouldShowAllTokens && (simBalance?.balances.length || 0) > filteredTokens.length;
+    const tokensToShow = shouldShowAllTokens ? balances || [] : filteredTokens;
+    const hasHiddenTokens = !shouldShowAllTokens && (balances?.length || 0) > filteredTokens.length;
 
     // Handle token selection and navigate to send form
-    const handleTokenClick = (token: SimBalanceItem) => {
+    const handleTokenClick = (token: B3TokenBalance) => {
       setSelectedToken(token);
       animationDirection.current = "forward"; // Set animation direction BEFORE state change
       setTokenPanelView(TokenPanelView.SEND);

package/src/global-account/react/components/ManageAccount/NFTContent.tsx

@@ -1,6 +1,6 @@
 import { useActiveWallet } from "thirdweb/react";
 import { AccountAssets } from "..";
-import { useSimCollectibles } from "../../hooks";
+import { usePortfolioCollectibles } from "../../hooks";
 
 const NFTContent = () => {
   // Get active wallet state
@@ -8,11 +8,13 @@ const NFTContent = () => {
   const activeAccount = activeWallet?.getAccount();
   const activeAddress = activeAccount?.address;
 
-  const { data: nfts, isLoading } = useSimCollectibles(activeAddress, [1, 8453], { filterSpam: true });
+  const { data: nfts, isLoading, isError } = usePortfolioCollectibles(activeAddress, [1, 8453], { filterSpam: true });
 
   return (
     <div style={{ minHeight: "100px" }}>
-      {nfts ? (
+      {isError ? (
+        <div className="py-12 text-center text-gray-500">Couldn&apos;t load your NFTs</div>
+      ) : nfts ? (
         <AccountAssets nfts={nfts} isLoading={isLoading} />
       ) : (
         <div className="py-12 text-center text-gray-500">No NFTs found</div>

package/src/global-account/react/components/ManageAccount/ProfileSection.tsx

@@ -3,7 +3,7 @@ import {
   useB3Config,
   useModalStore,
   useProfile,
-  useSimBalance,
+  usePortfolioBalance,
   useUser,
 } from "@b3dotfun/sdk/global-account/react";
 import { validateImageUrl } from "@b3dotfun/sdk/global-account/react/utils/profileDisplay";
@@ -32,14 +32,16 @@ const ProfileSection = () => {
   const setB3ModalContentType = useModalStore(state => state.setB3ModalContentType);
   const navigateBack = useModalStore(state => state.navigateBack);
 
-  const { data: simBalance } = useSimBalance(smartWalletAddress);
+  const { data: balances, isError: isBalanceError } = usePortfolioBalance(smartWalletAddress);
   const [imgError, setImgError] = useState(false);
   const handleImgError = useCallback(() => setImgError(true), []);
 
+  // Null while the holdings are unknown. Summing an absent list to $0.00 would report an empty
+  // portfolio to someone whose balances merely failed to load.
   const totalBalanceUsd = useMemo(() => {
-    if (!simBalance?.balances) return 0;
-    return simBalance.balances.reduce((sum, token) => sum + (token.value_usd || 0), 0);
-  }, [simBalance]);
+    if (isBalanceError || !balances) return null;
+    return balances.reduce((sum, token) => sum + (token.value_usd || 0), 0);
+  }, [balances, isBalanceError]);
 
   const handleEditAvatar = () => {
     setB3ModalOpen(true);
@@ -92,7 +94,9 @@ const ProfileSection = () => {
           {!isBetterAuth && (
             <h2 className="text-b3-grey font-neue-montreal-semibold flex h-[38px] items-center gap-1 text-xl">
               <div className="text-b3-foreground-muted"> $</div>
-              <div className="text-[30px]">{formatDisplayNumber(totalBalanceUsd, { fractionDigits: 2 })}</div>
+              <div className="text-[30px]">
+                {totalBalanceUsd === null ? "—" : formatDisplayNumber(totalBalanceUsd, { fractionDigits: 2 })}
+              </div>
             </h2>
           )}
           <div className="b3-modal-username font-neue-montreal-semibold text-base leading-none text-[#0B57C2]">

package/src/global-account/react/components/ManageAccount/TokenContent.tsx

@@ -1,10 +1,16 @@
-import { useSimBalance } from "@b3dotfun/sdk/global-account/react";
+import { usePortfolioBalance } from "@b3dotfun/sdk/global-account/react";
 import { getChainLogo } from "@b3dotfun/sdk/shared/constants/chains/supported";
 import { useActiveWallet } from "thirdweb/react";
 import { TokenBalanceRow } from "./TokenBalanceRow";
 
-// Chain logo URLs mapping
-const CHAIN_LOGOS: Record<number, string> = [1, 8453, 8333].map(chainId => getChainLogo(chainId));
+const ETHEREUM_CHAIN_ID = 1;
+
+// Chain logo URLs, keyed by chain id. Built with Object.fromEntries rather than `.map()`: an array
+// satisfies Record<number, string> for the type checker while indexing by 0,1,2 at runtime, so
+// every lookup by a real chain id would miss.
+const CHAIN_LOGOS: Record<number, string> = Object.fromEntries(
+  [ETHEREUM_CHAIN_ID, 8453, 8333].map(chainId => [chainId, getChainLogo(chainId)]),
+);
 
 const TokenContent = () => {
   // Get active wallet state
@@ -12,19 +18,26 @@ const TokenContent = () => {
   const activeAccount = activeWallet?.getAccount();
   const activeAddress = activeAccount?.address;
 
-  const { data: simBalance } = useSimBalance(activeAddress, [8453, 8333, 1]);
-  console.log("simBalance :", simBalance);
+  // Base and Ethereum only. B3 (8333) is deliberately absent: the portfolio provider does not index
+  // it, so asking for it returns nothing and reads as a coverage gap rather than a choice. Restoring
+  // B3 needs a non-provider source, the way HyperEVM and Plume are served on-chain in b3os-web.
+  const { data: balances, isError: isBalanceError } = usePortfolioBalance(activeAddress, [8453, ETHEREUM_CHAIN_ID]);
 
   if (!activeAddress) {
     return <div className="col-span-3 py-12 text-center text-gray-500">No tokens found</div>;
   }
 
-  if (!simBalance?.balances || simBalance.balances.length === 0) {
+  // "Couldn't load" and "holds nothing" are different answers and must not share a message.
+  if (isBalanceError) {
+    return <div className="col-span-3 py-12 text-center text-gray-500">Couldn&apos;t load your tokens</div>;
+  }
+
+  if (!balances || balances.length === 0) {
     return <div className="col-span-3 py-12 text-center text-gray-500">No tokens found</div>;
   }
 
   // Sort by USD value descending
-  const sortedBalances = [...simBalance.balances].sort((a, b) => {
+  const sortedBalances = [...balances].sort((a, b) => {
     const valueA = a.value_usd || 0;
     const valueB = b.value_usd || 0;
     return valueB - valueA;
@@ -43,8 +56,8 @@ const TokenContent = () => {
         // Determine token logo
         // For native tokens, use ETH logo instead of chain logo
         let tokenLogo = token.token_metadata?.logo || "";
-        if (token.address === "native" && token.symbol === "ETH") {
-          tokenLogo = CHAIN_LOGOS[0];
+        if (token.is_native && token.symbol === "ETH") {
+          tokenLogo = CHAIN_LOGOS[ETHEREUM_CHAIN_ID];
         }
 
         return (

package/src/global-account/react/components/Send/Send.tsx

@@ -6,7 +6,7 @@ import {
   useAnalytics,
   useModalStore,
   useProfile,
-  useSimBalance,
+  usePortfolioBalance,
   useUnifiedChainSwitchAndExecute,
 } from "@b3dotfun/sdk/global-account/react";
 import { validateImageUrl } from "@b3dotfun/sdk/global-account/react/utils/profileDisplay";
@@ -18,7 +18,7 @@ import { NumericFormat } from "react-number-format";
 
 import { encodeFunctionData, erc20Abi, isAddress, parseUnits } from "viem";
 
-import type { SimBalanceItem } from "../../hooks/useSimBalance";
+import type { B3TokenBalance } from "@b3dotfun/sdk/shared/utils/zerionPositions";
 import { useRecentAddressesStore } from "../../stores/useRecentAddressesStore";
 import ModalHeader from "../ModalHeader/ModalHeader";
 import { Button } from "../ui/button";
@@ -66,7 +66,7 @@ export function Send({ recipientAddress: initialRecipient, onSuccess }: SendModa
 
   // Wizard state
   const [step, setStep] = useState<SendStep>("recipient");
-  const [selectedToken, setSelectedToken] = useState<SimBalanceItem | null>(null);
+  const [selectedToken, setSelectedToken] = useState<B3TokenBalance | null>(null);
   const [recipientAddress, setRecipientAddress] = useState(initialRecipient || "");
   const [sendAmount, setSendAmount] = useState("");
   const [isSending, setIsSending] = useState(false);
@@ -74,7 +74,12 @@ export function Send({ recipientAddress: initialRecipient, onSuccess }: SendModa
   const [showValidatedResult, setShowValidatedResult] = useState(false);
 
   // Hooks
-  const { data: simBalance, refetch: refetchSimBalance, isLoading: isLoadingBalance } = useSimBalance(address);
+  const {
+    data: balances,
+    refetch: refetchBalances,
+    isLoading: isLoadingBalance,
+    isError: isBalanceError,
+  } = usePortfolioBalance(address);
   const { switchChainAndExecute } = useUnifiedChainSwitchAndExecute();
   const { sendAnalyticsEvent } = useAnalytics();
 
@@ -138,11 +143,11 @@ export function Send({ recipientAddress: initialRecipient, onSuccess }: SendModa
   };
 
   // Get current selected token from fresh balance
-  const getCurrentSelectedToken = (): SimBalanceItem | null => {
-    if (!selectedToken || !simBalance?.balances) {
+  const getCurrentSelectedToken = (): B3TokenBalance | null => {
+    if (!selectedToken || !balances) {
       return null;
     }
-    const found = simBalance.balances.find(
+    const found = balances.find(
       token => token.chain_id === selectedToken.chain_id && token.address === selectedToken.address,
     );
     return found || null;
@@ -187,11 +192,15 @@ export function Send({ recipientAddress: initialRecipient, onSuccess }: SendModa
         args: [recipientAddress, amountInWei],
       });
 
-      const tx = await switchChainAndExecute(currentToken.chain_id, {
-        to: currentToken.address === "native" ? recipientAddress : currentToken.address,
-        data: sendTokenData,
-        value: currentToken.address === "native" ? amountInWei : BigInt(0),
-      });
+      // A native send carries value and no calldata; an ERC-20 send carries calldata and no value.
+      // Branch on the explicit flag, never on the address: the native sentinel is a display detail,
+      // and taking the ERC-20 path for a native coin spends gas without moving anything.
+      const tx = await switchChainAndExecute(
+        currentToken.chain_id,
+        currentToken.is_native
+          ? { to: recipientAddress, value: amountInWei }
+          : { to: currentToken.address, data: sendTokenData, value: BigInt(0) },
+      );
 
       if (tx) {
         sendAnalyticsEvent("send_token_button_click", {
@@ -208,7 +217,7 @@ export function Send({ recipientAddress: initialRecipient, onSuccess }: SendModa
         }
 
         setTimeout(async () => {
-          await refetchSimBalance();
+          await refetchBalances();
         }, 1000);
       }
     } catch (error: any) {
@@ -364,10 +373,10 @@ export function Send({ recipientAddress: initialRecipient, onSuccess }: SendModa
                   ))}
                 </div>
               </div>
-            ) : simBalance?.balances && simBalance.balances.length > 0 ? (
+            ) : balances && balances.length > 0 ? (
               <div className="space-y-4">
                 <div className="space-y-1">
-                  {simBalance.balances.map(token => (
+                  {balances.map(token => (
                     <div
                       key={token.chain_id + "_" + token.address}
                       className="hover:bg-b3-line/60 dark:hover:bg-b3-primary-wash/40 group flex cursor-pointer items-center justify-between rounded-xl p-3 transition-all duration-200"
@@ -411,6 +420,21 @@ export function Send({ recipientAddress: initialRecipient, onSuccess }: SendModa
                   ))}
                 </div>
               </div>
+            ) : isBalanceError ? (
+              // Telling someone they hold nothing, when the read simply failed, invites them to go
+              // looking for missing funds.
+              <div className="flex flex-col items-center justify-center py-12 text-center">
+                <CircleHelp className="text-b3-foreground-muted mb-4 h-8 w-8" />
+                <p className="text-b3-foreground-muted font-neue-montreal-medium text-sm">
+                  Couldn&apos;t load your tokens
+                </p>
+                <button
+                  onClick={() => refetchBalances()}
+                  className="text-b3-foreground-muted font-neue-montreal-medium mt-2 text-sm underline"
+                >
+                  Try again
+                </button>
+              </div>
             ) : (
               <div className="flex flex-col items-center justify-center py-12 text-center">
                 <CircleHelp className="text-b3-foreground-muted mb-4 h-8 w-8" />

package/src/global-account/react/hooks/index.ts

@@ -39,8 +39,8 @@ export { useQueryBSMNT } from "./useQueryBSMNT";
 export { useRemoveSessionKey } from "./useRemoveSessionKey";
 export { useRouter } from "./useRouter";
 export { useSearchParamsSSR } from "./useSearchParamsSSR";
-export { useSimBalance, useSimSvmBalance, useSimTokenBalance } from "./useSimBalance";
-export { useSimCollectibles } from "./useSimCollectibles";
+export { usePortfolioBalance, usePortfolioTokenBalance } from "./usePortfolioBalance";
+export { usePortfolioCollectibles } from "./usePortfolioCollectibles";
 export { useSiwe } from "./useSiwe";
 export { useTokenBalance } from "./useTokenBalance";
 export { useTokenBalanceDirect } from "./useTokenBalanceDirect";

package/src/global-account/react/hooks/useAuth.ts

@@ -1,7 +1,7 @@
 import app from "@b3dotfun/sdk/global-account/app";
 import { authenticateWithB3JWT } from "@b3dotfun/sdk/global-account/bsmnt";
 import { useAuthStore, useB3Config } from "@b3dotfun/sdk/global-account/react";
-import { ecosystemWalletId } from "@b3dotfun/sdk/shared/constants";
+import { ecosystemWalletId, type EcosystemWallet } from "@b3dotfun/sdk/shared/constants";
 import { debugB3React } from "@b3dotfun/sdk/shared/utils/debug";
 import { client } from "@b3dotfun/sdk/shared/utils/thirdweb";
 import { ConnectionOptions } from "@thirdweb-dev/wagmi-adapter";
@@ -54,7 +54,8 @@ export function useAuth() {
   const { user, setUser } = useUserQuery();
   debug("@@activeWagmiAccount", activeWagmiAccount);
 
-  const wallet = ecosystemWallet(ecosystemWalletId, {
+  // Explicit annotation keeps the hook's declaration portable (TS2742).
+  const wallet: EcosystemWallet = ecosystemWallet(ecosystemWalletId, {
     partnerId: partnerId,
   });
 

package/src/global-account/react/hooks/useAuthentication.ts

@@ -1,7 +1,7 @@
 import app from "@b3dotfun/sdk/global-account/app";
 import { authenticateWithB3JWT } from "@b3dotfun/sdk/global-account/bsmnt";
 import { useAuthStore } from "@b3dotfun/sdk/global-account/react";
-import { ecosystemWalletId } from "@b3dotfun/sdk/shared/constants";
+import { ecosystemWalletId, type EcosystemWallet } from "@b3dotfun/sdk/shared/constants";
 import { debugB3React } from "@b3dotfun/sdk/shared/utils/debug";
 import { client } from "@b3dotfun/sdk/shared/utils/thirdweb";
 import { ConnectionOptions } from "@thirdweb-dev/wagmi-adapter";
@@ -63,7 +63,8 @@ export function useAuthentication(partnerId: string, { skipAutoConnect = false }
   const { switchAccount } = useSwitchAccount();
   debug("@@activeWagmiAccount", activeWagmiAccount);
 
-  const wallet = ecosystemWallet(ecosystemWalletId, {
+  // Explicit annotation keeps the hook's declaration portable (TS2742).
+  const wallet: EcosystemWallet = ecosystemWallet(ecosystemWalletId, {
     partnerId: partnerId,
   });
 

package/src/global-account/react/hooks/useFirstEOA.tsx

@@ -5,10 +5,17 @@ import { useEffect, useMemo, useState } from "react";
 import { viemAdapter } from "thirdweb/adapters/viem";
 import { useConnectedWallets, useWalletInfo } from "thirdweb/react";
 import { Wallet } from "thirdweb/wallets";
+import type { WalletClient } from "viem";
 
 const debug = debugB3React("useFirstEOA");
 
-export function useFirstEOA(chain?: { id: number; name: string; rpc: string }) {
+// Explicit return annotation keeps the hook's declaration portable (TS2742).
+export function useFirstEOA(chain?: { id: number; name: string; rpc: string }): {
+  account: Wallet | undefined;
+  address: string | undefined;
+  info: ReturnType<typeof useWalletInfo>;
+  walletClient: WalletClient | undefined;
+} {
   const wallets = useConnectedWallets();
   const isConnected = useAuthStore(state => state.isConnected);
   const [firstEOA, setFirstEOA] = useState<Wallet | undefined>(undefined);
@@ -41,7 +48,7 @@ export function useFirstEOA(chain?: { id: number; name: string; rpc: string }) {
     autoSelectFirstEOAWallet();
   }, [isConnected, wallets]);
 
-  const walletClient = useMemo(() => {
+  const walletClient = useMemo<WalletClient | undefined>(() => {
     if (!firstEOA) return undefined;
     if (!chain) return undefined;
     try {

package/src/global-account/react/hooks/usePortfolioBalance.ts

@@ -0,0 +1,89 @@
+import { useQuery } from "@tanstack/react-query";
+import {
+  adaptZerionPositions,
+  balanceMatchesToken,
+  type B3TokenBalance,
+  type ZerionPositionLike,
+} from "@b3dotfun/sdk/shared/utils/zerionPositions";
+
+/**
+ * Wallet holdings, read through the b3 portfolio proxy.
+ *
+ * The proxy holds the upstream API key server-side and authorizes browsers by Origin allowlist, so
+ * nothing secret ships to the client and no key is accepted from it. A consumer served from an
+ * origin the proxy does not know will be refused — adding an origin is a proxy config change, not
+ * an SDK change.
+ */
+const PORTFOLIO_API_BASE_URL = "https://portfolio-api.b3.fun";
+
+interface ZerionPositionsResponse {
+  data?: ZerionPositionLike[];
+}
+
+/**
+ * Fetch every spendable holding for a wallet in one request.
+ *
+ * Deliberately unpaginated and unfiltered by chain. The positions endpoint returns a wallet's full
+ * simple-position list in a single response, and passing a chain filter is actively harmful: the
+ * upstream rejects a handful of otherwise-valid chain slugs and fails the WHOLE request when one
+ * appears, so a caller asking for five chains can lose all five. Callers narrow the result instead.
+ */
+async function fetchWalletPositions(address: string): Promise<B3TokenBalance[]> {
+  const url = `${PORTFOLIO_API_BASE_URL}/v1/wallets/${encodeURIComponent(address)}/positions/?filter[positions]=only_simple`;
+  const response = await fetch(url, { headers: { Accept: "application/json" } });
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch wallet balances: ${response.status} ${response.statusText}`);
+  }
+
+  const body = (await response.json()) as ZerionPositionsResponse;
+  return adaptZerionPositions(body.data ?? []);
+}
+
+/**
+ * Keyed by wallet alone so every consumer of the same wallet shares one fetch and one cache entry.
+ * Keying by the requested chain subset instead would refetch per caller and share nothing.
+ */
+function walletPositionsQueryKey(address?: string) {
+  return ["walletPositions", address] as const;
+}
+
+/**
+ * Holdings for a wallet, optionally narrowed to specific chains.
+ *
+ * Read `isError` before reading `data`: a failed read and an empty wallet are different facts, and
+ * rendering the first as the second tells the user they hold nothing when nobody knows.
+ */
+export function usePortfolioBalance(address?: string, chainIds?: number[]) {
+  const wantedChainIds = chainIds && chainIds.length > 0 ? chainIds : undefined;
+
+  return useQuery({
+    queryKey: walletPositionsQueryKey(address),
+    queryFn: () => {
+      if (!address) throw new Error("Address is required");
+      return fetchWalletPositions(address);
+    },
+    enabled: Boolean(address),
+    select: (balances: B3TokenBalance[]) =>
+      wantedChainIds ? balances.filter(balance => wantedChainIds.includes(balance.chain_id)) : balances,
+  });
+}
+
+/**
+ * One token's balance for a wallet, served from the same per-wallet fetch as {@link usePortfolioBalance}.
+ *
+ * `tokenAddress` may be a contract address or the chain's native sentinel; matching is
+ * case-insensitive because callers pass addresses in whatever casing their source used.
+ */
+export function usePortfolioTokenBalance(walletAddress?: string, tokenAddress?: string, chainId?: number) {
+  return useQuery({
+    queryKey: walletPositionsQueryKey(walletAddress),
+    queryFn: () => {
+      if (!walletAddress) throw new Error("Address is required");
+      return fetchWalletPositions(walletAddress);
+    },
+    enabled: Boolean(walletAddress) && Boolean(tokenAddress) && Boolean(chainId),
+    select: (balances: B3TokenBalance[]) =>
+      balances.find(balance => balance.chain_id === chainId && balanceMatchesToken(balance, tokenAddress ?? "")),
+  });
+}