@mnemoo/currency

Currency formatting helpers for Stake Engine monetary values.

Stake Engine sends money as integers with 6 decimal places of precision. Currency only affects display, so this package keeps gameplay math out of scope and focuses on consistently turning raw API values into readable fiat or virtual-currency strings.

Install

npm install @mnemoo/currency

Quick Start

import {
  convertMultiplierToRawAmount,
  formatCurrency,
  formatAmount,
  formatMultiplierValue
} from "@mnemoo/currency";

formatCurrency(1_000_000, "USD");
// "$1.00"

formatCurrency(10_000, "USD");
// "$0.01"

formatCurrency(100, "USD");
// "$0.0001"

formatCurrency(1, "USD");
// "$0.000001"

formatCurrency(1, "USD", { precision: 3 });
// "$0.001"

formatCurrency(1_000_000, "XSC");
// "1.00 SC"

formatAmount(100_100, "USD");
// "0.1001"

convertMultiplierToRawAmount(1_000_000, "1000x");
// 1000000000n

formatMultiplierValue(1_000_000, "1000x", "USD");
// "$1,000.00"

Money Model

All raw values are scaled by 1_000_000.

| Raw value | Actual amount | | --- | --- | | 100000 | 0.10 | | 1000000 | 1.00 | | 10000000 | 10.00 | | 100000000 | 100.00 | | 1000000000 | 1,000.00 |

Common values:

| Raw value | USD display | | --- | --- | | 1000000 | $1.00 | | 10000 | $0.01 | | 100 | $0.0001 | | 1 | $0.000001 |

Decimal Display Rules

The formatter uses each currency's documented display precision for normal values, but preserves meaningful extra precision for tiny non-zero payouts.

| Raw value | USD output | Why | | --- | --- | --- | | 1_000_000 | $1.00 | Standard 2-decimal fiat display | | 150_000 | $0.15 | No useless trailing zeroes | | 10_000 | $0.01 | Smallest normal 2-decimal bet | | 100 | $0.0001 | Real value would be hidden by 2 decimals | | 1 | $0.000001 | Full raw precision is meaningful |

This avoids both bad extremes:

• Do not show $0.1500 when $0.15 is enough.
• Do not show $0.00 when the player actually received $0.0001.

Pass precision when the UI should cap the number of decimal places. If the raw value has more fractional precision than the cap, it rounds away from zero so tiny non-zero values stay visible.

formatCurrency(1, "USD", { precision: 3 });
// "$0.001"

formatCurrency(100_100, "USD", { precision: 3 });
// "$0.101"

API

formatCurrency(rawAmount, currencyCode, options?)

Formats a raw integer amount with the configured currency symbol and placement.

formatCurrency(1_000_000, "EUR");
// "€1.00"

formatCurrency(1_000_000, "DKK");
// "1.00 KR"

formatAmount(rawAmount, currencyCode, options?)

Formats the numeric portion only, using the same decimal rules.

formatAmount(1_000_000, "USD");
// "1.00"

formatAmount(100, "USD");
// "0.0001"

convertMultiplierToRawAmount(baseBetRawAmount, multiplier, options?)

Converts an x value from a base bet into a raw monetary amount.

Use this when a value is expressed relative to the player's bet, for example a bonus cost of 300x or a payout of 0.01x.

convertMultiplierToRawAmount(1_000_000, 1000);
// 1000000000n

convertMultiplierToRawAmount(1_000_000, "300x");
// 300000000n

convertMultiplierToRawAmount(10_000, "0.01x");
// 100n

formatMultiplierValue(baseBetRawAmount, multiplier, currencyCode, options?)

Converts an x value from a base bet and formats it with the same currency rules as formatCurrency.

formatMultiplierValue(1_000_000, "1000x", "USD");
// "$1,000.00"

formatMultiplierValue(1_000_000, "300x", "USD");
// "$300.00"

formatMultiplierValue(10_000, "0.01x", "USD");
// "$0.0001"

Options

