Skip to main content

numbers

This module provides comprehensive utilities for handling numeric operations, formatting, and conversions in the GMX protocol. It includes functions for working with BigInt values, formatting currencies and percentages, handling decimal precision, and converting between different numeric representations.

Types​

  • Numeric: number | bigint - Union type for numeric values
  • BigNumberish: string | Numeric - Union type for values that can be converted to BigInt

Constants​

  • USD_DECIMALS: 30 - Standard decimal precision for USD values
  • BASIS_POINTS_DIVISOR: 10000 - Divisor for basis points calculations
  • BASIS_POINTS_DIVISOR_BIGINT: 10000n - BigInt version of basis points divisor
  • BASIS_POINTS_DECIMALS: 4 - Decimal places for basis points
  • PRECISION_DECIMALS: 30 - Standard precision decimal places
  • PRECISION: bigint - Precision constant (10^30)
  • BN_ZERO: 0n - BigInt zero constant
  • BN_ONE: 1n - BigInt one constant
  • BN_NEGATIVE_ONE: -1n - BigInt negative one constant
  • MaxUint256: bigint - Maximum uint256 value
  • PERCENT_PRECISION_DECIMALS: 28 - Decimal precision for percentages
  • TRIGGER_PREFIX_ABOVE: ">" - Prefix for values above threshold
  • TRIGGER_PREFIX_BELOW: "<" - Prefix for values below threshold
import { USD_DECIMALS, PRECISION, BN_ZERO } from "@gmx-ui/sdk/utils/numbers";

const usdValue = 1000n * 10n ** BigInt(USD_DECIMALS);
const calculation = (usdValue * PRECISION) / 100n;

Methods​

expandDecimals​

  • expandDecimals(n: BigNumberish, decimals: number): bigint

Expands a number by adding decimal places (multiplying by 10^decimals).

import { expandDecimals } from "@gmx-ui/sdk/utils/numbers";

const amount = expandDecimals(100, 18); // 100 * 10^18
const usdAmount = expandDecimals(50, 30); // 50 * 10^30

basisPointsToFloat​

  • basisPointsToFloat(basisPoints: bigint): bigint

Converts basis points to a float representation with precision scaling.

import { basisPointsToFloat } from "@gmx-ui/sdk/utils/numbers";

const bps = 250n; // 2.5%
const floatValue = basisPointsToFloat(bps);

getBasisPoints​

  • getBasisPoints(numerator: bigint, denominator: bigint, shouldRoundUp?: boolean): bigint

Calculates basis points from numerator and denominator with optional rounding.

import { getBasisPoints } from "@gmx-ui/sdk/utils/numbers";

const fee = getBasisPoints(25n, 1000n); // 250 basis points (2.5%)
const feeRoundedUp = getBasisPoints(25n, 1000n, true);

roundUpMagnitudeDivision​

  • roundUpMagnitudeDivision(a: bigint, b: bigint): bigint

Performs division with rounding up, handling negative values correctly.

import { roundUpMagnitudeDivision } from "@gmx-ui/sdk/utils/numbers";

const result = roundUpMagnitudeDivision(100n, 3n); // 34n
const negativeResult = roundUpMagnitudeDivision(-100n, 3n); // -33n

applyFactor​

  • applyFactor(value: bigint, factor: bigint): bigint

Applies a factor to a value using precision scaling.

import { applyFactor, expandDecimals } from "@gmx-ui/sdk/utils/numbers";

const value = expandDecimals(1000, 30);
const factor = expandDecimals(15, 29); // 1.5x factor
const result = applyFactor(value, factor);

numberToBigint​

  • numberToBigint(value: number, decimals: number): bigint

Converts a JavaScript number to BigInt with specified decimal places.

import { numberToBigint } from "@gmx-ui/sdk/utils/numbers";

const amount = numberToBigint(123.456, 18);
const negativeAmount = numberToBigint(-50.25, 6);

trimZeroDecimals​

  • trimZeroDecimals(amount: string): string

Removes trailing zeros from decimal representation.

import { trimZeroDecimals } from "@gmx-ui/sdk/utils/numbers";

const trimmed = trimZeroDecimals("123.000"); // "123"
const unchanged = trimZeroDecimals("123.456"); // "123.456"

bigintToNumber​

  • bigintToNumber(value: bigint, decimals: number): number

