Evm Token Decimals

조용한 decimal mismatch는 에러 없이 잔액이나 USD 값이 자릿수 단위로 틀어지는 가장 흔한 원인 중 하나입니다.

사용 시점

• Python, TypeScript, Solidity에서 ERC-20 잔액을 읽을 때
• 온체인 잔액으로 법정화폐 값을 계산할 때
• 여러 EVM 체인의 토큰 수량을 비교할 때
• 브리지 자산을 다룰 때
• 포트폴리오 트래커, 봇, 집계기를 만들 때

동작 방식

스테이블코인이 어디서나 같은 decimals를 쓴다고 가정하지 않습니다. 런타임에 decimals()를 조회하고, (chain_id, token_address) 기준으로 캐시하며, 값 계산에는 decimal-safe 수학을 사용합니다.

예시

런타임에서 decimals 조회

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)