Pass token amounts as integer strings in the token’s smallest unit.
Definition
A human-readable amount includes the decimal point users see in wallets. A smallest unit amount is the integer value sent to APIs and contracts.
smallest_unit = human_readable_amount * 10^decimals
Decision Table
| Product | Where to read decimals | Amount fields |
|---|
| MultiversX Aggregator | /api/v1/pair-config | amountIn, amountOut, amountOutMin |
| Stellar Aggregator | /api/v1/tokens | amount_in, amount_out, amountIn, amountOut |
| Relayer and Gateway transactions | Token metadata or chain rules | value, ESDT transfer amounts, contract args |
Worked Example
Convert 1 WEGLD with 18 decimals:
const human = "1";
const decimals = 18n;
const smallest = BigInt(human) * 10n ** decimals;
console.log(smallest.toString()); // "1000000000000000000"
const human = "100";
const decimals = 6n;
const smallest = BigInt(human) * 10n ** decimals;
console.log(smallest.toString()); // "100000000"
Edge Cases
| Case | Risk | Fix |
|---|
| Floating-point conversion | JavaScript number can round large values. | Use BigInt, decimal libraries, or string parsers. |
| Assumed decimals | Tokens can use different precisions. | Read decimals from the product endpoint before quoting. |
| Human-readable amount sent to API | Quote amount is off by powers of ten. | Convert before request construction. |
| Scientific notation | APIs expect integer strings. | Serialize as base-10 strings without e. |
Do not send human-readable amounts to quote endpoints. A decimal mistake can build a transaction for the wrong value.
Verify
Before signing or broadcasting, compare:
- The input token decimals from metadata.
- The integer string sent in the request.
- The displayed human-readable amount in your UI.
- The returned
amountOut or amountIn converted back with output decimals.
