useBalance

Hook for fetching balance information for Ethereum or ERC-20 tokens.

This is a wrapper around viem's getBalance.

import { useBalance } from 'wagmi'

Usage

import { useBalance } from 'wagmi'   function App() {  const { data, isError, isLoading } = useBalance({  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',  })    if (isLoading) return <div>Fetching balance…</div>  if (isError) return <div>Error fetching balance</div>  return (  <div>  Balance: {data?.formatted} {data?.symbol}  </div>  ) }

Return Value

{  data?: {  decimals: number  formatted: string  symbol: string  value: bigint  }  error?: Error  isIdle: boolean  isLoading: boolean  isFetching: boolean  isSuccess: boolean  isError: boolean  isFetched: boolean  isFetchedAfterMount: boolean  isRefetching: boolean  refetch: (options: {  throwOnError: boolean  cancelRefetch: boolean  }) => Promise<{  decimals: number  formatted: string  symbol: string  value: bigint  }>  status: 'idle' | 'error' | 'loading' | 'success' }

Configuration

address (optional)

Address to fetch balance for. If address is not defined, hook will not run.

import { useBalance } from 'wagmi'   function App() {  const balance = useBalance({  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',  }) }

chainId (optional)

Force a specific chain id for the request. The wagmi Client's publicClient must be set up as a chain-aware function for this to work correctly.

import { useBalance } from 'wagmi'   function App() {  const balance = useBalance({  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',  chainId: 1,  }) }

formatUnits (optional)

Formats balance. Defaults to ether or token's decimal value.

import { useBalance } from 'wagmi'   function App() {  const balance = useBalance({  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',  formatUnits: 'gwei',  }) }

token (optional)

Address for ERC-20 token. If token is provided, hook fetches token balance instead of Ethereum balance. For example, we can fetch 0xA0Cf798816D4b9b9866b5330EEa46a18382f251e's current $UNI balance.

import { useBalance } from 'wagmi'   function App() {  const balance = useBalance({  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',  token: '0x1f9840a85d5af5bf1d1762f925bdaddc4201f984',  }) }

watch (optional)

Watches and refreshes data for new blocks.

import { useBalance } from 'wagmi'   function App() {  const balance = useBalance({  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',  watch: true,  }) }

cacheTime (optional)

Time (in ms) which the data should remain in the cache. Defaults to 0.

import { useBalance } from 'wagmi'   function App() {  const balance = useBalance({  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',  cacheTime: 2_000,  }) }

enabled (optional)

Set this to false to disable this query from automatically running. Defaults to true.

import { useBalance } from 'wagmi'   function App() {  const balance = useBalance({  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',  enabled: false,  }) }

staleTime (optional)

Time (in ms) after data is considered stale. If set to Infinity the data will never be considered stale. Defaults to 0.

import { useBalance } from 'wagmi'   function App() {  const balance = useBalance({  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',  staleTime: 2_000,  }) }

scopeKey (optional)

Scopes the cache to a given context. Hooks that have identical scope will share the same cache.

import { useBalance } from 'wagmi'   function App() {  const balance = useBalance({  addressOrName: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',  scopeKey: 'wagmi',  }) }

suspense (optional)

Set this to true to enable suspense mode.

import { useBalance } from 'wagmi'   function App() {  const balance = useBalance({  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',  suspense: true,  }) }

onError (optional)

Function to invoke when an error is thrown while fetching new data.

import { useBalance } from 'wagmi'   function App() {  const balance = useBalance({  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',  onError(error) {  console.log('Error', error)  },  }) }

onSettled (optional)

Function to invoke when fetching is settled (either successfully fetched, or an error has thrown).

import { useBalance } from 'wagmi'   function App() {  const balance = useBalance({  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',  onSettled(data, error) {  console.log('Settled', { data, error })  },  }) }

onSuccess (optional)

Function to invoke when fetching new data is successful.

import { useBalance } from 'wagmi'   function App() {  const balance = useBalance({  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',  onSuccess(data) {  console.log('Success', data)  },  }) }

useAccount useBlockNumber