Total Supply vs Circulating Supply in Token Data
Compare on-chain total supply with circulating-supply estimates, and document exclusions such as locked, treasury, custody or burned holdings.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
Total supply and circulating supply answer different questions. A contract can expose a supply value, while circulation usually requires a methodology for deciding which holdings are economically available.
Separate observation and methodology
Record the contract’s supply result at a block with its units. Then define any circulation exclusions independently. Locked balances, vesting, treasury holdings and burn destinations require evidence and policy. A familiar address label is not enough to justify subtracting a quantity without a dated, reviewable classification.
Worked example: a restricted allocation
A token reports one million units. A methodology excludes two hundred thousand under a documented lock and estimates circulation at eight hundred thousand. If the lock expires, circulation can change without new minting. Preserve the lock evidence and effective time rather than treating the difference as a contract arithmetic error.
Keep market calculations consistent
Use a price and supply definition that refer to compatible times and units. Publish whether a market-cap calculation uses total, circulating or another supply estimate. Test minting, burning and token-specific rebasing. Unknown restriction status should remain uncertain rather than being automatically classified as either circulating or permanently excluded.
A practical acceptance test
Keep contract total supply fixed while a documented lock expires. Assert that the circulation estimate can change without minting. Retain the lock’s effective interval and methodology version. Then remove restriction evidence and verify an uncertainty state rather than automatically classifying the allocation as either permanently locked or freely circulating.
Questions about the topic
Frequently asked questions
Is circulating supply always an on-chain field?
No. It commonly depends on a separate classification methodology.
Does a locked allocation reduce contract total supply?
Not necessarily. Restriction and minting are different concepts.
Standards & technical documentation