Get Token Balance

token.getBalance

Gets the TIP-20 token balance of an account.

Usage

import {  } from './viem.config'
 
const  = await ..({
  : '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb',
  : '0x20c0000000000000000000000000000000000000',
})
 
.('Balance:', )
Balance: { amount: 10500000n, decimals: 6, formatted: '10.5' }

import { ,  } from 'viem/tempo'
 
export const  = .({
  : .('0x...'),
})

Recipes

Confirm the Payout Wallet Covers a Payroll Run

Omit account to read the Client's connected account, and compare the base-unit amount against the batch total before dispatching token.transferSync payouts.

import {  } from 'viem/utils'
import {  } from './viem.config'
 
const  = [
  { : .('1250.00', 6), : '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb' },
  { : .('980.50', 6), : '0x8ba1f109551bD432803012645Ac136ddd64DBA72' },
]
const  = .((, {  }) =>  + , 0n)
 
const  = await ..({
  : '0x20c0000000000000000000000000000000000000',
})
 
if (. < )
  throw new (
    `top up payout wallet by ${.( - ., .)}`,
  )

import { ,  } from 'viem/tempo'
 
export const  = .({
  : .('0x...'),
})

Read Balances Across Tokens in One Round Trip

Use getBalance.call with multicall to fetch one account's balances across several tokens in a single request, for example to render a wallet dashboard.

import {  } from 'viem/tempo'
import {  } from './viem.config'
 
const  = '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb'
 
const {  } = await .({
  : false,
  : [
    ...({
      ,
      : '0x20c0000000000000000000000000000000000000',
    }),
    ...({
      ,
      : '0x20c0000000000000000000000000000000000001',
    }),
  ],
})
 
.()
[10_500_000n, 2_750_000n]

import { ,  } from 'viem/tempo'
 
export const  = .({
  : .('0x...'),
})

Return Value

type ReturnType = {
  /** Balance in the token's base units. */
  amount: bigint
  /** Token decimals used to derive `formatted`. */
  decimals: number
  /** Balance formatted as a human-readable decimal string. */
  formatted: string
}

The balance, both in base units (amount) and as a human-readable decimal string (formatted, derived from the token's decimals).

Parameters

account

Type: Account | Address
Default: client.account

Account (or address) that owns the tokens.

decimals

Type: number

Decimals used to convert between base units and the human-readable amount. Inferred from the Client's tokens set when token matches a declared token; otherwise fetched from the token contract when needed.

token

Type: Address | bigint

Token to operate on: a TIP-20 token id or a contract address.

blockNumber (optional)

Type: bigint

Block number to read the state from.

blockOverrides (optional)

Type: BlockOverrides

Block overrides to apply to the state.

blockTag (optional)

Type: BlockTag

Block tag to read the state from.

stateOverride (optional)

Type: StateOverride

State override to apply.

Suggest changes to this page