打造 Token Data API：从 0 到上线 CoinMarketCap & CoinGecko

代币要想一炮而红，必须尽早出现在 CoinMarketCap（CMC） 和 CoinGecko（CG） 这两大行情站点。提交申请表、填写 Excel 表格、最后一公里就是提供一个合规的 HTTP API 返回总供应量、流通供应量等核心数据。这篇指南用一个端到端案例把全部流程拆给你看，还会给出可直接落地的 Node.js 代码。

读懂关键点：提交前必知的 3 件事

1. 准备材料

前往 CMC / CG 官网底部 → “Submit a Token” → 依次填写：

英文项目简介
Explorer 链接（Etherscan、BscScan 等）
Richlist（前 20 大持仓者）
确认哪些地址为锁定地址（locked wallet）

2. 牢记 3 个数字

术语	定义	计算方式
总供应 Total Supply	链上生成总量 - 已销毁	`totalSupply() - burnBalance`
最大供应 Max Supply	合约硬顶（无限增发则留空）	Solidity 常量
流通供应 Circulating Supply	目前可自由交易部分	`总供应 - 锁定 - 已销毁`

锁定例子包括：团队钱包、线性释放的投资人地址、质押奖励待释放合约。

3. API 规则

CMC：只向 GET /totalsupply 要 1 个纯数字。
CG：只向 GET /circulatingsupply 要 1 个纯数字。
若提供任何其他格式，会被驳回！

API 开发 5 步走

Step 1 选型与依赖

Node.js 18+
Express + rate-limit 做防刷
web3.js 读链上数据
MongoDB Atlas（免费集群即可）→ 缓存解析结果，降低链请求

Step 2 项目骨架

├── abi/               # 合约 ABI
├── addresses/         # 代币合约地址、团队/锁仓/销毁地址
├── middleware/        # 自定义中间件
├── routes/            # Express 路由
├── utils/
│   ├── db.js          # Mongo 连接
│   ├── getChainData.js # 定时更新任务
│   └── getProjectData.js # 链上计算逻辑
└── server.js          # 入口

Step 3 逻辑拆分：getProjectData.js

关键函数总览：

连接以太坊 & BSC → 双链取 totalSupply() 与 balanceOf(burnAddress)
遍历顶部 20 地址，汇总 team + vesting + staking 余额

套用公式：

circulatingSupply = totalSupply - burn - locked

格式化并写入 Mongo。

👉 看完原理，立刻实操完整仓库，直接 Fork 就能用

Step 4 定时刷新 getChainData.js

node-schedule 每 15 秒跑一次
自动探测接口故障 → 重试 3 次
把 web3 实例放进缓存池，避免重复连接

schedule.scheduleJob("*/15 * * * * *", async () => {
  await getProjectData(web3Pool);
});

Step 5 API 路径 routes/projectOne.js

/v1/projectOne/totalSupply → 纯数字 total
/v1/projectOne/circulatingSupply → 纯数字 circulating

router.get('/totalSupply', async (req, res) => {
  const { value } = req.chainData.combined.totalSupply;
  return res.type('text/plain').send(String(value));
});

本地启动 3 分钟搞定

git clone <仓库地址>
cd Token-Data-API
npm i
# 1. 复制模板
cp .env.example .env
# 2. 写入
#   INFURA_KEY=xxx
#   MONGO_URI=mongodb+srv://...
npm run dev   # 监听 3001

访问：

curl http://localhost:3001/v1/projectOne/circulatingSupply

常见问题 FAQ

Q1：能不能不用 MongoDB？
A：可以换成 Redis 或直接落盘 JSON 文件，生产环境建议 Redis，速度更快。

Q2：返回精度要保持几位？
A：CMC/CG 只认整数；如果你是 18 位精度代币，记得 Math.round.

Q3：合约没开源怎样拿 ABI？
A：向 Solidity 开发者索要，或把字节码拖进 https://abi.hashex.org。

Q4：多链部署如何合并数值？
A：把每条链的总供应、销毁、锁仓分别计算，再相加即可。

Q5：锁定地址的余额将来解锁了怎么办？
A：一旦代币解锁进入市场，就把对应地址从锁定列表移除，重新部署脚本即可。

Q6：如何验证 API 是否会被 CMC/CG 拒绝？
A：先用 curl 测试，确保响应只有数字，没有引号、逗号、空格；否则会被打回重新修改。

最后 checklist 再扫一遍

✅ 申请表提交
✅ Excel 锁定/销毁地址无误
✅ /totalsupply 返回纯数字
✅ /circulatingsupply 返回纯数字
✅ Mongo 正常缓存，15 秒刷新一次
✅ rate-limit（每 IP 每 15 分钟 100 次）

👉 拿下两大行情站的终极模板，今天就能上线

祝上架一次通过，加油！