formatTokenAmount

Formats a token balance for UI using the token’s display decimals, or an explicit maxDecimals when display is false.

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,
  maxDecimals: 8,
})
// "1.23456789"     — round to `maxDecimals` instead of display decimals

When display is false, pass maxDecimals (or decimals). The helper no longer looks up on-chain decimals from token.

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 / invalid input

Missing token or balance, whitespace, grouped numbers, and other non-amounts return ''. Scientific notation is expanded. Numeric 0 formats as "0".

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

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

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

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

formatTokenAmount({ balance: 0, token: TokenSymbol.USDT })
// "0"

formatTokenAmount({ balance: '1,234.50', token: TokenSymbol.USDT })
// ""              — pretty currency strings are not plain amounts

Param	Purpose
balance	Human amount (plain decimal string, scientific string, or number), or smallest units when decimals is set. Invalid / grouped values return ''
token	TokenSymbol — required; returns '' if missing
decimals	When set, treat balance as smallest units. Also used as rounding precision when display is false and maxDecimals is omitted
display	true (default) uses the token’s display decimals; false uses maxDecimals (or decimals)
maxDecimals	Rounding precision when display is false. Required in that mode unless decimals is set
firstNonZeroDecimal	Show enough places for amounts below the token minimum
useLargeNumberFormat	Abbreviate with K / M at/above largeNumberThreshold (default 10000)

Wallet and Coinbase balances already include formatted.balance (via formatTokenAmount). Prefer those strings over calling a formatter yourself.