CoinGlass API 教程:从获取 API Key 到拿到第一组比特币持仓数据,大约需要 5 分钟。本页给出可以直接运行的 cURL、Python 和 JavaScript 示例,并说明如何处理错误与限流。
| 项目 | 内容 |
|---|---|
| Base URL | https://open-api-v4.coinglass.com |
| 认证 | 请求头 CG-API-KEY |
| 测试接口 | GET /api/futures/supported-coins |
| 成功判断 | HTTP 状态码为 200 且 code 为 "0" |
| 常见错误 | 400:参数错误或 API Key 无效;401:密钥、接口权限或 API 等级问题,结合 msg 判断;429:限流。请同时检查 HTTP 状态和业务码 |
准备工作
第 1 步:获取 API Key
第 2 步:确认连接
先调用「支持的币种」接口,确认密钥可用。把 YOUR_API_KEY 换成你的密钥,返回的 code 为 "0" 即表示连接成功。
curl --request GET \
--url 'https://open-api-v4.coinglass.com/api/futures/supported-coins' \
--header 'accept: application/json' \
--header 'CG-API-KEY: YOUR_API_KEY'import requests
resp = requests.get(
"https://open-api-v4.coinglass.com/api/futures/supported-coins",
headers={"CG-API-KEY": "YOUR_API_KEY"},
timeout=10,
)
print(resp.status_code, resp.json()["code"])const res = await fetch(
"https://open-api-v4.coinglass.com/api/futures/supported-coins",
{ headers: { "CG-API-KEY": "YOUR_API_KEY" } }
);
const body = await res.json();
console.log(res.status, body.code);第 3 步:查询比特币持仓量
下面的示例调用「聚合持仓历史(K 线)」接口,获取比特币最近 7 天全市场的持仓量(Open Interest)。示例从环境变量 COINGLASS_API_KEY 读取密钥。
| 参数 | 必填 | 示例值 | 说明 |
|---|---|---|---|
symbol | 是 | BTC | 币种 |
interval | 是 | 1d | K 线周期,可选 1m、3m、5m、15m、30m、1h、2h、4h、6h、8h、12h、1d、1w,各 API 等级可用范围见时间周期与 interval |
limit | 否 | 7 | 返回条数,默认 1000,可传 1~1000 |
import os
import requests
API_KEY = os.environ["COINGLASS_API_KEY"]
BASE_URL = "https://open-api-v4.coinglass.com"
resp = requests.get(
BASE_URL + "/api/futures/open-interest/aggregated-history",
headers={"CG-API-KEY": API_KEY},
params={"symbol": "BTC", "interval": "1d", "limit": 7},
timeout=10,
)
body = resp.json()
for candle in body["data"]:
print(candle["time"], candle["close"])const params = new URLSearchParams({ symbol: "BTC", interval: "1d", limit: "7" });
const res = await fetch(
"https://open-api-v4.coinglass.com/api/futures/open-interest/aggregated-history?" + params,
{ headers: { "CG-API-KEY": process.env.COINGLASS_API_KEY } }
);
const body = await res.json();
for (const candle of body.data) {
console.log(candle.time, candle.close);
}响应结构如下。time 为毫秒时间戳;open、high、low、close 为周期内的持仓量,多数以字符串返回;最近一根尚未结束的 K 线中,部分字段可能以数字返回,计算前请统一转换为数字。
{
"code": "0",
"data": [
{
"time": 1760313600000,
"open": "<周期开始时的持仓量>",
"high": "<周期内最高持仓量>",
"low": "<周期内最低持仓量>",
"close": "<周期结束时的持仓量>"
}
]
}第 4 步:处理错误与限流
上线前至少处理下面三种情况。注意:这些错误的 HTTP 状态码通常仍是 200,要以 JSON 中的 code 判断。完整的返回码见错误码与频率限制。
| 情况 | 表现 | 处理方式 |
|---|---|---|
| 密钥缺失或无效 | code 为 "401"(缺少)或 "400"(无效) | 检查请求头名称是否为 CG-API-KEY,密钥是否完整复制 |
| 请求过快 | 返回码 429 | 等待后重试,每次等待时间加倍;长期超出上限时考虑升级 API 等级 |
| 业务失败 | code 不为 "0" | 读取 msg 字段排查,常见原因是参数错误或请求超出 API 等级范围 |
常见问题
可以在网页前端直接调用 CoinGlass API 吗?
不建议。在浏览器里发起请求会把 API Key 暴露给所有访问者。请由你自己的服务端调用 CoinGlass API,再把结果返回给前端。
为什么返回的数据条数比 limit 少?
可查询的历史长度由 API 等级和时间周期共同决定,超出范围的部分不会返回。各 API 等级的历史数据范围见API 等级与权限。
为什么返回 429?
每分钟的请求次数超过了 API 等级上限。业余、初创、标准、专业分别为每分钟 30、80、300、1,200 次,企业可定制。
CoinGlass API 使用教程:更多语言与工具
用 JavaScript(Node.js)调用
Node.js 18 及以上自带 fetch,可以直接请求 CoinGlass API。把 API Key 存在环境变量 COINGLASS_API_KEY 中,通过请求头 CG-API-KEY 发送,写法见上方第 3 步的 JavaScript 示例。
在 Google Sheets 中获取加密货币数据
在 Google Apps Script 中用 UrlFetchApp 请求接口,并在请求头中加入 CG-API-KEY,就能把比特币持仓量、资金费率等数据写入表格,配合定时触发器做成自动刷新的行情表。
新手推荐的第一批接口
支持的币种、聚合持仓历史、资金费率历史、币种爆仓历史和恐惧与贪婪指数,覆盖了大多数加密货币行情分析的起点。
相关文档
- 身份验证:获取与管理 CoinGlass API Key
- API 等级与权限:加密货币 API 价格与请求上限
- 错误码与频率限制:API 返回码与限流说明
- CoinGlass MCP(Beta):在 AI 工具中查询加密数据