Converts a BigInt with decimals to a JavaScript number.

import { bigintToNumber, expandDecimals } from "@gmx-ui/sdk/utils/numbers";

const bigintValue = expandDecimals(123456, 18);
const numberValue = bigintToNumber(bigintValue, 18); // 123.456

adjustForDecimals​

  • adjustForDecimals(amount: bigint, divDecimals: number, mulDecimals: number): bigint

Adjusts an amount from one decimal precision to another.

import { adjustForDecimals, expandDecimals } from "@gmx-ui/sdk/utils/numbers";

const amount = expandDecimals(100, 18);
const adjusted = adjustForDecimals(amount, 18, 6); // Convert from 18 to 6 decimals

formatUsd​

  • formatUsd(usd?: bigint, opts?: object): string | undefined

Parameters​

  • usd: bigint - USD amount to format
  • opts: object - Formatting options including fallbackToZero, displayDecimals, maxThreshold, minThreshold, displayPlus, visualMultiplier

Formats a USD amount with proper currency symbol and decimal places.

import { formatUsd, expandDecimals } from "@gmx-ui/sdk/utils/numbers";

const usdAmount = expandDecimals(1234567, 30);
const formatted = formatUsd(usdAmount); // "$1,234.57"
const withPlus = formatUsd(usdAmount, { displayPlus: true }); // "+$1,234.57"

formatBigUsd​

  • formatBigUsd(amount: bigint, opts?: object): string

Parameters​

  • amount: bigint - USD amount to format
  • opts: object - Options with displayDecimals property

Formats large USD amounts without threshold limits.

import { formatBigUsd, expandDecimals } from "@gmx-ui/sdk/utils/numbers";

const largeAmount = expandDecimals(999999999999, 30);
const formatted = formatBigUsd(largeAmount); // "$999,999,999,999"

formatDeltaUsd​

  • formatDeltaUsd(deltaUsd?: bigint, percentage?: bigint, opts?: object): string | undefined

Parameters​

  • deltaUsd: bigint - USD delta amount
  • percentage: bigint - Percentage change
  • opts: object - Options including fallbackToZero and showPlusForZero

Formats USD delta with percentage change.

import { formatDeltaUsd, expandDecimals } from "@gmx-ui/sdk/utils/numbers";

const delta = expandDecimals(150, 30);
const percentage = expandDecimals(5, 2); // 5%
const formatted = formatDeltaUsd(delta, percentage); // "+$150.00 (+5.00%)"

formatPercentage​

  • formatPercentage(percentage?: bigint, opts?: object): string | undefined

Parameters​

  • percentage: bigint - Percentage value to format
  • opts: object - Options including fallbackToZero, signed, displayDecimals, bps, showPlus

Formats percentage values with proper signs and decimal places.

import { formatPercentage } from "@gmx-ui/sdk/utils/numbers";

const percentage = 525n; // 5.25% in basis points
const formatted = formatPercentage(percentage); // "+5.25%"
const unsigned = formatPercentage(percentage, { signed: false }); // "5.25%"

formatTokenAmount​

  • formatTokenAmount(amount?: bigint, tokenDecimals?: number, symbol?: string, opts?: object): string | undefined

Parameters​

  • amount: bigint - Token amount to format
  • tokenDecimals: number - Token decimal places
  • symbol: string - Token symbol
  • opts: object - Formatting options including showAllSignificant, displayDecimals, fallbackToZero, useCommas, minThreshold, maxThreshold, displayPlus, isStable

Formats token amounts with symbol and proper decimal handling.

import { formatTokenAmount, expandDecimals } from "@gmx-ui/sdk/utils/numbers";

const amount = expandDecimals(1234567, 18);
const formatted = formatTokenAmount(amount, 18, "ETH"); // "1.2346 ETH"
const withCommas = formatTokenAmount(amount, 18, "ETH", { useCommas: true }); // "1.2346 ETH"

formatTokenAmountWithUsd​

  • formatTokenAmountWithUsd(tokenAmount?: bigint, usdAmount?: bigint, tokenSymbol?: string, tokenDecimals?: number, opts?: object): string | undefined

Parameters​

  • tokenAmount: bigint - Token amount
  • usdAmount: bigint - USD equivalent amount
  • tokenSymbol: string - Token symbol
  • tokenDecimals: number - Token decimal places
  • opts: object - Options including fallbackToZero, displayDecimals, displayPlus, isStable

Formats token amount with USD equivalent in parentheses.

import { formatTokenAmountWithUsd, expandDecimals } from "@gmx-ui/sdk/utils/numbers";

const tokenAmount = expandDecimals(1, 18);
const usdAmount = expandDecimals(2500, 30);
const formatted = formatTokenAmountWithUsd(tokenAmount, usdAmount, "ETH", 18);
// "1.0000 ETH ($2,500.00)"

formatRatePercentage​

  • formatRatePercentage(rate?: bigint, opts?: object): string

Parameters​

  • rate: bigint - Rate value to format
  • opts: object - Options with displayDecimals and signed properties

Formats rate as percentage with optional sign display.

import { formatRatePercentage, expandDecimals } from "@gmx-ui/sdk/utils/numbers";

const rate = expandDecimals(5, 28); // 0.05 (5%)
const formatted = formatRatePercentage(rate); // "+5.0000%"
const unsigned = formatRatePercentage(rate, { signed: false }); // "5.0000%"

formatUsdPrice​

  • formatUsdPrice(price?: bigint, opts?: object): string | undefined

Parameters​

  • price: bigint - Price to format
  • opts: object - Formatting options (same as formatUsd)

Formats USD price with dynamic decimal precision based on price magnitude.

import { formatUsdPrice, expandDecimals } from "@gmx-ui/sdk/utils/numbers";

const price = expandDecimals(2500, 30);
const formatted = formatUsdPrice(price); // "$2,500.00"
const smallPrice = expandDecimals(1, 27);
const formattedSmall = formatUsdPrice(smallPrice); // "$0.001000"

formatPercentageDisplay​

  • formatPercentageDisplay(percentage: number, hideThreshold?: number): string

Formats percentage display with optional hiding threshold.

import { formatPercentageDisplay } from "@gmx-ui/sdk/utils/numbers";

const formatted = formatPercentageDisplay(5.25); // "5.25%"
const hidden = formatPercentageDisplay(0.5, 1); // ""

formatAmountHuman​

  • formatAmountHuman(amount: BigNumberish | undefined, tokenDecimals: number, showDollar?: boolean, displayDecimals?: number): string

Formats amounts in human-readable format with k/m/b suffixes.

import { formatAmountHuman, expandDecimals } from "@gmx-ui/sdk/utils/numbers";

const amount = expandDecimals(1500000, 18);
const formatted = formatAmountHuman(amount, 18); // "1.5m"
const withDollar = formatAmountHuman(amount, 18, true); // "$1.5m"

formatBalanceAmount​

  • formatBalanceAmount(amount: bigint, tokenDecimals: number, tokenSymbol?: string, opts?: object): string

Parameters​

  • amount: bigint - Balance amount to format
  • tokenDecimals: number - Token decimal places
  • tokenSymbol: string - Token symbol
  • opts: object - Options including showZero, toExponential, isStable, signed

Formats balance amounts with dynamic precision based on magnitude.

import { formatBalanceAmount, expandDecimals } from "@gmx-ui/sdk/utils/numbers";

const balance = expandDecimals(123, 15); // Very small amount
const formatted = formatBalanceAmount(balance, 18, "ETH"); // "0.000123 ETH"
const zero = formatBalanceAmount(0n, 18, "ETH"); // "-"
const showZero = formatBalanceAmount(0n, 18, "ETH", { showZero: true }); // "0.0000 ETH"

formatFactor​

  • formatFactor(factor: bigint): string

Formats factor values with appropriate decimal precision.

import { formatFactor, expandDecimals } from "@gmx-ui/sdk/utils/numbers";

const factor = expandDecimals(15, 29); // 1.5x factor
const formatted = formatFactor(factor); // "1.5"

numberWithCommas​

  • numberWithCommas(x: BigNumberish, opts?: object): string

Parameters​

  • x: BigNumberish - Number to format
  • opts: object - Options with showDollar property

Adds comma separators to numbers.

import { numberWithCommas } from "@gmx-ui/sdk/utils/numbers";

const formatted = numberWithCommas(1234567); // "1,234,567"
const withDollar = numberWithCommas(1234567, { showDollar: true }); // "$1,234,567"

formatAmount​

  • formatAmount(amount: BigNumberish | undefined, tokenDecimals: number, displayDecimals?: number, useCommas?: boolean, defaultValue?: string, visualMultiplier?: number): string

