時間戳與分頁

CoinGlass API 的時間參數使用毫秒時間戳(UTC);返回欄位中的時間多數是毫秒,少數接口是秒或納秒,以接口頁為準。歷史類接口用 start_time、end_time 和 limit 控制返回範圍,需要的數據超過單次上限時,按時間分段多次請求。

本頁要點
項目內容
時間格式請求參數為 13 位毫秒時間戳(UTC);返回欄位多數為毫秒,少數接口為秒或納秒
範圍參數start_time、end_time(毫秒)、limit
limit預設值多為 1000;公開上限不超過 1000,部分接口更小,以接口頁為準
分頁方法按 interval × limit 把時間區間切成多段,逐段請求
時區換算代碼中統一用 UTC 處理,展示時再按用戶所在時區換算

時間格式

範例含義
17603136000002025-10-13 00:00:00 UTC,13 位毫秒時間戳
176031360010 位秒級時間戳,需要乘以 1000 後再傳入

請求參數 start_time、end_time 一律傳毫秒。返回欄位中的時間多數也是毫秒,但有例外:訂單簿熱力圖、足跡圖、清算熱力圖的價格 K 線、Coinbase 溢價指數、借貸利率、Bitfinex 槓桿多空倉位和鏈上轉帳等接口返回 10 位秒級時間戳,比特幣 ETF 詳情的 last_updated 是 19 位納秒時間戳。換算前請先看各接口頁的欄位說明。

⚠️

注意時區

時間戳本身不帶時區,換算成日期時請明確使用 UTC。同一個時間戳在不同時區顯示的日期和時刻不同,例如 1760313600000 在 UTC+8 顯示為 2025-10-13 08:00,在 UTC−5 顯示為 2025-10-12 19:00。

範圍參數

參數類型說明
start_timeinteger起始時間,毫秒時間戳,可選
end_timeinteger結束時間,毫秒時間戳,可選
limitinteger返回條數,預設值多為 1000;公開上限不超過 1000,訂單簿熱力圖為 100,以接口頁為準

是否支援這些參數、limit 的上限,以各接口頁的參數說明為準。

多數帶 interval 的歷史類接口按以下規則處理時間範圍(財經日曆等接口另有規則,以接口頁為準):

情況處理方式
不傳 start_time、end_time以當前時間為終點,向前取 interval × limit 的範圍
只傳 start_time終點為 start_time + interval × limit
end_time 晚於當前時間按當前時間處理
start_time 不在週期邊界上自動推到下一個整週期開始,例如 4h 推到 UTC 0、4、8 點
區間邊界包含開始時間,不包含結束時間;不足 1 秒的部分會被截斷
超出 API 等級範圍start_time 會自動改成你的 API 等級能查到的最早時間,單次查詢的跨度也有上限

返回記錄中的 time 是每個週期的開始時間。

分段獲取長歷史

需要的數據超過單次 limit 上限時,把目標時間區間按「interval × limit」切成若干段,每段用 start_time、end_time 單獨請求,最後按 time 去重並排序。這種方式不依賴接口返回數據的排列順序。

確定時間區間
start 至 end,毫秒時間戳
按 interval × limit 切段
每段不超過單次 limit 上限
逐段請求
每段傳 start_time、end_time
按 time 去重排序
得到完整的歷史數據
import os
import time
import requests

BASE_URL = "https://open-api-v4.coinglass.com"
HEADERS = {"CG-API-KEY": os.environ["COINGLASS_API_KEY"]}
INTERVAL_MS = {'1m': 60000, '3m': 180000, '5m': 300000, '15m': 900000, '30m': 1800000, '1h': 3600000, '2h': 7200000, '4h': 14400000, '6h': 21600000, '8h': 28800000, '12h': 43200000, '1d': 86400000, '1w': 604800000}

# 按你的 API 等級填寫每分鐘請求上限:業餘 30、創業 80、標準 300、專業 1200;同一個 Key 的其他程式也會佔用額度,可以再調低
REQUESTS_PER_MINUTE = 30

def fetch_range(path, params, interval, start_ms, end_ms, limit=1000):
    if interval not in INTERVAL_MS:
        raise ValueError(f"不支援的 interval: {interval}")
    if isinstance(limit, bool) or not isinstance(limit, int) or not 1 <= limit <= 1000:
        raise ValueError("limit 必須是 1~1000 的整數")
    step = INTERVAL_MS[interval] * limit
    rows = {}
    for s in range(start_ms, end_ms, step):
        query = dict(params, interval=interval, limit=limit,
                     start_time=s, end_time=min(s + step, end_ms))
        resp = requests.get(BASE_URL + path, headers=HEADERS, params=query, timeout=10)
        body = resp.json()
        if body.get("code") != "0":
            raise RuntimeError(body.get("msg"))
        for r in body["data"]:
            rows[r["time"]] = r          # 以 time 去重
        time.sleep(60 / REQUESTS_PER_MINUTE)  # 按每分鐘請求上限控制間隔
    return [rows[t] for t in sorted(rows)]
