Token Decimal Precision for Onchain Trading Agents

An autonomous onchain trading agent needs quantities in consistent units before a typed action reaches execution checks. We use exact synthetic amounts here to separate raw token records from the display values a model may read.

Token quantities commonly arrive as integers that require a scale before a reader can interpret them. A data pipeline should preserve that integer and its identity even after producing a human-readable amount. Formatting is not a harmless final step when amounts feed later calculations.

Work through one quantity

Assume an illustrative token with six decimal places and a raw amount of 1234567. The displayed amount is 1.234567 tokens because the scale is one million. If a pipeline assumes eighteen decimal places instead, it reports 0.000000000001234567. Both values can pass a numeric parser. Only one matches the stated metadata.

ERC-20 defines the decimals method as optional and explains its display scaling. It also makes name and symbol optional. A robust collector therefore needs an explicit missing-metadata path rather than an unconditional assumption that every contract supplies these fields.

Keep the raw and interpreted records together

Store the chain identifier, contract address, raw integer as an exact representation, declared decimals, and metadata observation reference. Store the normalized amount separately. Record whether the decimal value came from a contract call, a trusted registry, or an explicit local override. An override should have a reason and a reviewable history.

Use integer or decimal arithmetic for normalization. For the example, division by 10**6 yields an exact decimal with six fractional positions. Avoid converting a large integer through a binary floating-point value first. A later pretty-print cannot recover digits that were rounded during parsing.

Make unknown metadata visible

If decimals are unavailable, the correct output can be a raw amount with normalization status unknown. Keep the normalization unresolved until the scale is supported. A chart can omit the normalized point while retaining the underlying event and a diagnostic count. This is usually more useful than drawing a precise but unsupported balance.

For comparisons, ensure both quantity and price use compatible units. If the quoted price is per whole token, multiply it by the normalized quantity. If a price source uses another scaling convention, normalize that convention explicitly. A quantity that looks plausible does not validate the price's unit.

Test exact round trips

Use fixtures for zero, one raw unit, 1234567 raw units, and a large integer beyond the exact range of your default numeric representation. Normalize and then rescale; the recovered integer should match the original wherever no intentional rounding occurs. Add a missing-decimals fixture that remains unresolved rather than receiving a default.

Limits of this check

Correct decimal handling establishes unit consistency under the stated metadata. Token authenticity, market value, and contract behavior require separate evidence. Contract upgrades, wrappers, and provider-specific representations may require additional interpretation. Keep that interpretation attached to the data record. Exact arithmetic and metadata provenance make errors easier to find without turning a display convention into a broader claim.

Place this check in the agent loop

Our state and memory framework explains how this input contract fits a persistent trading agent. Use the harness-transfer test design to distinguish a data-adapter change from a change in model behavior.