Handle EVM Token Decimals
Your AI prevents silent token decimal mismatches across EVM chains by querying decimals at runtime and caching results. It normalizes balances safely for wallets, bots, dashboards, and DeFi tools handling bridged or multi-chain tokens.
affaan-m on GitHub
Curated by PromptsEdge from a public repo · MIT license. All credit goes to the author.
What is this skill?
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
What’s inside
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
from decimal import Decimal
from 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
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
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
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
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
cast call <token_address> "decimals()(uint8)" --rpc-url <rpc>
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
Install this skill
- 1
Get the skill — it’s free
Use the Get this skill panel. Unlocked skills stay in My skills. - 2
Download or clone the files
Download the zip, or clone the repo and copy theskills/evm-token-decimalsfolder. - 3
Put it where your agent looks for skills
For Claude Code, use your personal skills folder (every project) or a project’s own folder:~/.claude/skills/evm-token-decimals/SKILL.md # all projects .claude/skills/evm-token-decimals/SKILL.md # this project only
- 4
Just ask
No command needed. The agent reads the skill’s description and loads it on its own when your request matches.
SKILL.md frontmatter
What your agent reads to decide when to load this skill.
--- name: evm-token-decimals description: 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. ---
Files
Open any Markdown file to read it here.
Related skills
View all →- Review Prediction Market RisksFreeYour AI reviews prediction-market workflows for compliance, safety, data quality, privacy, and execution risks before accessing sensitive data or trading. It checks venue rules, flags legal issues, enforces security, and ensures manual decision points remain.
- Review Spring Boot SecurityFreeYour AI reviews Spring Boot services for authentication, authorization, validation, CSRF, secrets, headers, and rate limiting. It covers JWT, OAuth2, session cookies, method security, and dependency vulnerability scanning.
- Audit Claude Code SecurityFreeScan your Claude Code project’s .claude/ directory for security risks using AgentShield. It checks configuration files, MCP servers, hooks, and agent definitions for secrets, injection vulnerabilities, and unsafe settings.
- Review Code SecurityFreeEnsure your code follows security best practices for authentication, input validation, secret management, and sensitive features. It checks for hardcoded secrets, validates user input schemas, and audits API endpoint protections.