Reconciling Token Transfers with Balance Snapshots
Compare opening balances, token movements and closing state with aligned blocks, exact units and explicit treatment of unexplained differences.
Overview
When translating these concepts into an integration, keep the scope described by the historical balance api with the result. The examples in historical token balances and blockchain data reconciliation show how the same distinction affects neighbouring data questions.
A transfer-derived balance and a directly observed balance answer related but different questions. Their comparison is useful only when both refer to the same asset, wallet, units and boundary states.
Align the opening state and range
If the opening snapshot is the state after block A, include movements after A through closing block B. Including A again double-counts its effects. Use block hashes where reproducibility requires them, and avoid mixing a finalized opening observation with an unstable closing head without declaring that policy.
Worked example: a visible difference
Opening raw balance is 1000. Known incoming movements total 400 and outgoing movements total 250. Expected closing balance is 1150, while a state read reports 1175. Preserve the difference of 25. Do not invent a transfer to make the equation balance: missing evidence, token mechanics or an interpretation error still need investigation.
Investigate by cause
Check duplicate events, off-by-one boundaries, decimals, reorganisation handling and asset identity before interpreting the difference. Rebasing or other contract-specific behaviour may change balances without ordinary transfer evidence. Record the method and coverage used for each side of the comparison. A matched total is helpful, but does not prove that every individual movement was classified correctly.
A practical acceptance test
Supply an opening balance after block A and a transfer inside A. Assert that the transfer is excluded from the subsequent A-to-B change range under that boundary rule. Then introduce an unexplained difference at B. The report should retain the discrepancy and its inputs rather than invent a balancing movement to make the test pass.
Questions about the topic
Frequently asked questions
Does an unmatched balance prove missing transfers?
No. Boundary errors, token behaviour and decoding issues can also explain differences.
Should a difference become a synthetic transaction?
Not automatically. Keep it as an unresolved reconciliation result until supported by evidence.
Standards & technical documentation
