Token decimals set the scale for swaps and payouts

Token decimals tell an interface how to convert a displayed amount into the integer a token contract receives: with 6 decimals, 1.25 tokens is 1,250,000 base units. OpenZeppelin’s ERC-20 documentation says this setting affects display, while contract arithmetic and transfers use integers. A swap or payout can therefore go wrong if the amount is scaled for the wrong token.

How do token decimals turn a balance into an amount?

Divide a token’s raw balance by 10 raised to its decimals to display it; multiply a displayed amount by the same factor to create the raw integer for a transfer. OpenZeppelin gives the example that, with 2 decimals, a raw balance of 505 displays as 5.05 tokens. For an 18-decimal token, one whole token is 1,000,000,000,000,000,000 base units.

ERC-20’s standard makes the decimals() method optional, according to the Ethereum improvement proposal, so an integration should not assume every token returns it. OpenZeppelin sets 18 as its implementation’s default, but that is not a universal rule. A payout form should read the token’s supported metadata or use a verified token configuration, then convert with that token’s scale.

For a practical look at how route choice changes a trade, Byreal’s guide to swaps and concentrated liquidity covers the decision in more detail. The same discipline applies whichever route is used: establish the token and its scale before encoding an amount.

How should decimals be handled in a swap?

Convert the input and output with their own decimal counts; never reuse the input token’s scale for the other side. If a quote is 2.5 units of a 6-decimal output token, the raw output is 2,500,000, regardless of whether the input token uses 18 decimals. The human-readable exchange rate also depends on both scales.

• Confirm the token contract or verified asset record, not only its ticker symbol.
• Read the decimals for each asset separately.
• Convert user-entered amounts to integer base units before submitting a transaction.
• Display the quoted output using the output token’s decimals.

OpenZeppelin’s documentation notes that ERC-20 balances and transfers are integer values. In practice, keep calculations in integer or exact-decimal arithmetic through conversion; ordinary floating-point values can lose precision when a large raw integer is represented approximately. Show a rounded figure for readability, but retain the exact integer used in the transaction.

What should you check before a payout?

Check the raw amount after conversion and before signing: it should represent the intended human amount when divided by 10 raised to the token’s decimals. A one-place scale error changes the payment by a factor of ten; using the wrong token’s scale can make the difference much larger or smaller. This follows directly from the conversion rule OpenZeppelin documents.

Rounding matters when a requested amount has more fractional digits than the token can represent. A token with 6 decimals cannot encode a seventh fractional digit as a whole base unit. Decide whether to reject the extra precision or apply a stated rounding rule, then show the final amount and token symbol before the user approves.

The useful rule is simple: identify the asset, get its decimal scale, convert to an integer, and verify the displayed result. Decimals change how an amount is written, not the amount the contract counts.