CoinGecko 行情数据 API调用手册
制作市值行情列表
取得价格、市值、成交量与市值排名,并按页读取。
← 返回平台功能接入准备
- 注册 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。
调用步骤
- 01
进入 CoinGecko Developer Dashboard,选择 Demo API,创建并复制 API Key 到自己的服务端环境变量 CG_DEMO_API_KEY。
- 02
先运行单次查询,确认返回币种 ID、报价单位和更新时间,再决定缓存与刷新周期。
- 03
若要查询其他资产,从币种页面 API ID 或 /coins/list 获取唯一 ID,避免用有歧义的 ticker 代替。
调用 01
取得市场列表
本接口参数 vs_currency 为单数,与 simple/price 的参数名不同。
GET
https://api.coingecko.com/api/v3/coins/markets?vs_currency=usd&order=market_cap_desc&per_page=20&page=1&sparkline=false请求头
x-cg-demo-api-key${CG_DEMO_API_KEY}Acceptapplication/json
参数说明
参数表可左右滑动,查看完整说明。
| 字段 / 位置 | 类型 / 必填 | 说明 |
|---|---|---|
vs_currencyQuery | string必填 | 市场数据报价币种,例如 usd。 |
orderQuery | string可选 | 默认 market_cap_desc,示例按市值倒序。 |
per_pageQuery | integer可选 | 每页 1–250,默认 100;示例 20。 |
pageQuery | integer可选 | 页码,从 1 开始;下一页将 page 加 1。 |
sparklineQuery | boolean可选 | 是否包含 7 日迷你图数组,示例 false 减少返回量。 |
调用代码
替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误,业务状态还需按下方返回示例核对。
# 执行后核对返回 JSON 的业务状态;HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
--request GET \
--url "https://api.coingecko.com/api/v3/coins/markets?vs_currency=usd&order=market_cap_desc&per_page=20&page=1&sparkline=false" \
--header "x-cg-demo-api-key: ${CG_DEMO_API_KEY}" \
--header "Accept: application/json"
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/markets?vs_currency=usd&order=market_cap_desc&per_page=20&page=1&sparkline=false")
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 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/markets?vs_currency=usd&order=market_cap_desc&per_page=20&page=1&sparkline=false");
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));
返回示例
按官方结构整理的节选示意,非实测结果。响应为数组;current_price、market_cap、total_volume 以 vs_currency 计价;部分数值允许 null。 以下为结构示意,非本站实测结果。
[
{
"id": "bitcoin",
"symbol": "btc",
"name": "Bitcoin",
"current_price": 60000,
"market_cap": 1200000000000,
"market_cap_rank": 1,
"total_volume": 1000000000,
"last_updated": "2025-01-01T00:00:00Z"
}
]常见错误与排查
HTTP 401 / 403鉴权或访问受限- 确认使用 Demo Key 与 Demo 根地址,检查后台密钥状态及方案权限。
HTTP 429请求过于频繁- 停止高频轮询,等待窗口恢复;检查开发者后台当前额度和每分钟限制。
调用注意
- 保存 id 作为资产主键;symbol 可能重复。分页过程中行情会变化,不能把跨页结果当成同一时刻的快照。
注意事项
- Demo 配额、更新速度与商用许可以当前方案为准;免费 Key 不代表无限调用或允许任意再分发。
- 本页查询聚合行情,不提供交易或投资操作,返回数值全部为字段示意。
核验来源
本站按官方资料整理本场景的必要调用步骤与代码,覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。
- 01Demo API 鉴权与根地址核验日期 2026-10-15
- 02Demo 币种市场数据与分页核验日期 2026-10-15
- 03CoinGecko 错误与频控核验日期 2026-10-15
