CoinGecko 行情数据 API调用手册

读取近 7 天历史价格

获得绘图所需的时间和价格点,同时了解历史范围与自动粒度。

官方资料核对 2026-10-15示例代码,未进行真实接口实测
← 返回平台功能

接入准备

  • 注册 CoinGecko 账号,在 Developer Dashboard 创建 Demo API Key。
  • 本手册统一使用 api.coingecko.com 与 x-cg-demo-api-key;Pro 套餐需同时更换根地址和对应认证头。

准备环境变量

示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行;密钥不应放进公开网页。

CG_DEMO_API_KEY
CoinGecko Developer Dashboard 创建的 Demo API Key;与 Pro Key 不通用。
终端
export CG_DEMO_API_KEY='replace_with_demo_api_key'

以上 export 适用于 macOS / Linux 的终端,在同一终端内运行后续代码。Python 示例保存为 request.py 后执行 python3 request.py。

调用步骤

  1. 01

    进入 CoinGecko Developer Dashboard,选择 Demo API,创建并复制 API Key 到自己的服务端环境变量 CG_DEMO_API_KEY。

  2. 02

    先运行单次查询,确认返回币种 ID、报价单位和更新时间,再决定缓存与刷新周期。

  3. 03

    若要查询其他资产,从币种页面 API ID 或 /coins/list 获取唯一 ID,避免用有歧义的 ticker 代替。

调用 01

取得历史序列

省略 interval,让接口按时间范围决定粒度;近 7 天通常为小时点。

GEThttps://api.coingecko.com/api/v3/coins/bitcoin/market_chart?vs_currency=usd&days=7

请求头

x-cg-demo-api-key
${CG_DEMO_API_KEY}
Accept
application/json

参数说明

参数表可左右滑动,查看完整说明。

字段 / 位置类型 / 必填说明
idPathstring必填CoinGecko 唯一资产 ID,示例 bitcoin。
vs_currencyQuerystring必填报价货币,例如 usd。
daysQueryinteger/string必填向前查询天数,示例 7;Demo 历史最多覆盖过去 365 天。
intervalQuerystring可选可省略自动决定;当前参数支持 hourly、daily,仍受方案和范围条件约束。

调用代码

替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误,业务状态还需按下方返回示例核对。

cURL
# 执行后核对返回 JSON 的业务状态;HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
  --request GET \
  --url "https://api.coingecko.com/api/v3/coins/bitcoin/market_chart?vs_currency=usd&days=7" \
  --header "x-cg-demo-api-key: ${CG_DEMO_API_KEY}" \
  --header "Accept: application/json"
Python 3
import json
import os
import re
import urllib.request
import urllib.error

def expand(value):
    return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
                  lambda match: os.environ[match.group(1)], value)

url = expand("https://api.coingecko.com/api/v3/coins/bitcoin/market_chart?vs_currency=usd&days=7")
headers = {
    "x-cg-demo-api-key": expand("${CG_DEMO_API_KEY}"),
    "Accept": expand("application/json"),
}
data = None
request = urllib.request.Request(url, data=data, headers=headers, method="GET")
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
    raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))
Node.js
// Node.js 22+,保存为 request.mjs 后运行 node request.mjs
function expand(value) {
  return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
    if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
    return process.env[name];
  });
}

const url = expand("https://api.coingecko.com/api/v3/coins/bitcoin/market_chart?vs_currency=usd&days=7");
const headers = Object.fromEntries(
  Object.entries({
  "x-cg-demo-api-key": "${CG_DEMO_API_KEY}",
  "Accept": "application/json"
}).map(([key, value]) => [key, expand(value)])
);
const response = await fetch(url, {
  method: "GET",
  headers,
  signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));

返回示例

按官方结构整理的节选示意,非实测结果。prices、market_caps、total_volumes 分别是 [毫秒时间戳, 数值] 数组;这里不是 OHLC K线。 以下为结构示意,非本站实测结果。

JSON
{
  "prices": [
    [
      1735689600000,
      60000
    ],
    [
      1735693200000,
      60100
    ]
  ],
  "market_caps": [
    [
      1735689600000,
      1200000000000
    ]
  ],
  "total_volumes": [
    [
      1735689600000,
      1000000000
    ]
  ]
}

常见错误与排查

HTTP 401 / 403鉴权或访问受限
确认使用 Demo Key 与 Demo 根地址,检查后台密钥状态及方案权限。
HTTP 429请求过于频繁
停止高频轮询,等待窗口恢复;检查开发者后台当前额度和每分钟限制。

调用注意

  • 默认自动粒度为近 1 天的 5 分钟点、2–90 天的小时点、超过 90 天的 UTC 日点;不要假设每个请求返回固定点数。
  • 图表时间戳为毫秒,simple/price 的更新时间为秒;转换时注意单位。

注意事项

  • Demo 配额、更新速度与商用许可以当前方案为准;免费 Key 不代表无限调用或允许任意再分发。
  • 本页查询聚合行情,不提供交易或投资操作,返回数值全部为字段示意。

核验来源

本站按官方资料整理本场景的必要调用步骤与代码,覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。

  1. 01
    Demo API 鉴权与根地址核验日期 2026-10-15
  2. 02
    Demo 历史行情与粒度限制核验日期 2026-10-15
  3. 03
    CoinGecko 错误与频控核验日期 2026-10-15

CoinGecko 行情数据 API的其他调用手册

← 返回CoinGecko 行情数据 API的全部功能