useBalance – wagmi

Documentation

Hooks

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({
    addressOrName: '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

result

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

getBalance

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

Configuration

addressOrName (optional)

Fetches Ethereum balance for address or ENS name.

import { useBalance } from 'wagmi'

const App = () => {
  const [{ data, error, loading }, getBalance] = useBalance({
    addressOrName: 'awkweb.eth'
  })

  return ...
}

formatUnits (optional)

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

import { useBalance } from 'wagmi'

const App = () => {
  const [{ data, error, loading }, getBalance] = useBalance({
    addressOrName: '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({
    addressOrName: '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({
    addressOrName: '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({
    addressOrName: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e'
    watch: true
  })

  return ...
}

useAccount

useBlockNumber