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 工具中查詢加密數據
