How to Write a Token Data API to Get Listed on Coinmarketcap and Coingecko

Launching a new cryptocurrency token is an exciting milestone, but visibility on major platforms like Coinmarketcap (CMC) and Coingecko (CG) is crucial for credibility and adoption. One of the most technical—and often misunderstood—requirements for listing is setting up a functional HTTP REST API that returns accurate token supply data. This guide walks you through the entire process: from understanding key supply metrics to building and deploying a robust token data API.

Whether you're launching on Ethereum, Binance Smart Chain, or another EVM-compatible network, this step-by-step tutorial ensures your project meets the strict data standards required by top-tier crypto tracking platforms.

Understanding the Token Listing Process

Before diving into code, it’s essential to understand how CMC and Coingecko evaluate new tokens for listing.

Both platforms require project teams to submit detailed token data sheets. These spreadsheets collect vital information such as:

• Total supply
• Circulating supply
• Max supply
• Blockchain explorer link
• Richlist URL
• Top 20 wallet addresses and lock status

While Coingecko allows basic token info to be listed first, full data integration—including live supply metrics—requires a second submission with a working REST endpoint. Coinmarketcap, on the other hand, mandates this API upfront.

👉 Discover how leading projects power their market data with reliable infrastructure.

Key Definitions: Total Supply, Max Supply, and Circulating Supply

Misunderstanding these core terms is one of the biggest reasons applications get delayed or rejected. Let’s clarify each:

Total Supply

This is the number of tokens currently in existence, minus any verifiably burnt tokens. It reflects the net live supply on-chain at any given time.

Example: If 1 million tokens were minted and 100,000 were sent to a burn address, the total supply is 900,000.

Max Supply

The maximum number of tokens that will ever exist. This value is typically hardcoded into the smart contract.

Note: Not all tokens have a max supply. For instance, USDT and some algorithmic stablecoins are minted on-demand and have no hard cap.

Burnt tokens do not reduce max supply—it represents the historical ceiling of issuance.

Circulating Supply

This is the most complex metric. It represents the number of tokens actively available for trading in the open market.

The formula is:

Circulating Supply = Total Supply – Locked Tokens – Burnt Tokens

"Locked" includes:

• Team and advisor allocations under vesting schedules
• Reserve funds held by the project
• Incentive pools (e.g., staking rewards, liquidity mining)
• Any tokens not yet released to public markets

Even if tokens aren’t technically locked in a smart contract, they’re considered non-circulating if they’re reserved and controlled by insiders.

Building Your Token Data API: Step-by-Step

Now for the technical core: creating an API that returns accurate, real-time supply data.

We'll use Node.js, Express, Web3.js, and MongoDB Atlas (for caching). The goal is to expose two endpoints:

• GET /total-supply → returns total supply
• GET /circulating-supply → returns circulating supply

These will be consumed by CMC and CG to display up-to-date metrics.

Step 1: Set Up Your Development Environment

Prerequisites

• Node.js installed
• Basic knowledge of Express and REST APIs
• Familiarity with Web3.js (for blockchain interaction)

Required Services

1. Infura or Alchemy
   Provides reliable access to Ethereum and BSC nodes via HTTP/WebSocket endpoints. Sign up for a free account and create a project to get your API key.

2. MongoDB Atlas
   A free-tier cloud database for caching token data and reducing node load.

   • Create a cluster
   • Allow access from all IPs (0.0.0.0/0)
   • Set up a database user with read/write permissions
   • Copy your connection string (we’ll use it later)

👉 See how real-time blockchain data powers successful token listings.

Step 2: Project Structure Overview

Organize your project as follows:

/token-data-api
│
├── /abi               # Smart contract ABIs
├── /addresses         # Contract & wallet addresses
├── /middleware        # Custom middleware (e.g., slash removal)
├── /routes            # API endpoints
├── /utils             # Core logic: Web3 setup, data fetching
└── server.js          # Entry point

This modular structure keeps your code clean and maintainable.

Step 3: Connect to Blockchain Nodes

In /utils/getChainData.js, set up Web3 connections to Ethereum and Binance Smart Chain:

const setupWeb3 = async () => {
  const bsc_endpoints = [
    "https://bsc-dataseed.binance.org/",
    "https://bsc-dataseed1.defibit.io/",
    "https://bsc-dataseed1.ninicoin.io/"
  ];

  let bsc_web3;
  while (!bsc_web3) {
    for (let endpoint of bsc_endpoints) {
      try {
        bsc_web3 = new Web3(endpoint);
        const id = await bsc_web3.eth.getChainId();
        if (id === 56) break;
      } catch (err) {
        continue;
      }
    }
    if (!bsc_web3) await sleep(5000);
  }

  const web3 = new Web3("https://mainnet.infura.io/v3/YOUR_INFURA_KEY");

  return { web3, bsc_web3 };
};

