Token Base Unit

Overview

Meaning and boundaries

Token Base Unit is the indivisible integer unit recorded by a token contract or ledger. A token base unit is the smallest integer unit recorded by a token contract or ledger. For tokens with decimal precision, a human-facing quantity is represented as an integer scaled by ten to the configured decimals. Software should perform this conversion with exact integers or decimal arithmetic, using the specific token contract’s actual precision.

How it works in practice

Read token decimals from a trusted asset registry or verified contract information, not from a user-entered symbol. Convert a human amount to its integer representation using exact decimal arithmetic. Check that the desired quantity is representable at the token’s precision before creating a transaction. In reconciliation, compare the on-chain integer amount directly with the stored expectation and only format it as a display quantity for customer interfaces.

Checks and failure points

Assuming every token uses 18 decimals can misprice transfers by enormous factors. Avoid binary floating-point rounding and never derive contract identity from the token symbol alone.

Operational evidence and decisions

When performing a token transfer through an API, developers generally pass an integer amount rather than a human-readable decimal string. Converting 0.1 token using floating-point arithmetic can produce unintended rounding. Read the decimal specification from an authenticated token definition and use exact libraries. The network and contract address together identify the asset; a token ticker by itself is not a safe basis for deciding precision.

How it differs from related terms

Base units are ledger integers. Display units are the scaled values people read; both represent the same underlying token quantity. Related entries: Token Decimals; Token Minimum Unit; Token Display Unit.