Skip to main content

useWalletBalance

useWalletBalance is a standalone hook -- it does not require OneProvider or any other context wrapper. You can drop it into any React component to fetch token balances for a wallet address across one or more chains.

Import​

import { useWalletBalance } from '@one_deploy/sdk';

Signature​

function useWalletBalance(
  walletAddress: string,
  options?: UseWalletBalanceOptions
): UseWalletBalanceReturn;

Parameters​

ParameterTypeRequiredDescription
walletAddressstringYesThe wallet address to fetch balances for (e.g. "0x1234...abcd").
optionsUseWalletBalanceOptionsNoConfiguration for chains, auto-refresh, and API connection.

Options​

interface UseWalletBalanceOptions {
  /** Array of chain IDs to fetch balances from.
   *  Defaults to all supported chains (Base, Ethereum, Polygon, Arbitrum, Optimism). */
  chains?: number[];

  /** Enable automatic polling for updated balances.
   *  Defaults to false. */
  autoRefresh?: boolean;

  /** Polling interval in milliseconds when autoRefresh is true.
   *  Defaults to 30000 (30 seconds). Minimum: 5000. */
  refreshInterval?: number;

  /** Override the ONE Engine API URL.
   *  Defaults to 'https://engine.one23.io'. */
  engineUrl?: string;

  /** Your ONE project client ID. Required only when calling outside
   *  of OneProvider (the provider supplies this automatically). */
  clientId?: string;
}

Return Type​

interface UseWalletBalanceReturn {
  /** Array of token balances across all requested chains. */
  balances: TokenBalance[];

  /** Aggregated USD total across all tokens and chains (formatted string). */
  totalUsd: string;

  /** Whether the initial fetch is in progress. */
  isLoading: boolean;

  /** Error object if the fetch failed, or null on success. */
  error: OneSDKError | null;

  /** Manually trigger a balance refetch. Returns a promise that resolves
   *  when the new data is loaded. */
  refetch: () => Promise<void>;
}

TokenBalance Type​

Each entry in the balances array describes a single token on a single chain:

interface TokenBalance {
  /** Token ticker symbol (e.g. 'ETH', 'USDC'). */
  token: string;

  /** Display symbol (usually same as token). */
  symbol: string;

  /** Full token name (e.g. 'Ethereum', 'USD Coin'). */
  name: string;

  /** Formatted balance as a decimal string (e.g. '1.2345'). */
  balance: string;

  /** USD equivalent of the balance (e.g. '2469.00'). */
  balanceUsd: string;

  /** Chain ID where this balance was fetched. */
  chainId: number;

  /** Token decimal places. */
  decimals: number;

  /** ERC-20 contract address, or null for native tokens (ETH, MATIC, etc.). */
  contractAddress: string | null;

  /** URL to the token logo image. */
  logoUri: string;
}

Basic Usage​

import { useWalletBalance } from '@one_deploy/sdk';

function WalletOverview({ address }: { address: string }) {
  const { balances, totalUsd, isLoading, error, refetch } = useWalletBalance(address);

  if (isLoading) return <p>Loading balances...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <div>
      <h2>Total Balance: ${totalUsd}</h2>
      <table>
        <thead>
          <tr>
            <th>Token</th>
            <th>Balance</th>
            <th>USD</th>
            <th>Chain</th>
          </tr>
        </thead>
        <tbody>
          {balances.map((b) => (
            <tr key={`${b.chainId}-${b.contractAddress ?? b.symbol}`}>
              <td>{b.symbol}</td>
              <td>{b.balance}</td>
              <td>${b.balanceUsd}</td>
              <td>{b.chainId}</td>
            </tr>
          ))}
        </tbody>
      </table>
      <button onClick={refetch}>Refresh</button>
    </div>
  );
}

Auto-Refresh​

Enable polling to keep balances up to date:

import { useWalletBalance } from '@one_deploy/sdk';

function LiveBalance({ address }: { address: string }) {
  const { balances, totalUsd, isLoading } = useWalletBalance(address, {
    autoRefresh: true,
    refreshInterval: 15000, // poll every 15 seconds
  });

  return (
    <div>
      <h3>${totalUsd}</h3>
      {isLoading && <span>(updating...)</span>}
      <ul>
        {balances.map((b) => (
          <li key={`${b.chainId}-${b.symbol}`}>
            {b.symbol}: {b.balance}
          </li>
        ))}
      </ul>
    </div>
  );
}
tip

When autoRefresh is active, isLoading is only true for the initial fetch. Subsequent polls update balances silently without flipping isLoading back to true.

Multi-Chain Balances​

By default, useWalletBalance queries all supported chains. To limit the query to specific chains, pass the chains option:

import { useWalletBalance, CHAIN_IDS } from '@one_deploy/sdk';

function BaseAndEthBalance({ address }: { address: string }) {
  const { balances, totalUsd } = useWalletBalance(address, {
    chains: [CHAIN_IDS.BASE, CHAIN_IDS.ETHEREUM],
  });

  return (
    <div>
      <p>Total (Base + Ethereum): ${totalUsd}</p>
      {balances.map((b) => (
        <p key={`${b.chainId}-${b.symbol}`}>
          [{b.chainId}] {b.symbol}: {b.balance} (${b.balanceUsd})
        </p>
      ))}
    </div>
  );
}

Custom Engine URL​

When running against a self-hosted or staging ONE Engine instance:

import { useWalletBalance } from '@one_deploy/sdk';

function StagingBalance({ address }: { address: string }) {
  const { balances, totalUsd } = useWalletBalance(address, {
    engineUrl: 'https://engine-staging.one23.io',
    clientId: 'my_staging_client_id',
  });

  return <p>Staging balance: ${totalUsd}</p>;
}

No Provider Required​

Unlike most ONE SDK hooks, useWalletBalance works without wrapping your app in OneProvider. It calls the ONE Engine API directly.

import { useWalletBalance } from '@one_deploy/sdk';

// This component can be rendered anywhere -- no OneProvider ancestor needed
function StandaloneWidget() {
  const { totalUsd, isLoading } = useWalletBalance(
    '0x1234567890abcdef1234567890abcdef12345678'
  );

  if (isLoading) return <span>...</span>;
  return <span>Portfolio: ${totalUsd}</span>;
}

If you are inside OneProvider, the hook will still work -- it simply does not read from the provider context.

Error Handling​

import { useWalletBalance } from '@one_deploy/sdk';

function SafeBalance({ address }: { address: string }) {
  const { balances, totalUsd, isLoading, error, refetch } = useWalletBalance(address);

  if (isLoading) return <p>Loading...</p>;

  if (error) {
    return (
      <div>
        <p>Failed to load balances: {error.message} ({error.code})</p>
        <button onClick={refetch}>Retry</button>
      </div>
    );
  }

  if (balances.length === 0) {
    return <p>No tokens found for this address.</p>;
  }

  return <p>Total: ${totalUsd} across {balances.length} tokens</p>;
}

See Also​