Formatting Utilities

Format token balances and convert between units

Overview

The Nexus SDK provides powerful formatting utilities for displaying token balances and converting between different unit representations.

formatTokenBalance

Format a token balance for UI display with smart zero-compression for tiny values.

Basic Usage

import { formatTokenBalance } from '@avail-project/nexus-core';

// Format regular values
const formatted = formatTokenBalance(1234567n, { decimals: 6, symbol: 'USDC' });
// "1.2346 USDC"

// Format tiny values with subscript notation
const tiny = formatTokenBalance(85090000000n, { decimals: 18 });
// "~0.0₄8509" (shows 4 leading zeros after decimal)

Parameters

value · string | number | bigint · required

The value to format. Can be:

• bigint: Raw token amount (requires decimals option)
• string: Human-readable decimal string
• number: JavaScript number

options · FormatTokenBalanceOptions

Formatting options

decimals · number

Number of decimals (required when value is bigint)

symbol · string

Token symbol to append (e.g., “USDC”, “ETH”)

significantDigits · number · default: 4

Significant digits to show for tiny values

maxFractionDigits · number · default: 4

Maximum decimal places for normal values

tinyThresholdPower · number

Threshold exponent for tiny value detection (10^-4 = 0.0001)

zeroCompress · boolean · default: true

Use subscript notation for leading zeros (e.g., 0.0₄8509)

thousandSeparator · boolean · default: false

Add thousand separators (e.g., 12,345.67)

trimTrailingZeros · boolean · default: true

Remove trailing zeros after decimal point

approxTilde · boolean · default: true

Prefix ”~” when rounding/truncating values

Returns

formatted · string

The formatted balance string, ready for UI display

Examples

Regular Values

import { formatTokenBalance } from '@avail-project/nexus-core';

// Standard formatting
formatTokenBalance(1234567n, { decimals: 6, symbol: 'USDC' });
// "1.2346 USDC"

formatTokenBalance('1234.5678', { symbol: 'ETH' });
// "1234.5678 ETH"

---

formatTokenBalanceParts

Format a token balance and return structured parts for custom rendering.

import { formatTokenBalanceParts } from '@avail-project/nexus-core';

const parts = formatTokenBalanceParts(85090000000n, {
  decimals: 18,
  symbol: 'ETH',
});

// Returns:
// {
//   text: "~0.0₄8509 ETH",
//   approx: true,
//   integer: "0",
//   zeroCount: 4,
//   zeroSubscript: "₄",
//   significant: "8509",
//   symbol: "ETH"
// }

Parameters

Same as formatTokenBalance().

Returns

parts · FormattedParts

text · string

The complete formatted string

approx · boolean

Whether the value is approximate (rounded/truncated)

integer · string

The integer part of the number

fraction · string

The fractional part (for normal values)

zeroCount · number

Number of leading zeros after decimal (for tiny values)

zeroSubscript · string

Subscript representation of zero count (e.g., “₄”)

significant · string

Significant digits after leading zeros (for tiny values)

symbol · string

Token symbol if provided

Use Cases

Custom Styling

import { formatTokenBalanceParts } from '@avail-project/nexus-core';

const parts = formatTokenBalanceParts('0.00008509', { symbol: 'ETH' });

if (parts.zeroSubscript) {
  // Render with custom subscript styling
  return (
    <span>
      {parts.approx && '~'}
      {parts.integer}.0
      <sub>{parts.zeroCount}</sub>
      {parts.significant} {parts.symbol}
    </span>
  );
}

---

parseUnits

Convert a human-readable decimal string to the smallest unit (wei, satoshi, etc.).

import { parseUnits } from '@avail-project/nexus-core';

// Parse ETH to wei
const wei = parseUnits('1.5', 18);
// 1500000000000000000n

// Parse USDC to base units
const usdcAmount = parseUnits('100.50', 6);
// 100500000n

Parameters

value · string · required

The human-readable decimal value (e.g., “1.5”, “100.50”)

decimals · number · required

Number of decimal places for the token

• ETH: 18
• USDC/USDT: 6
• USDM: 18

Returns

amount · bigint

The value in the smallest unit (base units)

Examples

ETH to Wei

