如何构建 Token 数据 API 以通过 CoinMarketCap 和 CoinGecko 上币申请

对于在以太坊或其他 EVM 兼容链（如币安智能链）上发布新代币的项目而言，确保代币能够及时上线主流数据平台是成功的关键一步。其中，构建一个能够返回代币核心数据（如总供应量和流通供应量）的 HTTP API 接口，是满足 CoinMarketCap（CMC）和 CoinGecko（CG）上币要求的重要环节。本文将详细解析这一过程，帮助开发者高效完成 API 开发与上币申请。

上币申请基础流程

申请代币上线的第一步是提交申请工单。以下是针对 CMC 和 CG 的基本步骤：

• 访问各自网站首页底部的申请表单链接。
• 填写所有必填信息后，您将进入一个要求填写代币数据 Excel 表格的环节。
• 对于 CMC，必须填写此表格才能展示代币的基本信息；而对于 CG，您可以先获得基础信息的上线，之后再提交数据表格以显示更完整的数据。

两份表格内容相似，均要求提供以下核心数据：

1. 流通供应量（Circulating Supply）
2. 总供应量（Total Supply）
3. 最大供应量（Max Supply）
4. 区块链浏览器链接
5. 富豪榜链接
6. 前 20 大钱包地址及其详情（最重要的是标注代币是否“锁定”）

CG 额外要求：

• Coingecko 上的代币链接（需要先完成基础信息上线）
• 代币分配计划
• 返回流通供应量的 HTTP REST 端点

CMC 额外要求：

• 返回总供应量的 HTTP REST 端点

实用技巧：填写表格时，可直接访问代币的 Etherscan 页面，点击“持有者”标签，复制前 20 名持有者的表格信息，直接粘贴到申请表格中，以减少手动错误。

核心术语定义

理解并准确计算以下关键指标是避免申请被拒的基础：

总供应量（Total Supply）

指当前链上存在的代币总数，减去任何可验证已销毁的代币。

最大供应量（Max Supply）

指代币项目中硬编码设定的、链上将会存在的代币最大数量。并非所有代币都有最大供应量，例如 USDT 就没有发行上限，此时最大供应量为无限。对于部分代币，最大供应量可能等于总供应量（即全部代币在启动时一次性铸造且未有销毁）。

流通供应量（Circulating Supply）

这是最复杂且易出错的指标，其基本计算公式为：

流通供应量 = 总供应量 - 锁定代币 - 已销毁代币

锁定代币通常包括：

• 团队控制的预留代币（用于技术开发、社区扩展、团队薪酬等）
• 投资者或个人的限代代币（根据解锁计划逐步释放）
• 激励代币（按计划分发给节点运营者或流动性提供者等）

请注意：锁定代币可能是被智能合约真正“锁定”并按代码规则释放，也可能仅是由团队控制并按计划释放。只要这些代币自启动时被预留且尚未进入市场流通，它们就被视为“锁定”。

构建您的 Token API

接下来我们将进入实战环节，手把手教您构建一个符合要求的 API。本教程假设您已熟悉 Express 框架、路由设置基础，以及 MongoDB 或其他数据库/缓存方案的基本操作。

前期准备

在开始编码前，需要完成几项准备工作：

1. 获取 Infura 端点：注册 Infura 免费账户，创建项目后获取 HTTP 和 WebSockets 端点，用于 Web3.js 连接。
2. 设置 MongoDB 数据库：注册 MongoDB Atlas 免费账户，选择就近的免费集群，创建数据库。确保在“网络访问”中允许所有 IP（0.0.0.0/0），并在“数据库访问”中创建具有读写权限的用户。
3. 获取连接字符串：从数据库连接指南中复制连接字符串备用（密码稍后动态设置，避免硬编码）。

注意：此处选择 MongoDB 是因其免费、易用且与 Heroku 兼容良好。但对于生产环境，建议使用 Redis 等缓存方案或直接写入 JSON 文件。

项目结构概览

我们的示例项目包含以下主要结构和文件：

• /abi：存储各项目的 ABI 文件。
• /addresses：存放智能合约及相关地址（前 20 持有者、团队/投资者地址）。
• /middleware：自定义中间件（例如去除 URL 末尾斜杠）。
• /routes：定义所有公开路由。
• /utils：核心逻辑所在，包括数据库设置、代币数据获取逻辑等。
• server.js：整合所有模块，启动服务器。

👉 查看实时数据获取工具与代码示例

核心代码解析

1. 设置 Web3 连接与定时任务 (utils/getChainData.js)

此模块主要完成三件事：

• 定义 setupWeb3 异步函数，使用 web3.js 连接节点端点（支持故障转移）。
• 定义 updateData 函数，通过定时任务定期从链上获取最新数据。
• 导出 getChainData 函数，启动整个数据更新循环。

2. 获取数据、计算与存储 (utils/getProjectOneData.js)

此模块是核心数据处理单元，主要步骤包括：

• 使用传入的 web3 对象创建智能合约实例，调用合约方法获取原始数据。
• 对原始数据进行计算，得出所需指标（如总供应量、流通量）。
• 格式化数据（转换小数位、添加描述信息等）。
• 将格式化后的数据写入数据库。

关键计算示例（以太坊部分）：

const team_eth = Number(team_1) + Number(team_2) + Number(team_3);
tokenData.eth.totalSupply.value -= burnt_on_eth;
tokenData.eth.circulatingSupply.value = Number(tokenData.eth.totalSupply.value) - Number(team_eth);

3. 整合与启动 (server.js)

在此文件中，我们：

• 调用 getChainData() 启动数据更新循环。
• 设置 Express 服务器、中间件（如速率限制、CORS）。
• 定义路由，从数据库获取缓存数据并返回给客户端。

常见问题

1. 为什么需要单独构建 API？直接提供数字不行吗？

CoinMarketCap 和 CoinGecko 要求项目方提供一个公开的 API 端点，以便它们能够定期自动获取最新的链上数据，确保数据的实时性和准确性。直接提供静态数字无法满足动态更新的需求。

2. 流通供应量计算中最常见的错误是什么？

最常见的错误是对“锁定代币”的误判。许多项目容易忽略那些由团队控制但未硬锁定的代币（例如暂时保存在多签钱包中的代币），这些都应被计入锁定部分。

3. 除了 MongoDB，还可以使用哪些缓存方案？

对于轻量级或生产环境，可以考虑使用 Redis（性能更高）、简单的 JSON 文件存储（配合定期写入机制），或者甚至直接使用内存缓存（注意服务器重启会导致数据丢失）。

4. 如果我的代币只在一条链上，代码需要做哪些调整？

代码将大大简化。您只需要移除多链相关的逻辑（例如删除对 BSC 的 web3 连接和数据处理），集中处理一条链的数据即可。

5. API 需要部署在什么样的服务器上？

需要一个能够持续运行、稳定访问的公网服务器。常见的部署平台包括 Heroku、AWS EC2、DigitalOcean Droplets 等。确保服务器 IP 不会被目标网站屏蔽。

6. 如何处理智能合约未验证导致没有 ABI 的情况？

您需要联系项目的 Solidity 开发人员获取完整的 ABI。否则，将无法通过 web3.js 调用合约的读取函数来获取数据。

通过以上步骤，您将能够构建一个符合要求的 Token 数据 API，为成功上线主流数据平台扫清技术障碍。