Token decimals tell software how to translate an integer balance into a human-readable token amount. Token supply tells you how many units exist under a specified definition. Changing the scale of a number and changing the quantity represented are different operations.
This difference becomes practical when a wallet shows 123.456789 tokens while a contract query returns 123456789. Those values can describe exactly the same balance if the token uses six decimals.
This guide focuses on ERC-20-style token accounting: converting balances, reconciling a transfer, and protecting precision in an export. It does not assume that every token uses eighteen decimals or that a familiar ticker uniquely identifies the contract.
What token decimals actually mean
For a token with d decimals, one displayed token corresponds to 10 raised to d raw units. Divide a raw balance by that scale to display tokens. Multiply a displayed amount by the scale to obtain the integer quantity used for a transfer.
The ERC-20 standard defines separate functions for balances, total supply, and optional decimals metadata. The fact that decimals is optional matters: an integration should not silently treat missing metadata as a verified value of eighteen.
With zero decimals, one raw unit is one displayed token. With two decimals, 100 raw units are one token. With six decimals, the scale is 1,000,000. This is a unit convention, not a statement about price, scarcity, legitimacy, or the holder’s economic rights.
OpenZeppelin’s ERC-20 documentation makes the display distinction explicit: integer balances remain the basis of the contract’s arithmetic, while interfaces apply the decimal scale.
Worked example: reconcile a six-decimal transfer
Assume a fictional token named SAMPLE has six decimals. A verified contract query shows an opening balance of 123456789 raw units. We assume ordinary transfer behavior, with no token transfer fee, rebase, or other balance-changing event.
- Convert the opening balance: 123456789 ÷ 1,000,000 = 123.456789 SAMPLE.
- Convert a transfer of 2.500001 SAMPLE: 2.500001 × 1,000,000 = 2500001 raw units.
- Subtract in integer units: 123456789 − 2500001 = 120956788.
- Convert the remainder: 120956788 ÷ 1,000,000 = 120.956788 SAMPLE.
Now reconcile in displayed units: 123.456789 − 2.500001 = 120.956788. The two paths agree because both used the same scale and preserved every digit.
The token transfer amount is separate from any network fee paid in the chain’s native asset. A reduction in that native-asset balance should not be inserted into the SAMPLE calculation as though both quantities used the same unit.
If the actual token charges a transfer fee or changes balances through another mechanism, the simple subtraction may no longer explain the recipient’s amount. Verify contract behavior rather than treating the arithmetic assumption as a universal token rule.
Token decimals do not create additional token supply
Imagine two independent hypothetical tokens, each with a displayed total supply of 25,000,000 tokens. Token A uses six decimals, so its raw total is 25,000,000,000,000 units. Token B uses eighteen decimals, so its raw total is 25,000,000,000,000,000,000,000,000 units.
The second raw integer is much larger because it counts smaller units. It does not establish that B has more displayed tokens or a greater economic value. Comparing the raw integers without their scales is like comparing millimeters with kilometers while ignoring the labels.
This example compares different hypothetical token designs. It is not a claim that changing the decimals metadata of an existing token is harmless. A metadata change can cause interfaces and integrations to interpret existing raw balances differently.
Supply questions also require a defined boundary. The separate guide to circulating, total, and maximum supply handles those distinctions. Here the necessary first step is simply to express every supply figure in compatible units.
Precision is different from what a wallet chooses to show
A wallet may round 123.456789 to 123.46 for readability. That display choice does not prove that the underlying balance has only two decimal places. An export may preserve more precision than the headline number.
Suppose someone enters 1.23456789 for a six-decimal token. Multiplying by 1,000,000 gives 1234567.89, which is not an integer raw amount. The request cannot be represented exactly at that scale.
Rounding to six decimal places produces 1.234568. Truncating produces 1.234567. These are different amounts, even though both may look similar on a small screen. The difference between the rounded result and the original request is 0.00000011 tokens; the truncated result is 0.00000089 lower.
A careful interface should make its precision rule explicit. For a research spreadsheet, preserve the original value, the accepted precision, and any applied rounding. Do not let formatting silently become a change to the amount being analyzed.
Protect integer values when moving between tools
Large raw integers can lose precision if imported into a field that stores only a limited number of significant digits. Scientific notation may make the loss harder to notice. Keep an untouched text representation of the raw value as part of the evidence.
For exact calculation, use tools that support arbitrary-precision integers or decimal arithmetic with an explicit scale. The ethers unit-conversion documentation distinguishes decimal strings for human-facing values from integer quantities for program use. Its parseUnits and formatUnits functions accept an explicit decimal convention.
A round-trip test is helpful: convert the raw value to a decimal string and back using the same scale. The recovered raw integer should equal the original exactly. If it does not, investigate rounding, an incorrect scale, or a field-type conversion before using the result.
For example, applying eighteen decimals to the six-decimal raw balance 123456789 produces 0.000000000123456789 rather than 123.456789. The error factor is one trillion. A small-looking display error can therefore originate from a simple metadata mismatch.
A token decimals verification checklist
- Identify the asset: record network and verified contract address, not only the symbol.
- Verify the scale: record the decimals source and whether the value was queried, documented, or assumed.
- Keep the raw amount: retain every integer digit before formatting.
- Label the displayed amount: specify the token unit and applied precision.
- Match the observation: use compatible block references for balance and supply comparisons.
- Explain special behavior: note any transfer fees, rebasing, or conversion rules relevant to the calculation.
The network versus token guide explains why an asset label does not identify a unique environment. Two similarly named contracts can use different decimal scales, and a representation on another network may need its own verification.
When two balances disagree, work backward from identity, scale, and timestamp before assuming tokens have been created or lost. Those checks often reveal whether the disagreement is economic or simply presentational.
Frequently asked questions
Do all ERC-20 tokens use eighteen decimals?
No. Eighteen is a common implementation choice, but it is not a universal token identity rule. Verify the specific contract and metadata. If the decimals function is absent or unreliable, record the uncertainty instead of silently applying a default.
Do more token decimals mean a larger supply?
Not necessarily. More decimals mean more raw units per displayed token. Compare normalized supply amounts under the same supply definition. A larger raw integer can represent exactly the same displayed quantity when the scale is correspondingly larger.
Can a token have zero decimals?
Yes. Under a zero-decimal convention, one raw unit corresponds to one displayed token, so fractional displayed amounts are not representable through that scale. An interface showing extra zeros after the decimal point does not create smaller transferable units.
Why does my wallet round a balance that an explorer shows precisely?
The wallet may prioritize readability and hide low-order digits. That is a presentation choice, not evidence that the raw balance changed. Inspect the full precision or verified contract value when reconciling a transfer or comparing two services.
How do I convert a displayed amount to raw units?
Multiply by ten raised to the verified decimals value, preserving exact decimal arithmetic. The result must be an integer. If it is not, the requested amount has more fractional precision than the token scale can represent.
Are raw token units always called wei?
Wei is the smallest named unit of Ethereum’s native ether. An ERC-20 token’s raw units belong to that token’s own accounting convention. Calling every raw token amount wei can obscure a different decimal scale and create conversion mistakes.
Can I compare raw balances of two different tokens?
Only as raw integers, which usually answers little economically. Normalize each with its own scale before comparing displayed quantities, and remember that equal quantities of different tokens do not imply equal prices, rights, or underlying value.
Does totalSupply return the same number a website displays?
An ERC-20 contract returns an integer quantity. A website may apply the decimal scale and may also choose a different supply boundary. Check both the normalization and the field’s definition before concluding that the website contradicts the contract.
Why should a CSV preserve raw amounts as text?
A text field can preserve the original digits when spreadsheet software would otherwise round a large integer or convert it automatically. Keep that evidence column alongside an explicitly calculated display column, then verify that a round-trip conversion recovers the original.
Does changing token decimals metadata mint or burn tokens?
The metadata by itself describes how raw units are displayed; minting and burning involve changes to token accounting. However, changing the scale can disrupt how existing balances are presented or interpreted, so do not assume such a change has no practical consequences.
Explore the CrowdSent platform overview if you want to learn more about its approach to market research.
Educational information only. Examples are hypothetical and are not investment recommendations.