import { parseUnits } from '@avail-project/nexus-core';

const amount = parseUnits('1.5', 18);
// 1500000000000000000n (1.5 ETH in wei)

const small = parseUnits('0.001', 18);
// 1000000000000000n (0.001 ETH in wei)

---

formatUnits

Convert from the smallest unit to a human-readable decimal string.

import { formatUnits } from '@avail-project/nexus-core';

// Convert wei to ETH
const eth = formatUnits(1500000000000000000n, 18);
// "1.5"

// Convert USDC base units to decimal
const usdc = formatUnits(100500000n, 6);
// "100.5"

Parameters

value · bigint · required

The value in smallest units (wei, satoshi, etc.)

decimals · number · required

Number of decimal places for the token

Returns

formatted · string

Human-readable decimal string

Examples

Wei to ETH

import { formatUnits } from '@avail-project/nexus-core';

const eth = formatUnits(1500000000000000000n, 18);
// "1.5"

const smallEth = formatUnits(1000000000000000n, 18);
// "0.001"

---

Best Practices

Use formatTokenBalance for UI

Always use formatTokenBalance() for displaying values to users. It handles edge cases like tiny values automatically.

Use parseUnits for API calls

Convert user input with parseUnits() before passing to SDK methods like bridge() or swap().

Match decimals to token

Always use the correct decimals for each token:

• ETH: 18
• USDC/USDT: 6
• USDM: 18

Handle bigint properly

Remember that parseUnits() returns bigint. Use the n suffix for literals: 1000000n

Common Patterns

Input Validation

import { parseUnits, formatUnits } from '@avail-project/nexus-core';

function validateAndParse(input: string, decimals: number) {
  try {
    const amount = parseUnits(input, decimals);
    if (amount <= 0n) {
      throw new Error('Amount must be greater than 0');
    }
    return amount;
  } catch (error) {
    throw new Error('Invalid amount format');
  }
}

---

sdk.convertTokenReadableAmountToBigInt

Available as an SDK instance method

Convert a human-readable token amount to bigint using the SDK’s chain and token metadata. This is a convenience method that automatically looks up the correct decimals for a token on a specific chain.

sdk.convertTokenReadableAmountToBigInt(
  amount: string,
  tokenSymbol: string,
  chainId: number
): bigint

Parameters

amount · string · required

The human-readable decimal value (e.g., “1.5”, “100.50”)

tokenSymbol · string · required

Token symbol - must be one of the supported tokens (‘ETH’, ‘USDC’, ‘USDT’, ‘USDM’)

chainId · number · required

Chain ID where the token will be used

Returns

amount · bigint

The value in the smallest unit for that specific token on that specific chain

Example

import { NexusSDK } from '@avail-project/nexus-core';

const sdk = new NexusSDK({ network: 'mainnet' });

// Convert USDC on Ethereum (6 decimals)
const ethUSDC = sdk.convertTokenReadableAmountToBigInt('100.50', 'USDC', 1);
// 100500000n

// Convert USDC on BNB Chain (18 decimals)
const bnbUSDC = sdk.convertTokenReadableAmountToBigInt('100.50', 'USDC', 56);
// 100500000000000000000n

// Use in bridge operation
const amount = sdk.convertTokenReadableAmountToBigInt('50', 'USDC', 137);
await sdk.bridge({
  token: 'USDC',
  amount, // Automatically uses correct decimals for Polygon USDC
  toChainId: 137,
});

This method requires the SDK to be initialized with chain metadata. Use the standalone parseUnits() function if you need to convert amounts before SDK initialization.

Comparison with parseUnits

With SDK Method

// SDK method - decimals looked up automatically
const amount = sdk.convertTokenReadableAmountToBigInt('100', 'USDC', 1);
// Automatically uses 6 decimals for USDC on Ethereum

With parseUnits

import { parseUnits } from '@avail-project/nexus-core';

// Manual method - must specify decimals
const amount = parseUnits('100', 6);
// Must know USDC has 6 decimals on Ethereum

Use sdk.convertTokenReadableAmountToBigInt() when working with supported tokens to avoid decimal mismatch errors across different chains. For example, USDC has 6 decimals on most chains but 18 decimals on BNB Chain.