This function establishes resilient connections—retrying if nodes are down—ensuring continuous data updates.

Step 4: Fetch and Calculate Token Data

Create /utils/getProjectOneData.js to query smart contracts:

const getProjectOneData = async (web3s) => {
  const { web3, bsc_web3 } = web3s;
  const contractABI = require("../abi/projectOneAbi.json");
  const { eth_addresses, bsc_addresses } = require("../addresses/projectOne");

  const ethContract = new web3.eth.Contract(contractABI, eth_addresses.contract);
  const bscContract = new bsc_web3.eth.Contract(contractABI, bsc_addresses.contract);

  // Fetch raw data
  const totalSupplyETH = await ethContract.methods.totalSupply().call();
  const burntETH = await ethContract.methods.balanceOf(eth_addresses.burnt).call();
  const teamTokensETH = await ethContract.methods.balanceOf(eth_addresses.team).call();

  // Repeat for BSC
  const totalSupplyBSC = await bscContract.methods.totalSupply().call();
  const burntBSC = await bscContract.methods.balanceOf(bsc_addresses.burnt).call();
  const teamTokensBSC = await bscContract.methods.balanceOf(bsc_addresses.team).call();

  // Calculate net totals
  const netTotalSupply = (totalSupplyETH - burntETH) + (totalSupplyBSC - burntBSC);
  const lockedTokens = Number(teamTokensETH) + Number(teamTokensBSC);
  const circulatingSupply = netTotalSupply - lockedTokens;

  // Format and cache
  const formattedData = {
    totalSupply: Math.floor(netTotalSupply / 1e18),
    circulatingSupply: Math.floor(circulatingSupply / 1e18),
    timestamp: new Date().toISOString()
  };

  await db.updateTokenData(formattedData);
};

A scheduled job (using node-schedule) runs this every 15–30 seconds to keep data fresh.

Step 5: Expose REST Endpoints

In /routes/projectOne.js:

const express = require('express');
const router = express.Router();

router.get('/total-supply', (req, res) => {
  res.json({ totalSupply: req.chainData.combined.totalSupply.value });
});

router.get('/circulating-supply', (req, res) => {
  res.json({ circulatingSupply: req.chainData.combined.circulatingSupply.value });
});

module.exports = router;

These endpoints return plain numbers—exactly what CMC and CG expect.

Frequently Asked Questions

Q: Do I need both total and circulating supply APIs?

Yes. Coinmarketcap requires a total supply endpoint, while Coingecko requires a circulating supply endpoint. Both must return a single numeric value.

Q: Can I use a static JSON file instead of an API?

No. Both platforms require a live HTTP endpoint that serves dynamically updated data. Static files won’t pass review.

Q: What if my token is only on one chain?

Adjust your logic accordingly. You don’t need multi-chain support unless your token exists across networks.

Q: How often should my API update?

Every 15–60 seconds is ideal. Use node-schedule or setInterval to automate updates.

Q: Can I use Redis instead of MongoDB?

Absolutely. Redis is faster for caching. MongoDB is used here for ease of setup, but Redis or even in-memory storage works in production.

Q: What happens if my API goes down?

CMC and CG may temporarily stop showing your data or delist if downtime persists. Ensure high availability using services like Heroku, Render, or AWS.

Final Steps: Deployment and Submission

1. Deploy your API using Heroku, Vercel, or any Node.js-friendly host.
2. Ensure your endpoints are publicly accessible (e.g., https://your-api.com/v1/projectOne/circulating-supply).
3. Submit your token data sheet with the correct URLs.
4. Monitor logs and uptime—respond quickly to any issues.

👉 Explore how top blockchain projects ensure API reliability and scalability.

Conclusion

Getting listed on Coinmarketcap and Coingecko isn’t just about marketing—it’s about technical precision. By building a reliable token data API that accurately reports total supply and circulating supply, you meet a critical listing requirement while establishing trust with investors and users.

With the right tools—Infura for node access, MongoDB for caching, and Express for routing—you can automate accurate data delivery and keep your token’s metrics transparent and up-to-date.

Remember: clarity, consistency, and correctness are key. Follow this guide closely, test thoroughly, and ensure your endpoints remain stable post-launch.

Your token deserves visibility—make sure it’s backed by solid infrastructure.