快速开始

CoinGlass API 教程:从获取 API Key 到拿到第一组比特币持仓数据,大约需要 5 分钟。本页给出可以直接运行的 cURL、Python 和 JavaScript 示例,并说明如何处理错误与限流。

本页要点
项目内容
Base URLhttps://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 状态和业务码

准备工作

账号
已订阅 API 等级的 CoinGlass 账号
运行环境
终端(cURL)、Python 3,或 Node.js 18 及以上
预计用时
5 分钟

第 1 步:获取 API Key

登录 CoinGlass 账号,在个人中心查看 API Key。还没有账号的话,先注册;还没有订阅 API 的话,先在API 等级与权限中选择适合的 API 等级。

⚠️

保管好你的 API Key

API Key 等同于账号密码。不要写进网页前端、App 安装包或公开的代码仓库,建议存放在服务端的环境变量中。

第 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是1dK 线周期,可选 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,就能把比特币持仓量、资金费率等数据写入表格,配合定时触发器做成自动刷新的行情表。

新手推荐的第一批接口

支持的币种、聚合持仓历史、资金费率历史、币种爆仓历史和恐惧与贪婪指数,覆盖了大多数加密货币行情分析的起点。

相关文档