Core formatting function for amounts with customizable options.

import { formatAmount, expandDecimals } from "@gmx-ui/sdk/utils/numbers";

const amount = expandDecimals(1234567, 18);
const formatted = formatAmount(amount, 18, 4, true); // "1.2346"
const withCommas = formatAmount(amount, 18, 2, true); // "1.23"

formatKeyAmount​

  • formatKeyAmount(map: object, key: keyof object, tokenDecimals: number, displayDecimals: number, useCommas?: boolean): string

Formats amount from object property.

import { formatKeyAmount } from "@gmx-ui/sdk/utils/numbers";

const data = { balance: 1234567890000000000n };
const formatted = formatKeyAmount(data, "balance", 18, 4); // "1.2346"

formatArrayAmount​

  • formatArrayAmount(arr: any[], index: number, tokenDecimals: number, displayDecimals?: number, useCommas?: boolean): string

Formats amount from array element.

import { formatArrayAmount } from "@gmx-ui/sdk/utils/numbers";

const amounts = [1234567890000000000n, 9876543210000000000n];
const formatted = formatArrayAmount(amounts, 0, 18, 4); // "1.2346"

formatAmountFree​

  • formatAmountFree(amount: BigNumberish, tokenDecimals: number, displayDecimals?: number): string

Formats amount without padding zeros.

import { formatAmountFree, expandDecimals } from "@gmx-ui/sdk/utils/numbers";

const amount = expandDecimals(123, 18);
const formatted = formatAmountFree(amount, 18, 6); // "0.000123"

getLimitedDisplay​

  • getLimitedDisplay(amount: bigint, tokenDecimals: number, opts?: object): object

Parameters​

  • amount: bigint - Amount to check
  • tokenDecimals: number - Token decimal places
  • opts: object - Options with maxThreshold and minThreshold

Gets display information with threshold symbols.

import { getLimitedDisplay, expandDecimals } from "@gmx-ui/sdk/utils/numbers";

const amount = expandDecimals(1, 15); // Very small amount
const display = getLimitedDisplay(amount, 18);
// { symbol: "<", value: minThreshold }

limitDecimals​

  • limitDecimals(amount: BigNumberish, maxDecimals?: number): string

Limits decimal places in string representation.

import { limitDecimals } from "@gmx-ui/sdk/utils/numbers";

const limited = limitDecimals("123.456789", 4); // "123.4567"
const noLimit = limitDecimals("123.456789"); // "123.456789"

padDecimals​

  • padDecimals(amount: BigNumberish, minDecimals: number): string

Pads decimal places to minimum required.

import { padDecimals } from "@gmx-ui/sdk/utils/numbers";

const padded = padDecimals("123.4", 4); // "123.4000"
const integer = padDecimals("123", 2); // "123.00"

getPlusOrMinusSymbol​

  • getPlusOrMinusSymbol(value?: bigint, opts?: object): string

Parameters​

  • value: bigint - Value to get symbol for
  • opts: object - Options with showPlusForZero property

Returns appropriate plus or minus symbol for a value.

import { getPlusOrMinusSymbol } from "@gmx-ui/sdk/utils/numbers";

const positive = getPlusOrMinusSymbol(100n); // "+"
const negative = getPlusOrMinusSymbol(-100n); // "-"
const zero = getPlusOrMinusSymbol(0n); // ""
const zeroWithPlus = getPlusOrMinusSymbol(0n, { showPlusForZero: true }); // "+"

roundWithDecimals​

  • roundWithDecimals(value: BigNumberish, opts: object): bigint

Parameters​

  • value: BigNumberish - Value to round
  • opts: object - Options with displayDecimals and decimals properties

Rounds value to specified decimal places.

import { roundWithDecimals } from "@gmx-ui/sdk/utils/numbers";

const rounded = roundWithDecimals(123456789n, { displayDecimals: 4, decimals: 8 });

toBigNumberWithDecimals​

  • toBigNumberWithDecimals(value: string, decimals: number): bigint

Converts string value to BigInt with decimals.

import { toBigNumberWithDecimals } from "@gmx-ui/sdk/utils/numbers";

const bigint = toBigNumberWithDecimals("123.456", 18);

bigNumberify​

  • bigNumberify(n?: BigNumberish | null | undefined): bigint | undefined

