formatTokenAmount

Formats a token balance for UI using the token’s display (or on-chain) decimals.

import { TokenSymbol } from '@swapped/connect-sdk'
import { formatTokenAmount } from '@swapped/connect-sdk/format'

Human amount (by token)

Uses each token’s display decimals (e.g. ETH ≈ 6 display places, USDT = 2).

formatTokenAmount({ balance: '1.234567', token: TokenSymbol.ETH })
// "1.234567"

formatTokenAmount({ balance: '12.3456', token: TokenSymbol.USDT })
// "12.35"          — USDT display decimals = 2

formatTokenAmount({
  balance: '1.234567891',
  token: TokenSymbol.ETH,
  display: false,
})
// "1.234567891"    — on-chain decimals instead of display decimals

Raw smallest units

Pass decimals when balance is in smallest units (wei, etc.).

formatTokenAmount({
  balance: '1500000000000000000',
  decimals: 18,
  token: TokenSymbol.ETH,
})
// "1.5"

Dust amounts (firstNonZeroDecimal)

formatTokenAmount({
  balance: '0.00000012',
  token: TokenSymbol.ETH,
})
// "0"              — rounds to display precision

formatTokenAmount({
  balance: '0.00000012',
  token: TokenSymbol.ETH,
  firstNonZeroDecimal: true,
})
// "0.0000001"      — keeps the first significant digit visible

Large amounts (useLargeNumberFormat)

Uses formatCompactTokenAmount at/above the threshold (default 10000).

formatTokenAmount({
  balance: '12500',
  token: TokenSymbol.ETH,
})
// "12500"

formatTokenAmount({
  balance: '12500',
  token: TokenSymbol.ETH,
  useLargeNumberFormat: true,
})
// "12.50K"

Empty / missing input

formatTokenAmount({ balance: '1', token: null })
// ""

formatTokenAmount({ balance: '', token: TokenSymbol.ETH })
// ""

Param	Purpose
balance	Human amount, or smallest units when decimals is set
token	TokenSymbol — required; returns '' if missing
decimals	When set, treat balance as smallest units
display	true (default) uses display decimals; false uses on-chain decimals
firstNonZeroDecimal	Show enough places for amounts below the token minimum
useLargeNumberFormat	Abbreviate with K / M at/above largeNumberThreshold (default 10000)

Coinbase balances already include formatted.balance / formatted.valueFiat. For the same token formatting Coinbase uses, formatCoinbaseTokenAmount is also available from @swapped/connect-sdk.