Display balances

How to correctly fetch, convert, and display token balances from DFNS wallets, including decimal handling, fiat conversion, and caching tips.

When you call Get Wallet Assets, balances are returned in their smallest unit (wei, satoshi, etc.) as strings:

{
  "assets": [
    {
      "kind": "Native",
      "symbol": "ETH",
      "balance": "1500000000000000000",
      "decimals": 18,
      "verified": true
    },
    {
      "kind": "Erc20",
      "contract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "symbol": "USDC",
      "balance": "1000000",
      "decimals": 6,
      "verified": true
    }
  ]
}

To display a human-readable balance, divide by 10^decimals. Always use the decimals value from the API response. Different tokens use different values (ETH uses 18, USDC uses 6, WBTC uses 8, etc.).

Never use floating point numbers for balance calculations. Use BigInt in TypeScript or Decimal in Python to avoid precision loss.

Converting for display

TypeScript

function formatBalance(balance: string, decimals: number): string {
  const raw = BigInt(balance)
  const divisor = 10n ** BigInt(decimals)

  const wholePart = raw / divisor
  const fractionalPart = raw % divisor

  const fractionalStr = fractionalPart.toString().padStart(decimals, '0')
  const trimmed = fractionalStr.replace(/0+$/, '')

  return trimmed ? `${wholePart}.${trimmed}` : wholePart.toString()
}

formatBalance('1500000000000000000', 18) // "1.5"
formatBalance('1000000', 6)              // "1"
formatBalance('123456789', 6)            // "123.456789"

If you’re using a web3 library, formatUnits does the same thing:

import { formatUnits } from 'ethers'

formatUnits('1500000000000000000', 18) // "1.5"

import { formatUnits } from 'viem'

formatUnits(1500000000000000000n, 18) // "1.5"

Converting back to raw

When sending a transaction, convert user input back to the smallest unit:

TypeScript

function parseBalance(amount: string, decimals: number): string {
  const [whole, fraction = ''] = amount.split('.')
  const paddedFraction = fraction.padEnd(decimals, '0').slice(0, decimals)
  return BigInt(whole + paddedFraction).toString()
}

parseBalance('0.5', 18) // "500000000000000000"

Balance freshness

Get Wallet Assets returns the latest balance recorded by the DFNS indexer, not a live read from the chain. The indexer follows the chain with a short delay, so a just-confirmed deposit usually appears within seconds, but can take a few minutes on busy networks. There is no read-side cache to bust: polling more frequently will not surface a balance the indexer has not yet recorded.

For crediting a specific deposit, use the value field in the wallet.blockchainevent.detected webhook rather than differencing two Get Wallet Assets reads. Each webhook carries the exact amount for that event; sequential balance reads can both reflect the latest on-chain total and miss intermediate movements when events arrive in bursts.

Related

Get Wallet Assets

API reference for retrieving balances

Transfer Asset

API reference for transfers