“Supply” is not one interchangeable number. Circulating, total, and maximum supply answer different questions, and data providers may calculate or verify them using different evidence. Check the provider, exact asset, and timestamp before comparing figures. The examples below are a dated CoinGecko API snapshot, not live data or an endorsement of either asset.
Three supply fields
| Field | What it describes in CoinGecko’s methodology | What it does not tell you by itself |
|---|---|---|
| Circulating supply | An estimate of units considered available in the public market. CoinGecko describes subtracting uncirculated holdings such as locked, vested, escrowed, or certain team and treasury wallets from total supply. | It is not a count of every unit that could be sold immediately. Classification depends on wallet and token information and can be revised. |
| Total supply | Units minted, less tokens permanently removed through burns, under CoinGecko’s stated methodology. | It is not necessarily the amount available to trade; locked, vested, reserved, or project-held units may remain included. |
| Maximum supply | The lifetime upper limit encoded or otherwise defined for an asset, if one is specified. | A missing value is not a number and does not, on its own, establish whether issuance is uncapped, unknown, or unreported. |
These are provider definitions, not universal on-chain fields. CoinGecko says it obtains circulating-supply information from project teams and verifies it; for proof-of-work assets it also describes using block-explorer APIs to query available coins. Read the provider’s methodology and the project’s issuance documentation for the asset you are evaluating.
Dated API examples
Retrieved from the public CoinGecko /coins/markets endpoint for Bitcoin and Ethereum in USD at 2026-11-03 13:24 UTC. The API returned last_updated as 13:22:52 UTC for both records. The values below are coin units; commas are formatting only.
| CoinGecko ID | Circulating supply | Total supply | Max supply | Circulating / max | Record updated (UTC) |
|---|---|---|---|---|---|
| bitcoin (BTC) | 20,105,365 | 20,105,365 | 21,000,000 | 95.74% | 2026-11-03 13:22:52 |
| ethereum (ETH) | 122,186,161.86556138 | 122,186,161.86556138 | Unknown (API returned null) | Not calculated | 2026-11-03 13:22:52 |
The BTC ratio is circulating supply ÷ maximum supply × 100, rounded to two decimal places. No ratio is shown for ETH because the response had no numeric maximum. CoinGecko’s methodology page describes Ethereum as having infinite supply, but the API field itself only returned null; the null value should not be treated as a documented issuance rule for another asset.
How to compare supply figures
- Match the asset definition. Check the provider’s asset ID, network, contract address where applicable, and whether the figure aggregates multiple chains. Tickers alone can be ambiguous.
- Keep the field names intact. Do not label total supply as circulating supply or treat a market-data provider’s estimate as an independently verified on-chain fact.
- Record both retrieval and data-update times. An API response can be retrieved after its
last_updatedvalue. Preserve both timestamps when saving a snapshot. - Calculate ratios only from compatible values. Circulating ÷ max is a reported supply ratio, not a forecast of unlocks, future issuance, price, or market capitalization.
- Leave absent data unknown. Do not substitute zero, a ticker-based guess, or an assumed unlimited supply for a null or missing field. Check project tokenomics and the provider’s methodology separately.
For a user-entered price and supply amount scenario, see the DCA planner or the P&L estimator; neither estimates token supply or token dilution.
Sources and limits
- CoinGecko Supply Methodology — definitions and provider approach to circulating, total, and maximum supply.
- CoinGecko API: Coins Markets — endpoint reference for market records and supply fields.
- CoinGecko Supply Update FAQ — provider notes on supply updates, missing circulating values, and multi-chain supply handling.
Sources and API response checked 2026-11-03. Figures can change or be revised. This page is an educational explanation, not a token valuation or investment recommendation.
Coinbase referrals — TODO: apply/approval and configure referral URL — referral link not configured.
Kraken referrals — TODO: apply/approval and configure referral URL — referral link not configured.
Ledger affiliate program — TODO: apply/approval and configure referral URL — referral link not configured.