useBalance

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

import { useBalance } from 'wagmi'

Usage#

import { useBalance } from 'wagmi'

const App = () => {
  const [{ data, error, loading }, getBalance] = useBalance({
    address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
  })

  if (loading) return <div>Fetching balance…</div>
  if (error) return <div>Error fetching balance</div>
  return (
    <div>
      {data?.formatted} {data?.symbol}
    </div>
  )
}

Return Values#

state#

{
  data?: {
    formatted: string
    symbol: string
    value: BigNumber
  }
  error?: Error
  loading?: boolean
}

getBalance#

(config: {
  address: string
  formatUnits?: Unit | number
  token?: string
}) => Promise<
  | {
      formatted: string
      symbol: string
      value: BigNumber
    }
  | Error
>

Configuration#

address (optional)#

Fetches Ethereum balance for address.

import { useBalance } from 'wagmi'

const App = () => {
  const [{ data, error, loading }, getBalance] = useBalance({
    address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e'
  })

  return ...
}

formatUnits (optional)#

Formats balance using ethers.js units. Defaults to ether.

import { useBalance } from 'wagmi'

const App = () => {
  const [{ data, error, loading }, getBalance] = useBalance({
    address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e'
    formatUnits: 'gwei',
  })

  return ...
}

skip (optional)#

Skips automatically fetching data on mount. Defaults to false. Useful if you want to call getBalance manually at some other point.

import { useBalance } from 'wagmi'

const App = () => {
  const [{ data, error, loading }, getBalance] = useBalance({
    address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e'
    skip: true,
  })

  return ...
}

token (optional)#

Fetches ERC-20 balance instead of Ethereum balance. For example, $UNI:

import { useBalance } from 'wagmi'

const App = () => {
  const [{ data, error, loading }, getBalance] = useBalance({
    address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e'
    token: '0x1f9840a85d5af5bf1d1762f925bdaddc4201f984',
  })

  return ...
}

watch (optional)#

Watches and refreshes balance for new blocks.

import { useBalance } from 'wagmi'

const App = () => {
  const [{ data, error, loading }, getBalance] = useBalance({
    address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e'
    watch: true
  })

  return ...
}