Token Decimals

Overview

Why Token Decimals matters

Smart contracts and blockchain software generally use integers rather than floating-point numbers for token balances. Decimal metadata tells a wallet how to present those integers to people. Payment systems must convert accurately in both directions; mistakes can result in very large underpayments or overpayments.

How it works

Suppose a token uses six decimals. A displayed balance of 12.345678 tokens corresponds to 12,345,678 smallest units. The calculation is displayed amount = raw integer / 10^6. A token with eighteen decimals would represent the same displayed amount with a much larger raw integer. ERC-20-style tokens commonly expose a decimals method, but implementations differ and not all interfaces should be trusted blindly. When preparing an invoice, software should look up the expected token's trusted contract and apply its precision rules, avoid binary floating-point rounding and validate minimum transaction increments. Transfer logs typically report integer amounts, so automated reconciliation must normalize values before comparing them with the human-readable invoice.

A safe way to calculate invoice amounts

Financial code should calculate with integers or exact decimal arithmetic. For a six-decimal token, multiplying 1.234567 by one million yields 1,234,567 base units; values requiring more than six fractional places must be rejected or rounded under an explicit documented policy. If a system uses binary floating-point, numbers that appear exact to a human can become slightly different internally and cause failed comparisons. When reconciling a transfer, compare expected raw units with the event's raw amount before formatting it for display. This also helps with partial payments, where several integer transfer amounts are added. The merchant's fiat quote is yet another layer: fiat-to-token conversion needs a timestamped rate, supported rounding rule and tolerance policy. Token decimals describe representation, not the exchange-rate calculation itself.

A real-world payment example

A shop expects 25.50 units of a token with six decimals. It should check for exactly 25,500,000 smallest units, subject to its explicitly documented payment tolerance. If a developer incorrectly assumes eighteen decimals, the computed raw amount differs by a factor of one trillion. That is not a minor display bug: the checkout might demand an impossible payment or credit the wrong amount.

Limits and common misunderstandings

The symbol and name of a token do not establish its decimal count. The decimals field can be implemented unusually or changed in a nonstandard upgradable system. Use token-specific verified metadata and integer arithmetic; do not cast money values to imprecise floating-point types in critical accounting code.

How it differs from related concepts

Decimals define denomination scaling. Price is market exchange value. Gas units and native-chain coin denominations follow their own rules and are not a substitute for token precision.

Explore further

Official background: technical documentation.

Related glossary terms: ERC-20, Token Contract Address, Payment Amount.