快速開始

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,就能把比特幣持倉量、資金費率等數據寫入表格,配合定時觸發器做成自動刷新的行情表。

新手推薦的第一批接口

支援的幣種、聚合持倉歷史、資金費率歷史、幣種爆倉歷史和恐懼與貪婪指數,覆蓋了大多數加密貨幣行情分析的起點。

相關文件