Reference
Amounts and decimals
How token amounts are represented across the API, notifications, and Proof-of-Payment.
Tekmerion represents on-chain token amounts in the token's smallest indivisible unit. This page fixes that representation, how to convert to a human-readable figure, and where amounts appear.
Representation
| Rule | Statement |
|---|---|
| Unit | On-chain token amounts are expressed in base units — the token's smallest indivisible unit — not in whole-token decimals. |
| Encoding | A base-unit amount is a non-negative integer rendered as a decimal string, to preserve exact precision beyond the range of a floating-point number. |
| No floats | An amount MUST NOT be parsed into a binary floating-point type before conversion; doing so silently loses precision for large balances. Use an arbitrary-precision integer or decimal type. |
Decimals per token
Each token has a fixed number of decimals that defines how base units map to whole tokens.
| Aspect | Rule |
|---|---|
| Source | The decimals for each supported token are published in Supported chains and tokens. Do not assume a uniform value across tokens. |
| Human-readable conversion | display_amount = base_units / 10^decimals. |
| Reverse | base_units = round(display_amount × 10^decimals) — see rounding below. |
Where amounts appear
The same base-unit representation is used on every surface that carries a token amount.
| Surface | Amounts carried |
|---|---|
| API | Expected and observed token amounts on payment and quote resources, in base units. |
| Notifications | Notification payloads carry correlation and outcome fields; token figures, when surfaced, follow the same base-unit representation. See Payload envelope. |
| Proof-of-Payment | The data payload records the deposited amount, the settled amount, and the protocol fee collected on-chain — all as on-chain base-unit quantities. See Artifact contents. |
Rounding in the quote
A quote snapshot converts a merchant's base amount into the amount a customer pays in the chosen token. The conversion resolves to a whole number of base units.
| Rule | Statement |
|---|---|
| Where rounding happens | Rounding to base units happens once, when the quote snapshot is created. The rounded base-unit amount is the canonical expected amount for any attempt that binds to that snapshot. |
| Immutability | A quote snapshot is immutable: its rate and resulting amount never change after creation. A new selection or an expired window requires a fresh quote, not a re-rounding. See Quotes. |
| Amount is not a matching criterion | The expected amount fixed by the quote does not gate settlement. A deposit is correlated by address, chain, and token — not by amount — and settlement acts on the full balance present at the deposit_address. The consequences of paying more or less than expected are in Edge cases. |