ERC-20 token decimals: turn a raw balance into a readable amount

To convert a raw ERC-20 balance into a readable token quantity, divide the integer by 10 raised to the token’s verified decimals. Do this only if the value is still in raw base units. A wallet or explorer may have performed the conversion already.

For example, a raw balance of 1234567 with 6 decimals represents 1.234567 tokens. The same raw integer with 18 decimals represents 0.000000000001234567 tokens. Neither result tells you a dollar value. These are hypothetical arithmetic examples, not balances queried from a wallet.

What decimals change when you read a balance

An ERC-20 contract’s balanceOf method returns an integer. The ERC-20 specification describes decimals as the scale for presenting a token amount to a user. Think of the integer as a count of the token’s smallest accounting units, with decimals telling the display where to put the decimal point.

The calculation is:

Readable token quantity = raw integer divided by (10 raised to decimals).

In this article, every raw integer is written in base 10, with no thousands separators. A hexadecimal value beginning with 0x needs to be decoded as an integer first. The letters and digits in that encoding are not a decimal token quantity you can copy into this division unchanged.

Here is the same hypothetical integer under three different scales:

Raw integer	Decimals	Token quantity
1234567	6	1.234567
1234567	18	0.000000000001234567
1234567	0	1234567

With 0 decimals, the divisor is 1. With 6 decimals, one whole token corresponds to 1000000 raw units. With 18, it corresponds to 1000000000000000000 raw units. The size of the integer alone cannot tell you which scale applies.

Establish the scale before calculating

Start with the network and full token contract address. A symbol is a label, not a unique identifier. If you are unsure which address belongs to the token and which belongs to the holder, use the wallet address and token contract guide first.

Use the project’s official deployment information for that network to establish the contract identity. Then inspect its read-only decimals result through a trusted explorer or contract reader. Record the result alongside the contract and network. Metadata read from a different deployment does not settle the scale for your holding.

Do not fill a missing decimals value with 18. ERC-20 makes the method optional. OpenZeppelin’s ERC20 reference documents a default of 18 in its implementation, which can be overridden. That implementation default is not a universal token rule. The same reference explains that decimals serve display formatting; they do not change the contract’s integer balance and transfer arithmetic.

If the read fails, distinguish an unavailable source from a contract that does not expose usable metadata. Try a trusted source for the same deployment or check its documented implementation. If the scale remains unestablished, preserve the raw integer and label the readable quantity unresolved. A plausible-looking number is not a verified conversion.

Check whether the number is already formatted

Before applying the formula, read the field label and the source’s documentation. A raw contract result, an API’s normalized quantity and a wallet’s rounded display can all describe the same holding differently. A decimal point suggests formatting, but the absence of one does not prove a value is raw: a formatted amount can be exactly 2 tokens.

For a hypothetical 6-decimal token, raw 2500000 becomes 2.5 tokens. If your wallet already shows 2.5 tokens, dividing that displayed figure by 1000000 produces 0.0000025, an incorrect second conversion.

Once you have the exact token quantity, apply display rounding separately. Raw 1 with 6 decimals is 0.000001 tokens. An interface limited to 4 decimal places may show 0.0000. That rounded label does not establish an empty balance. Keep the precise result available when investigating a discrepancy, without inventing extra meaningful digits beyond the source’s precision.

For a script or spreadsheet, preserve the raw integer as text or an exact integer until formatting. Large integers can lose precision in an ordinary JavaScript Number, as MDN’s safe-integer reference explains; division cannot recover precision already lost. The ethers v6 documentation provides formatUnits, which returns a decimal string. Pass the verified decimals explicitly, and keep that string rather than converting it into an imprecise number for convenience.

Reconcile two readings without moving tokens

Use one holding for the check. Reading public contract data does not require a transfer, approval, recovery phrase or wallet signature.

1. Fix the identity. Record the network, public holder address and verified token contract. Do not substitute the contract address for the holder when reading its balance.
2. Record the observation. Keep the time and block number where available. Prefer readings from the same block; otherwise a transfer between observations can prevent an exact match.
3. Label the inputs. Save the original value, whether it is raw or formatted, and the evidence for the contract’s decimals. If a source does not explain its units, stop the conversion there.
4. Scale once. Convert the raw integer using those decimals, retaining exact digits before any display rounding. Leave a quantity already supplied in token units as it is.
5. Compare like units. Compare that token quantity with the other screen’s token quantity at compatible precision. For a rounded zero, request more detail before concluding the raw balance is zero.
6. Handle the remaining gap. If identity, snapshot and units match but quantities still disagree, record both readings and their sources. If a source failed, mark the reading unavailable rather than inserting zero. The portfolio discrepancy guide covers missing source responses, prices and position coverage.

The useful result is a record another person can reproduce: which contract, whose balance, which observation, what raw value, which decimals and what converted quantity. A transaction is not part of proving the conversion.

Keep token quantity separate from value

Formatting gives you a count of this token. A dollar estimate additionally needs a price for that exact asset, in a stated currency and at a stated time. Decimals do not establish that price, trading liquidity or contract safety. An unfamiliar token can return a perfectly ordinary decimals value.

A receipt or wrapper token introduces another question: how much underlying asset does each token represent? Converting its raw balance gives you receipt or wrapper tokens. Any underlying-asset equivalent needs the relevant protocol’s conversion method and units. A token’s decimals cannot replace that exchange rate, and a protocol ratio such as a health factor needs its own documented scaling.

When the number still looks wrong, retain the unknown that matters. Unknown decimals leave the readable quantity unresolved. A known quantity with an unknown price leaves valuation unresolved. Keeping those gaps explicit gives you a useful next check without changing the holding you are trying to understand.