Import

import { useGetSingleTokenBalanceSummary, ZERO_ADDRESS } from '@0xsequence/hooks'

Usage

import { useGetSingleTokenBalanceSummary, ZERO_ADDRESS } from '@0xsequence/hooks'
import { useAccount } from 'wagmi'

// Fetch native ETH balance
function NativeBalance() {
  const { address } = useAccount()
  
  const {
    data: ethBalance,
    isLoading,
    isError
  } = useGetSingleTokenBalanceSummary({
    chainId: 1,
    accountAddress: address || '',
    contractAddress: ZERO_ADDRESS
  })

  if (isLoading) return <div>Loading...</div>
  if (isError) return <div>Error fetching balance</div>

  return <div>ETH Balance: {ethBalance?.balance}</div>
}

// Fetch USDC balance
function TokenBalance() {
  const { address } = useAccount()
  
  const {
    data: usdcBalance,
    isLoading,
    isError
  } = useGetSingleTokenBalanceSummary({
    chainId: 1,
    accountAddress: address || '',
    contractAddress: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', // USDC
    hideCollectibles: true
  })

  if (isLoading) return <div>Loading...</div>
  if (isError) return <div>Error fetching balance</div>

  return <div>USDC Balance: {usdcBalance?.balance}</div>
}

Return Type: UseQueryResult<TokenBalance>

The hook returns all properties from React Query’s UseQueryResult with token balance data. Here’s the detailed structure:

interface TokenBalance {
  contractType: ContractType
  contractAddress: string
  accountAddress: string
  tokenID?: string
  balance: string
  blockHash: string
  blockNumber: number
  chainId: number
  uniqueCollectibles: string
  isSummary: boolean
  contractInfo?: ContractInfo
  tokenMetadata?: TokenMetadata
}

Properties

data

TokenBalance | undefined

Token balance object containing:

  • contractType: The type of contract (ERC20, ERC721, ERC1155)
  • contractAddress: The token contract address
  • accountAddress: The address whose balance was queried
  • balance: The balance amount in the token’s base units
  • chainId: The chain ID where the balance was fetched from
  • blockHash: Hash of the block containing the balance
  • blockNumber: Number of the block containing the balance
  • tokenID: Optional token ID for NFTs
  • uniqueCollectibles: Number of unique collectibles
  • isSummary: Whether this is a summary balance
  • contractInfo: Optional contract information
  • tokenMetadata: Optional token metadata

isLoading

boolean

Loading state for the data fetch.

isError

boolean

Error state indicating if the query failed.

error

Error | null

Any error that occurred during data fetching.

Parameters

The hook accepts two parameters:

args: GetSingleTokenBalanceSummaryArgs

interface GetSingleTokenBalanceSummaryArgs {
  chainId: number
  accountAddress: string
  contractAddress: string
}
ParameterTypeDescription
chainIdnumberThe chain ID to fetch the balance from
accountAddressstringThe address to fetch the balance for
contractAddressstringThe token contract address (use ZERO_ADDRESS for native tokens)

options: BalanceHookOptions

interface BalanceHookOptions {
  disabled?: boolean
  retry?: boolean
  hideCollectibles?: boolean
}
ParameterTypeDescription
disabledboolean(Optional) Disable the query from automatically running
retryboolean(Optional) Whether to retry failed queries
hideCollectiblesboolean(Optional) If true, filters out ERC721 and ERC1155 tokens