# formatTokenAmount

> **formatTokenAmount**(`value`, `decimals`, `options?`): `string`

Defined in: [core/src/utils/token-amount.ts:229](https://github.com/B3Pay/ic-reactor/blob/f1956947ae037304fce1675a38695964c1aa9e32/packages/core/src/utils/token-amount.ts#L229)

Show an amount of a token's base units as decimal text, exactly.

`value` is what a ledger returns: a `bigint` from a `Reactor`, or the
integer text a `DisplayReactor` gives for a `nat`. `decimals` is the
token's, as `icrc1_decimals` returns it, in any of those forms. No digit
passes through a JavaScript `Number`, so an 18-decimal balance of any size
shows as it is.

By default every significant fraction digit is shown and zeros at the end
are dropped. `maxFractionDigits` shortens the fraction, cutting the rest
unless `roundingMode` is `"halfExpand"`; `minFractionDigits` or
`trimTrailingZeros: false` pads it. A negative amount (an `int`) is written
with a leading `-`, except where the digits shown are all zero.

## Parameters

### value

`string` \| `number` \| `bigint`

The amount in base units (e8s for ICP).

### decimals

`string` \| `number` \| `bigint`

The token's decimals, from 0 to 255.

### options?

[`FormatTokenAmountOptions`](https://ic-reactor.b3pay.net/v3/libs/interfaces/formattokenamountoptions/) = `{}`

Fraction digits, rounding, locale and grouping.

## Returns

`string`

The amount as decimal text, `"1.5"` for 150000000 e8s.

## Throws

TypeError when `value` is not an integer amount, or `decimals` is
not a whole number.

## Throws

RangeError when `decimals` or a digit option is outside 0-255,
`minFractionDigits` exceeds `maxFractionDigits`, `roundingMode` is not one
of the two, or `Intl.NumberFormat` refuses `locale`.

## Example

```ts
import { formatTokenAmount } from "@ic-reactor/core"

formatTokenAmount(150_000_000n, 8) // "1.5"
formatTokenAmount("123456789", 8, { maxFractionDigits: 2 }) // "1.23"
formatTokenAmount(100_000_000n, 8, { minFractionDigits: 2 }) // "1.00"
formatTokenAmount(123_456_789_000n, 8, { locale: "de-DE" }) // "1.234,56789"

// A DisplayReactor returns both as display values
const [balance, decimals] = await Promise.all([
  ledger.fetchQuery({ functionName: "icrc1_balance_of", args: [{ owner }] }),
  ledger.fetchQuery({ functionName: "icrc1_decimals" }),
])
formatTokenAmount(balance, decimals, { maxFractionDigits: 4 })
```