Token Decimals and Exact Amount Arithmetic
Convert token base units into display amounts using exact arithmetic, preserve raw integers, and avoid rounding errors in balances and reconciliation.
Overview
When translating these concepts into an integration, keep the scope described by the historical balance api with the result. The examples in historical token balances and blockchain data reconciliation show how the same distinction affects neighbouring data questions.
Token quantities are commonly stored as integers in base units. Decimals specify a display scale. They do not justify converting a large integer into an imprecise floating-point value before calculation.
Separate storage from presentation
Keep the raw integer and verified decimals together with the asset identity. Perform addition and subtraction in compatible base units. Apply a decimal scale only for display or a deliberately chosen decimal calculation. Tokens with different decimals cannot be aggregated merely because their symbols match. Missing decimals should remain an explicit metadata problem.
Worked example: six decimal places
A raw amount of 1234567 with six decimals represents 1.234567 units. Adding raw 200000 yields raw 1434567, or 1.434567 units. Format by splitting or scaling exact integers; do not pass through a rounded binary floating-point representation. Retain full precision even if the UI initially displays only two decimal places.
Test precision boundaries
Include amounts larger than the JavaScript safe integer range, zero-decimal tokens and very small nonzero balances. Define rounding separately for display, valuation and exports. A displayed 0.00 must not overwrite the underlying nonzero quantity. If metadata changes or a decoder correction occurs, preserve which scale was applied to the original derived value.
A practical acceptance test
Round-trip raw 9007199254740993 with a declared decimal scale and compare the final raw string byte-for-byte. Include a small nonzero amount whose two-decimal display is 0.00. Exporting or reimporting the display must not overwrite the exact holding. Test addition in base units independently from the formatting routine.
Questions about the topic
Frequently asked questions
Do all tokens use eighteen decimals?
No. Decimal scales vary and some token interfaces may omit this metadata.
Should a rounded display value be stored as the balance?
No. Preserve exact raw quantities and apply display rounding separately.
Standards & technical documentation