| Option | Type | Default | Description | | --- | --- | --- | --- | | useGrouping | boolean | true | Adds thousands separators, for example $1,000.00. | | includePlusSign | boolean | false | Adds + to positive values, for example +$1.00. | | precision | number | raw precision | Maximum decimal places to display. Extra raw precision rounds away from zero. | | roundingMode | "trunc" \| "floor" \| "ceil" \| "round" | "trunc" | Only used by multiplier helpers when the result falls between raw units. |

Multiplier helpers return integer raw units. If a multiplier result lands between raw units, the default roundingMode truncates toward zero.

convertMultiplierToRawAmount(1, "0.5x");
// 0n

convertMultiplierToRawAmount(1, "0.5x", { roundingMode: "round" });
// 1n

getCurrency(currencyCode)

Returns metadata for a supported currency. The lookup is case-insensitive and throws for unsupported codes.

getCurrency("usd");
// { code: "USD", name: "United States Dollar", symbol: "$", ... }

isSupportedCurrency(currencyCode)

Checks whether a currency code is supported.

isSupportedCurrency("USD");
// true

isSupportedCurrency("BTC");
// false

Constants

import { RAW_PRECISION, RAW_SCALE, SUPPORTED_CURRENCIES } from "@mnemoo/currency";

RAW_PRECISION;
// 6

RAW_SCALE;
// 1000000n

SUPPORTED_CURRENCIES;
// ["USD", "CAD", "JPY", ...]

Raw Amount Inputs

rawAmount can be a number, bigint, or integer string.

Use bigint or string for values larger than Number.MAX_SAFE_INTEGER.

formatCurrency(1_000_000n, "USD");
formatCurrency("1000000", "USD");

Invalid values throw, including decimals like 1.5, NaN, unsupported currencies, and unsafe integer numbers.

Multiplier Inputs

multiplier can be a number, bigint, decimal string, or decimal string with an x suffix.

formatMultiplierValue(1_000_000, 300, "USD");
formatMultiplierValue(1_000_000, 300n, "USD");
formatMultiplierValue(1_000_000, "300", "USD");
formatMultiplierValue(1_000_000, "300x", "USD");
formatMultiplierValue(10_000, "0.01x", "USD");

Multipliers must be non-negative. Use strings for exact decimal multipliers when precision matters.

Supported Currencies

| Code | Symbol | Decimals | Example | | --- | --- | --- | --- | | USD | $ | 2 | $10.00 | | CAD | CA$ | 2 | CA$10.00 | | JPY | ¥ | 0 | ¥10 | | EUR | € | 2 | €10.00 | | RUB | ₽ | 2 | ₽10.00 | | CNY | CN¥ | 2 | CN¥10.00 | | PHP | ₱ | 2 | ₱10.00 | | INR | ₹ | 2 | ₹10.00 | | IDR | Rp | 0 | Rp10 | | KRW | ₩ | 0 | ₩10 | | BRL | R$ | 2 | R$10.00 | | MXN | MX$ | 2 | MX$10.00 | | DKK | KR | 2 | 10.00 KR | | PLN | zł | 2 | 10.00 zł | | VND | ₫ | 0 | 10 ₫ | | TRY | ₺ | 2 | ₺10.00 | | CLP | CLP | 0 | 10 CLP | | ARS | ARS | 2 | 10.00 ARS | | PEN | S/ | 2 | S/10.00 | | NGN | ₦ | 2 | ₦10.00 | | SAR | SAR | 2 | 10.00 SAR | | ILS | ILS | 2 | 10.00 ILS | | AED | AED | 2 | 10.00 AED | | TWD | NT$ | 2 | NT$10.00 | | NOK | kr | 2 | kr10.00 | | KWD | KD | 2 | KD10.00 | | JOD | JD | 2 | JD10.00 | | CRC | ₡ | 2 | ₡10.00 | | TND | TND | 2 | 10.00 TND | | SGD | SG$ | 2 | SG$10.00 | | MYR | RM | 2 | RM10.00 | | OMR | OMR | 2 | 10.00 OMR | | QAR | QAR | 2 | 10.00 QAR | | BHD | BD | 2 | BD10.00 | | XGC | GC | 2 | 10.00 GC | | XSC | SC | 2 | 10.00 SC |