如何解读CoinMarketCap的标准化JSON响应格式

区块链文库报道：

引言

每个CoinMarketCap API端点都以相同的JSON结构返回数据。只需学习一次，你就可以处理任何端点，无需每次都重新适应新的响应格式。

本指南将解析两个顶级键、ID系统、时间戳格式，以及如何将多个资产和币种合并到单个请求中的约定。

两个顶级键

每个响应都包含两个顶级键：data 和 status。

{"data": { },"status": {"timestamp": "2026-07-03T10:00:00.000Z","error_code": 0,"error_message": null,"elapsed": 12,"credit_count": 1}}

data

包含你请求的记录。data 的结构因端点而异：

列表端点（如 /v1/cryptocurrency/listings/latest）返回数组。

查询端点（如 /v3/cryptocurrency/quotes/latest）返回以资产ID为键的字典。

单条记录端点直接返回对象。

status

始终存在，即使在错误响应中也是如此。它包含：

timestamp，请求被处理时的服务器时间，格式为 ISO 8601；

error_code，成功时为 0，失败时为特定错误码；

error_message，成功时为 null，失败时为人可读的错误信息；

elapsed，请求处理耗时，单位为毫秒；

credit_count，本次调用消耗的 API 积分数量。

在消费数据之前，务必检查 error_code。HTTP 状态码为 200 但 error_code 非零，表示部分响应或响应失败。

稳定的数字 ID

CoinMarketCap 为每种加密货币、交易所和法定货币分配一个永久的数字 ID。这些 ID 是稳定的。即使项目更名或改变交易代码，ID 也不会改变。

比特币：id=1

以太坊：id=1027

币安：id=270（交易所）

美元：id=2781

尽可能使用 ID 而非交易代码。交易代码不唯一，多个项目可能共享相同的代码。在构建前查询 ID：

curl -G 'https://pro-api.coinmarketcap.com/v1/cryptocurrency/map' --data-urlencode 'symbol=BTC,ETH,SOL' -H 'X-CMC_PRO_API_KEY: YOUR_API_KEY' -H 'Accept: application/json'

响应中包含每个资产的 id、slug、name、symbol、platform 和 first_historical_data。

时间戳

API 中的所有时间戳均为 ISO 8601 格式，采用 UTC 时区：2026-07-03T10:00:00.000Z

这适用于 status.timestamp、资产 last_updated 字段以及所有历史数据点。请将它们解析为 UTC，如需在应用层转换为本地时间，请自行转换。

币种转换

大多数价格端点支持 convert 参数，可一次性返回一种或多种币种的值。

curl -G 'https://pro-api.coinmarketcap.com/v3/cryptocurrency/quotes/latest' --data-urlencode 'id=1' --data-urlencode 'convert=USD,EUR,BTC' -H 'X-CMC_PRO_API_KEY: YOUR_API_KEY' -H 'Accept: application/json'

响应中包含每个请求币种的 quote 条目：

{"data": [{"id": 1,"name": "Bitcoin","symbol": "BTC","quote": [{"symbol": "USD","price": 63120.95,"market_cap": 1265258535378.41,"volume_24h": 29127614493.57},{"symbol": "EUR","price": 58471.23,"market_cap": 1171238512741.52}]}]}

注意版本差异。在 v3 API 系列中，quote 以数组形式返回。使用过滤器提取你需要的币种：

usd = next((q for q in asset.get("quote", []) if q.get("symbol") == "USD"),{})

price = usd.get("price")

v1 API 系列将 quote 作为以 symbol 为键的字典返回（quote["USD"]["price"]）。在编写解析器之前，请确认端点所属的版本。这是整个 API 中最常见的解析错误来源。

首次转换包含在基础积分成本中。每次额外转换增加 1 积分。

批量请求多个资产

无需为每个资产单独调用端点，可以在一次请求中传递多个 ID：

curl -G 'https://pro-api.coinmarketcap.com/v3/cryptocurrency/quotes/latest' --data-urlencode 'id=1,1027,1839,5426' -H 'X-CMC_PRO_API_KEY: YOUR_API_KEY' -H 'Accept: application/json'

这会在一次调用中返回多个资产的数据。积分按每返回 200 个资产消耗 1 分计算，向上取整，因此批量请求比逐个调用高效得多。

Accept-Encoding 请求头

在请求中包含 Accept-Encoding: deflate, gzip 以接收压缩响应。这能减少大型负载（如完整市场列表）的带宽消耗。

curl -G 'https://pro-api.coinmarketcap.com/v1/cryptocurrency/listings/latest' -H 'Accept: application/json' -H 'Accept-Encoding: deflate, gzip' -H 'X-CMC_PRO_API_KEY: YOUR_API_KEY'

常见错误

假设 quote 始终是字典。实际上，在 v3 中它是数组，在 v1 中是字典。解析前请检查端点版本。

未检查 error_code。HTTP 200 状态但 error_code 非零，表示响应部分或失败。务必先检查它。

将时间戳解析为本地时间。所有时间戳均为 UTC。先解析为 UTC，再根据需要转换。