Safely converts value to BigInt.

import { bigNumberify } from "@gmx-ui/sdk/utils/numbers";

const safe = bigNumberify("123"); // 123n
const invalid = bigNumberify("invalid"); // undefined

parseValue​

  • parseValue(value: string, tokenDecimals: number): bigint | undefined

Parses a string value to BigInt with specified decimals.

import { parseValue } from "@gmx-ui/sdk/utils/numbers";

const parsed = parseValue("123.456", 18);
const invalid = parseValue("invalid", 18); // undefined

roundUpDivision​

  • roundUpDivision(a: bigint, b: bigint): bigint

Performs division with rounding up.

import { roundUpDivision } from "@gmx-ui/sdk/utils/numbers";

const result = roundUpDivision(100n, 3n); // 34n

roundToTwoDecimals​

  • roundToTwoDecimals(n: number): number

Rounds number to two decimal places.

import { roundToTwoDecimals } from "@gmx-ui/sdk/utils/numbers";

const rounded = roundToTwoDecimals(123.456789); // 123.46

roundToOrder​

  • roundToOrder(n: bigint, significantDigits?: number): bigint

Rounds to specified significant digits.

import { roundToOrder } from "@gmx-ui/sdk/utils/numbers";

const rounded = roundToOrder(123456789n, 3); // 123000000n

roundBigIntToDecimals​

  • roundBigIntToDecimals(value: bigint, tokenDecimals: number, roundToDecimals: number): bigint

Rounds BigInt to specific decimal precision.

import { roundBigIntToDecimals } from "@gmx-ui/sdk/utils/numbers";

const rounded = roundBigIntToDecimals(123456789n, 18, 6);

minBigNumber​

  • minBigNumber(...args: bigint[]): bigint | undefined

Returns minimum value from BigInt arguments.

import { minBigNumber } from "@gmx-ui/sdk/utils/numbers";

const min = minBigNumber(100n, 50n, 200n); // 50n

maxbigint​

  • maxbigint(...args: bigint[]): bigint | undefined

Returns maximum value from BigInt arguments.

import { maxbigint } from "@gmx-ui/sdk/utils/numbers";

const max = maxbigint(100n, 50n, 200n); // 200n

removeTrailingZeros​

  • removeTrailingZeros(amount: string | number): string | number

Removes trailing zeros from numeric string.

import { removeTrailingZeros } from "@gmx-ui/sdk/utils/numbers";

const cleaned = removeTrailingZeros("123.000"); // 123

serializeBigIntsInObject​

  • serializeBigIntsInObject(obj: object): object

Serializes BigInt values in object for JSON compatibility.

import { serializeBigIntsInObject } from "@gmx-ui/sdk/utils/numbers";

const obj = { amount: 123n, name: "test" };
const serialized = serializeBigIntsInObject(obj);

deserializeBigIntsInObject​

  • deserializeBigIntsInObject(obj: object): object

Deserializes BigInt values from serialized object.

import { deserializeBigIntsInObject } from "@gmx-ui/sdk/utils/numbers";

const serialized = { amount: { type: "bigint", value: "123" } };
const deserialized = deserializeBigIntsInObject(serialized);

calculateDisplayDecimals​

  • calculateDisplayDecimals(price?: bigint, decimals?: number, visualMultiplier?: number, isStable?: boolean): number

Calculates appropriate number of decimal places to display based on price magnitude.

import { calculateDisplayDecimals, expandDecimals } from "@gmx-ui/sdk/utils/numbers";

const highPrice = expandDecimals(2500, 30);
const decimals = calculateDisplayDecimals(highPrice); // 2

const lowPrice = expandDecimals(1, 27);
const lowDecimals = calculateDisplayDecimals(lowPrice); // 6

clamp​

  • clamp(value: number, min: number, max: number): number

Clamps value between minimum and maximum bounds.

import { clamp } from "@gmx-ui/sdk/utils/numbers";

const clamped = clamp(150, 0, 100); // 100
const inRange = clamp(50, 0, 100); // 50

absDiffBps​

  • absDiffBps(value: bigint, base: bigint): bigint

Calculates absolute difference in basis points.

import { absDiffBps } from "@gmx-ui/sdk/utils/numbers";

const diff = absDiffBps(1050n, 1000n); // 500n (5%)