---
url: https://game-engine-io.github.io/enginex-frontend-sdk/concepts/money.md
---
# Money

The SDK moves every monetary value in **minor units**, as integers: `1999` is R$ 19.99 (a currency
with 2 decimal places). There is never a `number` with decimal places in the API, so balances and limits add up with no
floating-point error. The operator's currency (with `decimalPlaces`) comes from `config.get()`.

## What is validated in the response

Monetary fields coming from the gateway (in the core and in the product packages) go through a
**strict** check:

* the value is a **safe integer** (up to `Number.MAX_SAFE_INTEGER`), as a number or as text; a value from
  2^53 upward never arrives rounded;
* the currency is an ISO code of three uppercase letters (`/^[A-Z]{3}$/`);
* `decimalPlaces` is an integer from 0 to 8.

A field outside that rejects the **entire response** with `VALIDATION_ERROR`, **even in
`validation: 'warn'`** (the default): this also applies to items inside lists, maps and unions, and to the
balance that arrives through realtime. In `'warn'` the remaining fields stay tolerant (a new enum becomes
`onValidationIssue`), but wrong money is never delivered to the app. A gateway out of contract shows up
as an error, not as a wrong balance. Product packages reuse the same checks through
`money`, `moneyText`, `currencyCode` and `decimalPlaces` from `@getenginex/sdk/extension`.

Not everything is money. **Price, quantity and percentage are not validated as money**: Predictions
prices and quantities, fees in basis points (bps), loyalty points and mission progress
follow the common validation. The Predictions market aggregates and limits (`volume_24h`, `total_volume`,
`min_order_size`, `max_position`) are left out of the strict check by decision (market aggregates and limits,
in cents) and also follow the common validation.

An empty currency (`''`) is accepted only where the gateway omits it because the amount is zero: in bonus campaign values, in the
`currency` of loyalty redemption and in the `settlement_currency` of Predictions. In any other monetary
field, `''` rejects the response. The `config.currencies` list is free text and does not go through this check.

## Conversion helpers

Three helpers convert to and from what the user sees and types:

```ts
import { formatMoney, fromMinorUnits, toMinorUnits } from '@getenginex/sdk'

const { currency } = await enginex.config.get() // { code: 'BRL', symbol: 'R$', decimalPlaces: 2, ... }

formatMoney(123456, currency, 'pt-BR') // 'R$ 1.234,56'
toMinorUnits('1.234,56', currency) // 123456
toMinorUnits(19.99, currency) // 1999 (19.99 * 100 would give 1998.9999999999998)
fromMinorUnits(1999, currency) // 19.99
```

## `formatMoney(amountMinor, currency, locale?)`

Uses `Intl.NumberFormat` with the currency's ISO code and the `decimalPlaces` places. Accepts negatives
(statements). Without `locale`, the runtime's applies; in SSR (Next.js, Nuxt), pass the same `locale` on the
server and in the browser to avoid a hydration mismatch.

## `toMinorUnits(value, currency)`

Converts the text of a field (`'12,50'`, `'1.234,56'`, `'1,234.56'`) or a `number` into minor
units. The text is read digit by digit, without multiplying a `number`, and:

* with more decimal places than the currency has, it **rounds half up** on the given value
  (`'1.0050'` becomes `101`);
* with `.` and `,` together, the last one is the decimal separator (`'1.234,56'`); a single separator that appears
  once is the decimal (`'1.5'`, `'12,50'`); repeated, it is a thousands separator (`'1.234.567'`);
* a single separator followed by exactly 3 digits (`'1.000'`, `'1,000'`, `'10.500'`) is
  **ambiguous** and throws `RangeError`, except in a 3-decimal currency (there it is a decimal);
* it **rejects** negatives, empty or non-numeric text, `NaN`, infinity and values above the largest safe
  integer, throwing `RangeError`.

::: warning Values like '1.000' are refused
In pt-BR `1.000` is one thousand and in en-US it is one: converting silently could undervalue by a factor of 1000. That is
why the SDK throws instead of guessing. Pass a `number`, or an unambiguous string: with both
separators (`'1.000,00'`) or without thousands (`'1000'`). If the app reads a text field, normalize it (or
use a numeric input) before calling `toMinorUnits`.
:::

A `number` is never ambiguous, but it only carries what JavaScript can represent.

## `fromMinorUnits(amountMinor, currency)`

Returns the major unit as a `number` (`1999` becomes `19.99`), useful for filling in an
edit field. To show money to the user, use `formatMoney`. Since it is a `number`, beyond ~15 significant
digits the decimal places are no longer representable.

All three throw `RangeError` on out-of-contract input (a non-integer value in minor units
or an invalid `decimalPlaces`).
