How to Calculate Circulating Supply: The Short Answer
To calculate circulating supply, start from total supply and subtract every token that is not freely available to trade: unvested team and investor allocations, treasury and foundation reserves, unreleased ecosystem pools, tokens that have been burned or are provably unrecoverable, and any supply that is double counted across chains. What remains is the amount a market participant could actually acquire and sell today. The calculation itself is simple subtraction. The difficult part is deciding, wallet by wallet, which side of the line each balance sits on, and then publishing that decision in a form data aggregators and your own community can reproduce.
This guide is about that methodology and the reporting process. If you are still deciding how much of your supply should be liquid at launch, that is a different question, covered in our low float vs high float launch guide. Here we assume the allocation is fixed and ask how to count it honestly.
Circulating Supply vs Total Supply vs Max Supply
Three numbers are often confused, and mixing them up is the root of most reporting errors.
Max supply is the hard upper bound on how many tokens can ever exist, enforced by the contract or protocol rules. A token with no cap has no meaningful max supply, and should say so rather than publish a placeholder.
Total supply is the number of tokens that exist right now, minted and not burned, including locked, vested, and treasury-held tokens. It can rise toward max supply as new tokens are minted and fall when tokens are burned.
Circulating supply is the portion of total supply that is publicly tradable and not subject to a lock or restriction that prevents it from reaching the market. It is always less than or equal to total supply, which is always less than or equal to max supply.
These three drive different headline figures. Market capitalization is price multiplied by circulating supply. Fully diluted valuation (FDV) is price multiplied by max supply, or by total supply when there is no cap. The ratio between them tells a prospective buyer how much future dilution is queued up behind the current float, so the circulating figure you report directly shapes how your token is read.
A Framework for Classifying Every Wallet
The reliable way to avoid arguments about the number is to account for every token in total supply by wallet or contract, assign each to a category, and write down the reason. The table below gives a default classification. Treat it as a starting position, not a rule: your contracts and legal terms may justify a different treatment, as long as the reasoning is documented and applied consistently.
| Holder category | Default treatment | Reasoning |
|---|---|---|
| Team vesting contracts | Not circulating until released | Tokens in a vesting contract cannot be sold. Count them only as the contract releases them to a claimable state. |
| Investor lock contracts | Not circulating until released | Same logic as team vesting. Cliff and linear release determine when each tranche moves. |
| Treasury and foundation wallets | Usually not circulating | Held for operations, grants, and reserves, not for open-market sale. Label the wallets publicly so the exclusion is checkable. |
| Ecosystem and incentive pools | Not circulating until distributed | Tokens count once they reach recipients who can freely move them, not while they sit in the pool contract. |
| Market maker loans | Document one policy and apply it always | Loaned tokens sit in a third-party wallet and can trade, so many teams count them as circulating. Whatever you choose, state it and never switch quietly. |
| Exchange hot and deposit wallets | Circulating | Tokens held on exchanges are by definition available to trade. Do not subtract them. |
| Burned or provably unrecoverable | Not circulating, and reduce total supply if burned | Sent to a burn address or lost with no recovery path. Burned tokens should also come out of total supply. |
| Staking contracts | Depends on lock terms | Liquid staking with free withdrawal is closer to circulating. Staking with an enforced unbonding period or lock is usually excluded until withdrawable. State your rule. |
| Bridged supply on other chains | Count once, not twice | Locked-and-minted bridging creates a representation, not new supply. Count the canonical tokens or the wrapped tokens, never both. |
Two principles sit under the whole table. First, the test is whether the holder can sell today, not whether they intend to. Second, every exclusion should be defensible by pointing at an on-chain contract or a public wallet label.
How to Compute It Step by Step
- Establish total supply from the chain. Read it from the token contract rather than from a spreadsheet. If you are multichain, identify the canonical chain and the bridge mechanism.
- Build a complete wallet inventory. List every address and contract that holds a material balance: vesting, locks, treasury, pools, MM wallets, staking, bridges. The inventory must sum, with the circulating remainder, back to total supply. If it does not reconcile, something is missing.
- Classify each entry using the table above and record the reason in one sentence.
- Resolve time-dependent items. For vesting, use the released amount, not the scheduled amount. Cliffs and linear releases change claimable balances over time, so recompute at each unlock.
- Subtract and reconcile. Circulating supply equals total supply minus the sum of all non-circulating balances.
- Record the snapshot time. A supply number without a block height or timestamp cannot be verified later.
A Worked Example (Hypothetical)
Consider a hypothetical token with a total supply of 1,000,000,000.
- Team vesting contract holds 150,000,000 locked.
- Investor lock contracts hold 200,000,000 locked.
- Foundation treasury wallet holds 150,000,000.
- Ecosystem incentive pool holds 100,000,000, none distributed yet.
- Burn address holds 20,000,000.
- Everything else, 380,000,000, is spread across public holders, exchange wallets, and a market maker wallet counted under a documented policy.
Non-circulating balances total 620,000,000, so circulating supply is 380,000,000, or 38 percent of the total. If the burned tokens were removed from total supply as well, total supply would be reported as 980,000,000 and the circulating share would be about 38.8 percent. These numbers are illustrative only.
Publishing It: Endpoints, Wallet Lists, and Cadence
Calculating the number once is not enough. Aggregators and analysts need a way to read it on an ongoing basis, and a figure that cannot be verified will eventually be questioned.
A Public Supply Endpoint
The most useful publication format is a simple HTTP endpoint, often called a circulating supply API, that returns the current figure as a plain number with no wrapper, labels, or formatting. Machines parse plain numbers reliably, while a JSON object or a number with thousands separators invites parsing errors. A separate endpoint for total supply is equally useful. Keep the response fast, stable, and at a permanent URL, because aggregators may poll it repeatedly.
A Documented Wallet List
Alongside the endpoint, publish a page listing every wallet and contract excluded from circulating supply: address, chain, category, and a one-line reason. This turns the number from an assertion into something anyone can audit. It is also what makes unlabelled treasury wallets, a common source of disputes, disappear as a problem.
Update Cadence Around Unlocks
Circulating supply changes on predictable dates. Plan for them. Update the figure at each unlock or release event, rather than on a fixed weekly schedule that lets the published number lag behind reality. Announce upcoming changes in advance, and tie the update to a block height. For the market-side effects of those dates, see our piece on token unlocks and managing sell pressure.
Working With Aggregators
CoinGecko, CoinMarketCap, and similar data providers each follow their own methodology. They may accept a team-reported figure, verify it against on-chain data, or override it with their own calculation. Their submission requirements also change over time, so check each provider's current documentation and listing process before you submit, and do not assume one provider's treatment matches another's. Our guide to getting listed on CoinGecko and CoinMarketCap walks through the broader listing process.
Keep the Number Consistent Everywhere
A correct number reported inconsistently looks like an incorrect one. Your whitepaper, website, documentation, exchange listing forms, and aggregator submissions should all use the same definitions and the same classification rules, even though the figures themselves will differ by date. If you are drafting or revising the whitepaper, our crypto whitepaper checklist is a useful place to confirm the supply section matches your published methodology.
The same applies to exchange applications. Whichever launch route you choose, whether a launchpool, an IEO, or a launchpad, the exchange will ask for supply details, and they should match what everyone else sees. Our comparison of launchpool, IEO, and launchpad models covers what each route requires.
Common Mistakes
- Double counting bridged tokens. Counting both the locked originals and the minted wrapped versions inflates the figure. Count each unit of economic supply once.
- Treating market maker loans inconsistently. Including loaned tokens one month and excluding them the next makes the series impossible to interpret. Pick a policy, publish it, keep it.
- Stale numbers after unlocks. The most frequent failure. A major release happens, the published figure does not move for days, and every derived metric is wrong in the meantime.
- Unlabelled treasury wallets. If observers cannot tell that a large balance belongs to the foundation, they may count it as circulating, or accuse you of hiding it.
- Reporting scheduled rather than released vesting. The schedule says what will be released; the contract says what has been.
- Forgetting to reduce total supply after burns. Burned tokens that remain in the total understate your circulating share.
Why This Number Matters
Circulating supply feeds directly into market cap, the headline valuation figure every aggregator displays. Together with total or max supply it sets your FDV-to-market-cap ratio, which sophisticated holders and analysts read as a measure of future dilution. Exchange listing reviews and diligence processes tend to look at whether a project's published supply matches on-chain reality. And over time, accurate and prompt reporting is a trust signal: teams that publish clear methodologies and update on schedule give their communities less reason to suspect hidden float.
It also matters for trading. Liquidity depth, spreads, and inventory sizing are all calibrated against the amount of tradable supply, so a misreported float distorts every decision built on it. At Fibonacci Capital, supply data is one of the first things we check when we assess a token's market structure, because a clean, consistent number makes everything downstream easier to plan.
If your supply reporting needs a second pair of eyes, or you are preparing a listing and want the float and liquidity plan to line up, get in touch with Fibonacci Capital.