Get Token Total Supply

Gets the total supply of a TIP-20 token.

Usage

import { client } from './viem.config'
 
const totalSupply = await client.token.getTotalSupply({
  token: '0x20c0000000000000000000000000000000000000',
})
 
console.log('Total Supply:', totalSupply)
Total Supply: { amount: 1000000000000000n, decimals: 6, formatted: '1000000000' }

import { Account, Client } from 'viem/tempo'
 
export const client = Client.create({
  account: Account.fromSecp256k1('0x...'),
})

Recipes

Snapshot Supply for a Reserve Attestation

Resolve the snapshot block with block.getNumber, then pass blockNumber so the reported circulating supply matches custodian reserve balances captured at the same moment.

import { client } from './viem.config'
 
const blockNumber = await client.block.getNumber()
 
const totalSupply = await client.token.getTotalSupply({
  blockNumber,
  token: '0x20c0000000000000000000000000000000000001',
})
 
console.log(`Supply at block ${blockNumber}:`, totalSupply.formatted)
Supply at block 19868020: 48250000.5

import { Account, Client } from 'viem/tempo'
 
export const client = Client.create({
  account: Account.fromSecp256k1('0x...'),
})

Return Value

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

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

Parameters

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.