Skip to main content

Balance Display

The ONE SDK provides both components and a standalone hook for displaying wallet token balances across multiple chains.

OneWalletBalance Component​

A ready-to-use component that renders a formatted balance view for a wallet address.

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

function WalletView() {
  return (
    <OneWalletBalance
      walletAddress="0x1234...abcd"
      chains={[8453, 1, 137]}
      autoRefresh
      refreshInterval={30000}
    />
  );
}

OneBalanceDisplay Component​

A lower-level display component that accepts pre-fetched balance data. Useful when you want full control over data fetching.

import { OneBalanceDisplay } from '@one_deploy/sdk';
import type { TokenBalance } from '@one_deploy/sdk';

function CustomBalanceView() {
  const balances: TokenBalance[] = [
    {
      token: 'ETH',
      symbol: 'ETH',
      name: 'Ethereum',
      balance: '1.2345',
      balanceUsd: '2469.00',
      chainId: 1,
      decimals: 18,
      contractAddress: null,
      logoUri: 'https://assets.one23.io/tokens/eth.png',
    },
    {
      token: 'USDC',
      symbol: 'USDC',
      name: 'USD Coin',
      balance: '500.00',
      balanceUsd: '500.00',
      chainId: 8453,
      decimals: 6,
      contractAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
      logoUri: 'https://assets.one23.io/tokens/usdc.png',
    },
  ];

  return <OneBalanceDisplay balances={balances} />;
}

OneWalletBalance Props​

interface OneWalletBalanceProps {
  /** The wallet address to display balances for. */
  walletAddress: string;

  /** Array of chain IDs to fetch balances from. Defaults to all supported chains. */
  chains?: number[];

  /** Enable automatic balance refresh. Defaults to false. */
  autoRefresh?: boolean;

  /** Refresh interval in milliseconds. Only used when autoRefresh is true. Defaults to 30000 (30s). */
  refreshInterval?: number;

  /** Callback fired when balances are loaded or updated. */
  onBalancesLoaded?: (balances: TokenBalance[]) => void;

  /** Show zero-balance tokens. Defaults to false. */
  showZeroBalances?: boolean;

  /** Additional CSS class name. */
  className?: string;

  /** Inline styles. */
  style?: React.CSSProperties;
}

TokenBalance Type​

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

  /** Display symbol. */
  symbol: string;

  /** Full token name. */
  name: string;

  /** Formatted balance as a decimal string. */
  balance: string;

  /** USD equivalent of the balance. */
  balanceUsd: string;

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

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

  /** ERC-20 contract address, or null for native tokens. */
  contractAddress: string | null;

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

useWalletBalance Hook​

The useWalletBalance hook is a standalone hook that does not require a provider. You can use it anywhere in your React tree to fetch wallet balances.

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

function BalanceHookExample() {
  const {
    balances,
    totalBalanceUsd,
    isLoading,
    error,
    refetch,
  } = useWalletBalance({
    walletAddress: '0x1234...abcd',
    chains: [8453, 1],
    autoRefresh: true,
    refreshInterval: 15000,
  });

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

  return (
    <div>
      <h2>Total: ${totalBalanceUsd}</h2>
      <ul>
        {balances.map((b) => (
          <li key={`${b.chainId}-${b.token}`}>
            {b.symbol}: {b.balance} (${b.balanceUsd})
          </li>
        ))}
      </ul>
      <button onClick={refetch}>Refresh</button>
    </div>
  );
}

Hook Signature​

function useWalletBalance(options: UseWalletBalanceOptions): UseWalletBalanceResult;

interface UseWalletBalanceOptions {
  /** The wallet address to query. */
  walletAddress: string;

  /** Chain IDs to fetch balances from. Defaults to all supported chains. */
  chains?: number[];

  /** Enable automatic refresh polling. Defaults to false. */
  autoRefresh?: boolean;

  /** Polling interval in milliseconds. Defaults to 30000. */
  refreshInterval?: number;
}

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

  /** Aggregated USD total across all tokens and chains. */
  totalBalanceUsd: string;

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

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

  /** Manually trigger a balance refetch. */
  refetch: () => Promise<void>;
}

No Provider Required​

Unlike most hooks in the ONE SDK, useWalletBalance works without wrapping your app in OneProvider. It uses the SDK's public API endpoints directly:

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

// This works outside of OneProvider
function StandaloneBalance({ address }: { address: string }) {
  const { balances, totalBalanceUsd, isLoading } = useWalletBalance({
    walletAddress: address,
  });

  if (isLoading) return <span>...</span>;

  return <span>${totalBalanceUsd}</span>;
}

Multi-Chain Balances​

Fetch balances from specific chains using the chains prop or option:

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

function MultiChainBalance() {
  return (
    <OneWalletBalance
      walletAddress="0x1234...abcd"
      chains={[
        CHAIN_IDS.BASE,
        CHAIN_IDS.ETHEREUM,
        CHAIN_IDS.POLYGON,
        CHAIN_IDS.ARBITRUM,
        CHAIN_IDS.OPTIMISM,
      ]}
      autoRefresh
      refreshInterval={60000}
      showZeroBalances={false}
      onBalancesLoaded={(balances) => {
        console.log(`Loaded ${balances.length} token balances`);
      }}
    />
  );
}

Next Steps​