const BASE_URL = "https://open-api-v4.coinglass.com";
const HEADERS = { "CG-API-KEY": process.env.COINGLASS_API_KEY };
const INTERVAL_MS = {"1m": 60000, "3m": 180000, "5m": 300000, "15m": 900000, "30m": 1800000, "1h": 3600000, "2h": 7200000, "4h": 14400000, "6h": 21600000, "8h": 28800000, "12h": 43200000, "1d": 86400000, "1w": 604800000};

// 按你的 API 等級填寫每分鐘請求上限:業餘 30、創業 80、標準 300、專業 1200;同一個 Key 的其他程式也會佔用額度,可以再調低
const REQUESTS_PER_MINUTE = 30;

async function fetchRange(path, params, interval, startMs, endMs, limit = 1000) {
  if (!Object.prototype.hasOwnProperty.call(INTERVAL_MS, interval)) {
    throw new RangeError(`不支援的 interval: ${interval}`);
  }
  if (!Number.isInteger(limit) || limit < 1 || limit > 1000) {
    throw new RangeError("limit 必須是 1~1000 的整數");
  }
  const step = INTERVAL_MS[interval] * limit;
  const rows = new Map();
  for (let s = startMs; s < endMs; s += step) {
    const query = new URLSearchParams({
      ...params, interval, limit,
      start_time: s, end_time: Math.min(s + step, endMs),
    });
    const body = await (await fetch(`${BASE_URL}${path}?${query}`, { headers: HEADERS })).json();
    if (body.code !== "0") throw new Error(body.msg);
    for (const r of body.data) rows.set(r.time, r); // 以 time 去重
    await new Promise((r) => setTimeout(r, 60000 / REQUESTS_PER_MINUTE)); // 按每分鐘請求上限控制間隔
  }
  return [...rows.keys()].sort((a, b) => a - b).map((t) => rows.get(t));
}

因為結束時間不包含在內,每段的 end_time 直接取下一段的 start_time,相鄰兩段首尾相接、不會漏掉數據。範例適用於 data 為物件陣列、data[].time 為毫秒的 K 線類接口;返回秒級時間或其他結構的接口,請按接口頁調整。範例中的 limit 取 1000;接口上限小於 1000 時,請按該接口的上限調整。仍然觸發 429 時,按錯誤碼與頻率限制中的方法等待後重試。

start_ms 建議對齊到週期邊界(例如 4h 對齊到 UTC 0、4、8 點),否則接口會從下一個週期邊界開始返回。累計類指標(如 CVD 的累計值)會以每段的第一條記錄為起點重新累加,分段下載時請保存每個週期的原始值,自己續算累計值,不要直接拼接各段的累計結果。

帶自動重試的請求寫法見錯誤碼與頻率限制。可查詢的最早時間受 API 等級限制,見時間週期與 interval。

常見問題

分頁時出現重複的數據怎麼辦?

以 time 欄位作為唯一鍵去重。相鄰兩段的邊界可能落在同一根 K 線上,去重後再按 time 排序即可。

翻到某個時間點之前不再返回數據,是什麼原因?

通常是已經到達 API 等級允許的歷史邊界,或該幣種、交易對在那之前尚未上線。可以對照API 等級與權限中的歷史數據表。

毫秒時間戳轉換與時區

Python 毫秒時間戳轉日期

使用 datetime.fromtimestamp(ts / 1000, tz=timezone.utc) 得到 UTC 時間;反過來用 int(dt.timestamp() * 1000) 生成接口需要的毫秒時間戳。

JavaScript 時間戳轉日期

JavaScript 的 Date 本身使用毫秒:new Date(ts).toISOString() 返回 UTC 時間,Date.now() 返回當前時間的毫秒時間戳,可以直接作為 end_time 傳入。

本地時間與 UTC 如何換算?

UTC = 本地時間 − 時區偏移。例如在 UTC+8 時區,要查詢本地某天 0 點之後的數據,start_time 應設為前一天 UTC 16:00 對應的毫秒時間戳。建議代碼中統一用 UTC 處理,展示時再轉換為用戶所在時區。

相關文件