Token Supply API

Custom token supply API for CoinMarketCap and CoinGecko

What is different between "Max", "Total" and "Circulating" Supply?

  • Max Supply is the maximum amount of coins that can ever exist in the lifetime of a coin
  • Total Supply is the total amount of coins that are currently in existence at this moment in time (minus any coins that have been burned).
  • Circulating Supply is the estimated amount of coins that are currently circulating the entire market and within the general public's hand.

As a token dev how do I have CoinMarketCap & CoinGecko display my Circulating / Total Supply?

So you will be required to provide this information via your own API rather than have CMC/CG automatically calculate this for you. What we found ourselves is current existing options out there are rather cumbersome or lack really any information on getting it set up for yourself. To help with this AnjiLabs have put together a GitHub repository for any token to use that can be used by any EVM chain

This GitHub repository will provide you with the 2 different end-points required for both CG & CMC one /circulating for the current circulating supply to the current block and /total for the current total supply (minus burns) to the current block.

There are a couple of prerequisites to using the project:

  1. Node JS - To be able to run this package you'll require Node JS on your local system. If you don't currently have Node on your machine check out nvm to get started.
  2. CloudFlare - This API is built and runs on CloudFlare Workers, the free tier should suffice for this API if you don't already have a CloudFlare account. You will first need to sign up to workers as well follow CloudFlare's own documentation here

Getting Started

You will see the file info.json this is where the basic information of your token will live. As an example we have used the ANJI token information.

You can either update the JSON file directly or you can run our little helper script to enter details by running npm run details. Within your terminal you will be asked a series of questions and will generate the info.json file directly for you.


The balances param within the JSON object should contain all of the wallets that should be omitted from your circulating supply. Removing wallets such as dead wallet, developer wallets and liquidity pool wallets.


The endpoint param within the JSON object should be a https endpoint that provides data for the blockchain.

Such as:

Now one big gotcha for BSC and some data endpoints is they will block some IP's such as CloudFlare for this reason if your token is on the BSC network we suggest using you can sign up for free and use the free tier for this API using their Speedy Nodes option. Once you create your account and get your BSC Speedy Node url simply add this to the value for the endpoint param.


Finally you'll see the token param containing some basic information of your token address, supply & decimals. The address should be the contract address for the token, supply being the full max supply (before burns etc) and decimals be the decimals set for the token.


Now that we have all this information setup we can get going. By installing and running the project.

Install the dependencies of the project using

npm install

Login to your personal Cloudflare

npm run wlogin

Run locally

npm start

Once the command completes you'll see

👂  Listening on

You can now visit your API locally

Once you have verified this is all correct you can simply deploy your API to Cloudflare using.

npm run deploy

This will deploy directly to your CloudFlare account a worker whilst returning a URL in which the API runs from something like

✨  Build completed successfully!
✨  Successfully published your script to

About the Author

Nick White
Chief Technology Officer

Nick leads the technical operations for the Anji Foundation working hands on with the developers at AnjiLabs.