Evm Token Decimals

by affaan-mef648e01899ba3e8dc6371642deaaf64b4477775No license275K starsListed Oct 9, 2026Updated Oct 9, 2026Repository updated 4 days ago

Prevent silent decimal mismatch bugs across EVM chains. Covers runtime decimal lookup, chain-aware caching, bridged-token precision drift, and safe normalization for bots, dashboards, and DeFi tools. Use when handling token amounts across EVM chains, or when a balance, price, or transfer amount is off by orders of magnitude.

Instructions onlySoftware Development

AI-generated overview

Guidance for reading ERC-20 token decimals correctly across EVM chains to avoid silent decimal mismatch bugs.

What it does: Explains how to query an ERC-20 token's decimals() at runtime instead of assuming fixed values, and how to cache results by chain ID and token address. Provides code examples in Python, TypeScript, and Solidity for balance reads, decimal-safe math, fallback handling, and normalization to 18-decimal WAD. Also lists rules such as re-querying decimals after bridging or wrapper changes.
When to use it: Use when reading ERC-20 balances, computing fiat values from on-chain amounts, comparing token amounts across multiple EVM chains, or handling bridged assets. Also relevant when a balance, price, or transfer amount appears off by orders of magnitude.
Requirements: No scripts are shipped; it is instructions and code examples only. Examples reference Python with web3 and decimal, TypeScript with ethers, Solidity, and the cast CLI, plus RPC access to an EVM chain.

EVM Token Decimals

Silent decimal mismatches are one of the easiest ways to ship balances or USD values that are off by orders of magnitude without throwing an error.

When to Use

Reading ERC-20 balances in Python, TypeScript, or Solidity
Calculating fiat values from on-chain balances
Comparing token amounts across multiple EVM chains
Handling bridged assets
Building portfolio trackers, bots, or aggregators

How It Works

Never assume stablecoins use the same decimals everywhere. Query decimals() at runtime, cache by (chain_id, token_address), and use decimal-safe math for value calculations.

Examples

Query decimals at runtime

python

from decimal import Decimalfrom web3 import Web3
ERC20_ABI = [    {"name": "decimals", "type": "function", "inputs": [],     "outputs": [{"type": "uint8"}], "stateMutability": "view"},    {"name": "balanceOf", "type": "function",     "inputs": [{"name": "account", "type": "address"}],     "outputs": [{"type": "uint256"}], "stateMutability": "view"},]
def get_token_balance(w3: Web3, token_address: str, wallet: str) -> Decimal:    contract = w3.eth.contract(        address=Web3.to_checksum_address(token_address),        abi=ERC20_ABI,    )    decimals = contract.functions.decimals().call()    raw = contract.functions.balanceOf(Web3.to_checksum_address(wallet)).call()    return Decimal(raw) / Decimal(10 ** decimals)

from decimal import Decimalfrom web3 import Web3
ERC20_ABI = [    {"name": "decimals", "type": "function", "inputs": [],     "outputs": [{"type": "uint8"}], "stateMutability": "view"},    {"name": "balanceOf", "type": "function",     "inputs": [{"name": "account", "type": "address"}],     "outputs": [{"type": "uint256"}], "stateMutability": "view"},]
def get_token_balance(w3: Web3, token_address: str, wallet: str) -> Decimal:    contract = w3.eth.contract(        address=Web3.to_checksum_address(token_address),        abi=ERC20_ABI,    )    decimals = contract.functions.decimals().call()    raw = contract.functions.balanceOf(Web3.to_checksum_address(wallet)).call()    return Decimal(raw) / Decimal(10 ** decimals)

Do not hardcode 1_000_000 because a symbol usually has 6 decimals somewhere else.

Cache by chain and token

python

from functools import lru_cache
@lru_cache(maxsize=512)def get_decimals(chain_id: int, token_address: str) -> int:    w3 = get_web3_for_chain(chain_id)    contract = w3.eth.contract(        address=Web3.to_checksum_address(token_address),        abi=ERC20_ABI,    )    return contract.functions.decimals().call()

from functools import lru_cache
@lru_cache(maxsize=512)def get_decimals(chain_id: int, token_address: str) -> int:    w3 = get_web3_for_chain(chain_id)    contract = w3.eth.contract(        address=Web3.to_checksum_address(token_address),        abi=ERC20_ABI,    )    return contract.functions.decimals().call()

Handle odd tokens defensively

python

try:    decimals = contract.functions.decimals().call()except Exception:    logging.warning(        "decimals() reverted on %s (chain %s), defaulting to 18",        token_address,        chain_id,    )    decimals = 18

try:    decimals = contract.functions.decimals().call()except Exception:    logging.warning(        "decimals() reverted on %s (chain %s), defaulting to 18",        token_address,        chain_id,    )    decimals = 18

Log the fallback and keep it visible. Old or non-standard tokens still exist.

Normalize to 18-decimal WAD in Solidity

solidity

interface IERC20Metadata {    function decimals() external view returns (uint8);}
function normalizeToWad(address token, uint256 amount) internal view returns (uint256) {    uint8 d = IERC20Metadata(token).decimals();    if (d == 18) return amount;    if (d < 18) return amount * 10 ** (18 - d);    return amount / 10 ** (d - 18);}

interface IERC20Metadata {    function decimals() external view returns (uint8);}
function normalizeToWad(address token, uint256 amount) internal view returns (uint256) {    uint8 d = IERC20Metadata(token).decimals();    if (d == 18) return amount;    if (d < 18) return amount * 10 ** (18 - d);    return amount / 10 ** (d - 18);}

TypeScript with ethers

typescript

import { Contract, formatUnits } from 'ethers';
const ERC20_ABI = [  'function decimals() view returns (uint8)',  'function balanceOf(address) view returns (uint256)',];
async function getBalance(provider: any, tokenAddress: string, wallet: string): Promise<string> {  const token = new Contract(tokenAddress, ERC20_ABI, provider);  const [decimals, raw] = await Promise.all([    token.decimals(),    token.balanceOf(wallet),  ]);  return formatUnits(raw, decimals);}

import { Contract, formatUnits } from 'ethers';
const ERC20_ABI = [  'function decimals() view returns (uint8)',  'function balanceOf(address) view returns (uint256)',];
async function getBalance(provider: any, tokenAddress: string, wallet: string): Promise<string> {  const token = new Contract(tokenAddress, ERC20_ABI, provider);  const [decimals, raw] = await Promise.all([    token.decimals(),    token.balanceOf(wallet),  ]);  return formatUnits(raw, decimals);}

Quick on-chain check

Rules

Always query decimals() at runtime
Cache by chain plus token address, not symbol
Use Decimal, BigInt, or equivalent exact math, not float
Re-query decimals after bridging or wrapper changes
Normalize internal accounting consistently before comparison or pricing

Source and attribution

Source:affaan-m/ECCinskills/evm-token-decimalsat commitef648e0

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Evm Token Decimals

EVM Token Decimals

When to Use

How It Works

Examples

Query decimals at runtime

Cache by chain and token

Handle odd tokens defensively

Normalize to 18-decimal WAD in Solidity

TypeScript with ethers

Quick on-chain check

Rules

Source and attribution

More from affaan-m/ECC

Unified Notifications Ops

Verification Loop

Ui To Vue

Unified Memory

Visa Doc Translate

Team Builder

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices