Sites like CoinMarketCap and CoinGecko often require an HTTP API endpoint that returns critical token data, such as total supply or circulating supply. This is a key step in getting your token listed and ensuring its visibility in the crypto ecosystem.
If you are launching a new token on Ethereum or another EVM-compatible chain like Binance Smart Chain, creating this API is a crucial item on your checklist. This guide walks you through the entire process, from understanding the requirements to building and deploying a functional API.
Understanding the Listing Application Process
The first step to getting your token listed is submitting a formal request through the appropriate forms. For CoinMarketCap and CoinGecko, this process involves providing detailed information about your token.
After submitting basic token information, you will be asked to complete a data sheet. This sheet requires precise figures for your token's supply metrics. Filling it out accurately is essential to avoid delays or rejection.
Key Differences Between Platforms
CoinMarketCap requires you to submit the data sheet before your token's basic information is listed. CoinGecko, on the other hand, allows you to get a basic listing first but requires a second submission with the completed data sheet for more detailed information.
Both platforms ask for similar data, including circulating supply, total supply, max supply, explorer links, and a list of the top 20 token holders. The definition and calculation of these terms are covered in the next section.
Defining Key Token Supply Metrics
Understanding the precise definitions of supply metrics is critical. Misunderstanding these terms is a common source of errors that can lead to application rejection.
Total Supply
Total supply refers to the total number of tokens that currently exist on the blockchain, minus any tokens that have been verifiably burned. This is a dynamic figure that can change over time.
Max Supply
Max supply is the hard-coded maximum number of tokens that will ever exist. Not all tokens have a max supply; some, like Tether USDT, have an unlimited supply. For tokens where all units are minted at launch and none are burned, the max supply equals the total supply.
Circulating Supply
Circulating supply is the most complex metric to calculate. The basic formula is:
Circulating Supply = Total Supply — Locked Tokens — Burnt Tokens
Locked tokens include team reserves, vested investor funds, and incentive tokens that have not yet entered the market. These tokens may be held in smart contracts or controlled by the team but are not considered circulating until released.
Building Your Token Data API
This section provides a technical overview of constructing an API that serves the required data. The example uses Node.js, Express, Web3.js, and MongoDB, but the principles can be applied to other tech stacks.
Prerequisites and Setup
Before you start coding, you need to set up a few external services:
- Blockchain Node Access: Use a service like Infura to get HTTP or WebSocket endpoints for connecting to Ethereum and other EVM chains.
- Database: A free MongoDB Atlas cluster is sufficient for development and testing. Ensure you configure network access to allow connections from your API server.
- Testing Tools: Have a tool like Insomnia or Postman ready to test your API endpoints.
👉 Explore more strategies for API development
Core Application Structure
A typical project structure for this API includes several key directories:
- /abi: Contains Application Binary Interface (ABI) files for your token contracts.
- /addresses: Holds JavaScript files exporting relevant smart contract addresses and wallet addresses.
- /routes: Defines the Express routes that will expose your API endpoints.
- /utils: Includes the core logic for connecting to the blockchain, fetching data, performing calculations, and interacting with the database.
Fetching and Calculating On-Chain Data
The heart of the API is a script that regularly queries the blockchain. Using the Web3.js library, you connect to node endpoints and create contract objects using your token's ABI.
These contract objects allow you to call functions like totalSupply() and balanceOf(address) to get raw data. You then process this data—converting units based on the token's decimals, summing balances, and applying the circulating supply formula.
The calculated results are formatted into a JSON object and cached in a database. This avoids making a new blockchain query for every API request, which would be slow and rate-limited.
Setting Up API Endpoints
The final step is creating simple HTTP routes that fetch the latest calculated data from the database and return it.
For CoinGecko, you need an endpoint that returns a single number representing the circulating supply (e.g., GET /v1/yourToken/circulating-supply).
For CoinMarketCap, you need a similar endpoint that returns the total supply (e.g., GET /v1/yourToken/total-supply).
These endpoints should return a plain text response containing only the number, which is what the listing platforms expect.
Frequently Asked Questions
What is the most common mistake in the listing application?
The most common mistake is miscalculating the circulating supply. Projects often incorrectly classify tokens as "locked" or "unlocked," or they fail to account for all locked tokens across different wallets and chains, leading to an inflated circulating supply figure.
Do I need to host this API on a server?
Yes, the API must be publicly accessible on the internet 24/7 so that CoinMarketCap and CoinGecko's systems can periodically call it to retrieve the latest data. Using a reliable cloud hosting provider is recommended.
My token is on multiple chains. How do I handle that?
You must aggregate the data from all chains. The API should query the total and circulating supply on each chain (Ethereum, BSC, etc.), sum them together, and return the aggregated figure as the final result.
How often does the data need to be updated?
The data should be updated regularly. The example code uses a scheduler to update the database every 15 minutes. The API endpoints themselves then serve this cached data, ensuring fast responses without hitting blockchain node rate limits.
What if my locked tokens become unlocked?
Your calculation logic must account for vesting schedules. This often means hardcoding release dates or amounts into your script or creating a more complex system that can check vesting contract states to dynamically determine the circulating supply.
Can I use this same API for other purposes?
Absolutely. Once built, this API can also power your project's website, displaying real-time token metrics to your community, which enhances transparency and trust. 👉 Get advanced methods for data management