Evm Token Decimals
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.
Get the complete skill folder, including its scripts and reference files.
·
When to use this skill
Use Evm Token Decimals when an AI agent needs a reusable SKILL.md workflow for this job: 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.
When not to use it
Skip Evm Token Decimals when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/evm-token-decimals # Save SKILL.md to ~/.claude/skills/evm-token-decimals/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/evm-token-decimals/SKILL.md. For a shared project, commit the folder at .claude/skills/evm-token-decimals/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Evm Token Decimals skill for this task: Reading ERC-20 balances in Python, TypeScript, or Solidity. Confirm any required inputs or files before making changes.
What supports this recommendation?
83/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 92/100
- Practical detail
- 92/100
- Source evidence
- 63/100
- Source signals
- 72/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# 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 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
```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() ```
### 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 ```
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); } ```
### 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); } ```
### Quick on-chain check
```bash 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
Intended uses
- 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
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.