CoinGecko 与 CoinMarketCap 行情 API 实战：429 按分钟窗口算，credit 只认 200

排障从一次 429 开始。前端报「Too Many Requests」，但控制台看月度 credit 几乎没动，于是有人以为是限流配错了、或者 key 没生效。实际是两个计数器：分钟级限流窗口统计所有请求，包括 4xx 和 5xx；月度 credit 只在 HTTP 200 时扣。 一次 401、一次 400，credit 不掉，但分钟窗口照样被吃掉一格。反过来，重试风暴打满分钟窗口、credit 省着用，这个组合最容易把服务打挂。

CoinGecko：错误码、根地址与鉴权差异

文档：

HTTP 状态码：

业务错误码更常踩：

• 10002 Missing API Key。Pro 用 x_cg_pro_api_key，Demo 用 x_cg_demo_api_key。
• 10005 Plan Restricted，该端点不在你的套餐内。
• 10010 Invalid API Key：用了 Pro key，但根地址必须是 pro-api.coingecko.com。
• 10011 Invalid API Key：用了 Demo key，但根地址必须是 api.coingecko.com。

10010/10011 基本就是 key 和根域名搭错。Demo key 走 api.coingecko.com，Pro key 走 pro-api.coingecko.com，两者不能互换。

CORS Error 是另一种：服务端没返回 CORS 头，别在浏览器直连，走后端代理。

CoinGecko 限流口径与套餐

限流口径：

• 付费套餐按套餐档位。
• Demo 计划 100 calls/min。
• Keyless（无 key）按 IP 限流，同 IP 下所有用户共享。
• 所有请求都计入每分钟限流，包括 4xx 和 5xx。

用 Google Sheets 调 API 的场景，共享 IP 很容易撞限流，建议配专用付费 key。support 页另有一处口径：Public API 5~15 calls/min（视全球用量浮动），注册 Demo 可稳定 30 calls/min。

credit 计数规则：任意端点每次请求算 1 call（1 call = 1 credit）；只有 HTTP 200 才扣月度 credit；4xx/5xx 不扣 credit；但不管状态码，所有请求都计入分钟限流。

套餐（）：

超额 $0.0005/call。WebSocket：Basic 起 5 sockets；Webhook：Basic 1 个。

CoinMarketCap Keyless Public API

文档：

Keyless 不需要注册、不需要 key、不需要 header。根地址是 https://pro-api.coinmarketcap.com/public-api，把 /public-api 放在受支持端点路径前即可。

注意别用带 key 的根 https://pro-api.coinmarketcap.com/v1/...，那需要 key。Keyless 用：

https://pro-api.coinmarketcap.com/public-api/v1/simple/price

Keyless 调用不要发 X-CMC_PRO_API_KEY 头；只支持 GET；返回与 keyed Pro API 完全相同的 JSON envelope、约定与错误格式。

首测（无 key，标准库即可，1=BTC，1027=ETH）：

curl "https://pro-api.coinmarketcap.com/public-api/v1/simple/price?ids=1,1027&convert=USD"

Python 标准库：

base = "https://pro-api.coinmarketcap.com/public-api"
# urllib.request 请求 /v1/simple/price?ids=1,1027&convert=USD

Node：

fetch(`${base}/v1/simple/price?ids=1,1027&convert=USD`)

限流方面，Keyless 请求共享一个按 IP 的限流池，保证公共端点稳定。遇到 429 要退避重试，短暂等待即可清除：

def get(url, tries=5):
for i in range(tries):
try:
req = urllib.request.Request(url, headers={"Accept":"application/json"})
return json.load(urllib.request.urlopen(req, timeout=10))
except urllib.error.HTTPError as e:
if e.code == 429 and i

带 key 请求域名 `pro-api.coinmarketcap.com`，key 两种传法：首选自定义头 `X-CMC_PRO_API_KEY`；次选 query 参数 `CMC_PRO_API_KEY`。生产用头，别把 key 放 URL 里。

credit 按成功（HTTP 200）计，1:1。账号管理端点、用量统计端点、错误响应不计入。分页端点每超 100 个数据点会多计 1 credit（向上取整），`/map` 轻量端点恒为 1 credit；bundled 资源同样每 100 个多 1 credit；convert 每多一个币种多 1 credit。用 `/key/info` 查用量。免费 Basic 层每天/每月按 UTC 零点重置。

套餐（）：

| 套餐 | 价格 | 月度 credit | 限流 |
| --- | --- | --- | --- |
| Basic | 免费 | 15,000 | 50 req/min |
| Builder | $29/mo | 150K | 300/min |
| Startup | $79/mo | 450K | 600/min |
| Growth | $299/mo | 2M | 750/min |
| Professional | $699/mo | 5M | 1200/min |
| Enterprise | 定制 | | 1600+/min |

Basic 免费层含 60+ 端点、1 把 key、数据 60 秒更新、商用授权。

x402 是按次付费模型，例如 `/x402/v3/cryptocurrency/quotes/latest` 0.01 USDC，30/min per wallet，走 USDC 结算。另有 MCP：`mcp.coinmarketcap.com/mcp`。

数据新鲜度：多数 REST 端点 1 分钟周期更新；需要推送式实时用 WebSocket；x402 是访问模型，不是新鲜度层。

## 工程要点

1. 先 Keyless / 首次 curl 打通连通性与 JSON envelope，再上 key。解析逻辑先跑通，鉴权是后一步的事。
2. Demo key 根域名 `api.coingecko.com`，Pro key 必须 `pro-api.coingecko.com`，混用报 10010/10011。
3. 限流是分钟窗口且 4xx/5xx 也算次数；credit 只按 200 扣。别把重试风暴打满分钟窗口，退避要带抖动。
4. 浏览器直连会被 CORS 拦，行情 key 也不能暴露在前端，必须走后端代理/网关；给前端的接口做缓存（例如 10~60s）削掉重复请求。
5. 批量取价用一次多 id 请求（CoinGecko `/simple/price?ids=` 逗号分隔；CMC `simple/price` `ids` 逗号分隔），比逐币轮询省配额。
6. 付费前先用 `/key/info`（CMC）或控制台核对 credit 消耗，分页和 convert 会悄悄多扣 credit。

## 不适用边界与选型理由

Keyless 适合连通性验证、低频脚本、内部看板这类对 429 有一定容忍度的场景。它共享按 IP 的限流池，流量不可预测，不做生产主链路；真正上线要么上带 key 的套餐，要么在后端代理层做缓存和合并请求。

后端代理这一层不是可选项。行情 key 放前端等于公开，CORS 也拦着直连；代理同时承担缓存（10~60s 足够覆盖多数展示场景）和多 id 合并，把上游请求数压到最低。

选 CoinGecko 还是 CoinMarketCap 取决于两点：一是需要的端点类型（CMC 的 DEX 端点、恐惧与贪婪指数、CMC100/CMC20 指数是它自己的数据；CoinGecko 的 WebSocket 从 Basic 起就有），二是 credit 计费模型——CoinGecko 每次请求 1 credit 口径直白，CMC 的分页和 convert 会按数据点/币种加计，批量拉取前先用 `/key/info` 对一遍账再决定档位。