useGetSingleTokenBalanceSummary

Hook for fetching a specific token balance for an account on a chain

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
}

Parameter	Type	Description
chainId	number	The chain ID to fetch the balance from
accountAddress	string	The address to fetch the balance for
contractAddress	string	The token contract address (use ZERO_ADDRESS for native tokens)

options: BalanceHookOptions

interface BalanceHookOptions {
  disabled?: boolean
  retry?: boolean
  hideCollectibles?: boolean
}

Parameter	Type	Description
disabled	boolean	(Optional) Disable the query from automatically running
retry	boolean	(Optional) Whether to retry failed queries
hideCollectibles	boolean	(Optional) If true, filters out ERC721 and ERC1155 tokens