K-Line API · 介面詳情

歷史 K 線查詢

本模組用於查詢已經採集並落庫的 OHLCV 蠟燭圖資料，適用於繪製歷史 K 線圖、補齊客戶端斷線期間資料，以及在即時訂閱前載入初始行情。

查詢時需要同時指定鏈、池地址和 K 線週期。OHLCV 查詢按 pool_address 匹配池，忽略 token 參數。介面返回陣列結構，未命中資料時通常返回空陣列。

查詢 OHLCV 資料

請求

GET /kline/api/v1/kline/ohlcv

請求參數

參數	類型	必填	預設值	說明
`interval`	string	是	-	K 線週期：`1s`、`1m`、`15m`、`1h`、`4h`、`1d`、`1w`、`1M`、`1Y`
`from`	integer	是	-	查詢起始時間，Unix 秒或毫秒
`to`	integer	是	-	查詢結束時間，Unix 秒或毫秒
`limit`	integer	否	`1000`	最大返回筆數，範圍 1-5000
`chain_type`	string	是	-	鏈類型，會自動歸一化
`chain_id`	integer	是	-	鏈 ID，正整數
`pool_address`	string	是	-	池合約地址

curl 範例

curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/kline/api/v1/kline/ohlcv?interval=1h&from=1776679200&to=1776765600&limit=500&chain_type=evm&chain_id=1&pool_address=0xabc123def456"

成功回應

data 是 OHLCV 陣列，不再套 items：

{
  "code": 0,
  "message": "ok",
  "data": [
    {
      "pool_id": 42,
      "interval": "1h",
      "open_time": 1776679200,
      "open": 3500.12,
      "high": 3520,
      "low": 3480.5,
      "close": 3510.88,
      "volume": 1234567.89
    }
  ]
}

回應欄位

欄位	類型	必返回	說明
`pool_id`	integer	是	池的內部 ID
`interval`	string	是	K 線週期
`open_time`	integer	是	蠟燭開始時間，Unix 秒
`open`	number / null	是	開盤價
`high`	number / null	是	最高價
`low`	number / null	是	最低價
`close`	number / null	是	收盤價
`volume`	number / null	是	成交量

快取說明

歷史 K 線查詢目前未聲明固定 HTTP 快取頭。業務側可按 interval 自行設定短快取；即時性要求高的場景建議結合 WebSocket 推送刷新最新一根蠟燭。

常見錯誤回應

參數缺失或格式不合法時通常返回：

{
  "code": 10001,
  "message": "Invalid query params",
  "error": {
    "type": "ValidationError",
    "details": {
      "fieldErrors": {
        "interval": ["Required"],
        "pool_address": ["Required"]
      }
    }
  }
}

Market 行情介面

Market 介面使用 K-Line 服務統一成功回應，data 欄位返回對應市場資料。

本模組適用於查詢池和代幣的市場資訊，例如池詳情、Top Holders 和合約地址對應的代幣元資料。

注意： Market 介面主要用於輔助展示和偵錯，不等同於 K-Line 服務內部採集狀態。

取得池市場詳情

請求

GET /kline/api/v1/market/pools/{network}/{address}

參數	位置	類型	必填	說明
`network`	path	string	是	網路標識符，1-100 字元
`address`	path	string	是	池合約地址，1-200 字元
`include`	query	string	否	額外包含的欄位，逗號分隔
`include_volume_breakdown`	query	string	否	`"true"` 或 `"false"`
`include_composition`	query	string	否	`"true"` 或 `"false"`

curl 範例

curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/kline/api/v1/market/pools/eth/0xabc123def456?include=base_token,quote_token&include_volume_breakdown=true&include_composition=false"

快取說明

目前介面未在文件中承諾固定快取時長。

常見錯誤回應

請求失敗、限流或內部異常時通常返回：

{
  "code": 99001,
  "message": "Internal server error",
  "error": { "type": "InternalServerError" }
}

取得代幣 Top Holders

請求

GET /kline/api/v1/market/tokens/{network}/{address}/top-holders

參數	位置	類型	必填	說明
`network`	path	string	是	網路標識符，1-100 字元
`address`	path	string	是	代幣合約地址，1-200 字元
`holders`	query	string	否	正整數字串或 `max`
`include_pnl_details`	query	string	否	`"true"` 或 `"false"`

curl 範例

curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/kline/api/v1/market/tokens/eth/0xabc123def456/top-holders?holders=10&include_pnl_details=false"

快取說明

目前介面未在文件中承諾固定快取時長；請按業務展示需求控制呼叫頻率。

常見錯誤回應

{
  "code": 99001,
  "message": "Internal server error",
  "error": { "type": "InternalServerError" }
}

透過合約地址查詢代幣元資料

請求

GET /kline/api/v1/market/coins/{network}/{address}

參數	位置	類型	必填	說明
`network`	path	string	是	平台標識符，1-100 字元
`address`	path	string	是	代幣合約地址，1-200 字元

curl 範例

curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/kline/api/v1/market/coins/ethereum/0xabc123def456"

快取說明

目前代理介面未在文件中承諾固定快取時長。代幣元資料變化頻率通常較低，客戶端可按業務需要自行快取。

常見錯誤回應

{
  "code": 99001,
  "message": "Internal server error",
  "error": { "type": "InternalServerError" }
}

K-Line WebSocket

K-Line 即時推送使用單一 WebSocket 入口，連線建立後透過 JSON 訊息動態訂閱或退訂多個池。

本模組適用於需要低延遲接收 K 線變更的客戶端，例如行情頁面、告警服務和內部資料同步任務。客戶端建立連線後，可透過 subscribe / unsubscribe 動態維護多個池的訂閱。

建議客戶端同時保留 HTTP 歷史查詢能力：首次進入頁面或斷線重連後先用 HTTP 補齊歷史資料，再使用 WebSocket 推送更新最新蠟燭。

連線要求

連線地址

GET /kline/api/v1/kline/ws

必填請求頭

Header	必填	說明
`Upgrade: websocket`	是	標準 WebSocket 升級頭
`Connection: Upgrade`	是	標準 WebSocket 升級頭
`X-API-Key`	是	公共 API Key，用於介面鑑權和計費識別

注意： X-API-Key 是對外接入唯一必填業務請求頭。

未攜帶 WebSocket 升級頭時返回 HTTP 426：

{
  "code": 4000,
  "message": "WebSocket upgrade required",
  "error": { "type": "BadRequestError" }
}

缺少 X-API-Key 或鑑權失敗時通常返回 HTTP 401 或 403，具體以閘道配置為準：

{
  "code": 20001,
  "message": "Unauthorized",
  "error": { "type": "UnauthorizedError" }
}

協定常量

常量	字串值	方向	說明
`WS_TYPE_PING`	`ping`	客戶端 → 服務端	應用層心跳
`WS_TYPE_PONG`	`pong`	服務端 → 客戶端	心跳回應
`WS_TYPE_SUBSCRIBE`	`subscribe`	客戶端 → 服務端	訂閱池
`WS_TYPE_UNSUBSCRIBE`	`unsubscribe`	客戶端 → 服務端	退訂池
`WS_TYPE_SUBSCRIBED`	`subscribed`	服務端 → 客戶端	訂閱成功確認
`WS_TYPE_UNSUBSCRIBED`	`unsubscribed`	服務端 → 客戶端	退訂成功確認
`WS_TYPE_OHLCV`	`ohlcv`	服務端 → 客戶端	即時或快照 K 線推送

WebSocket code	說明
`0`	成功
`4001`	無效訊息，例如 JSON 解析失敗、缺少 `id`/`type`、訂閱欄位缺失
`4002`	未知命令
`4500`	內部錯誤，目前預留

客戶端訊息結構

客戶端訊息必須是 JSON 文字幀：

{
  "id": "req-001",
  "type": "subscribe",
  "data": {}
}

欄位	類型	必填	說明
`id`	string	是	請求關聯 ID，服務端回應會原樣帶回
`type`	string	是	`ping`、`subscribe`、`unsubscribe`
`data`	object	視命令而定	命令負載

subscribe.data

欄位	類型	必填	說明
`chain_type`	string	是	鏈類型，會自動歸一化
`chain_id`	number	是	鏈 ID
`pool_address`	string	是	池合約地址，內部池鍵會轉小寫
`token`	string	否	已相容保留；服務端會根據目前啟用的唯一池配置自動確定 `base` 或 `quote`，客戶端無需傳入
`intervals`	string[]	否	合法 K 線週期陣列；省略或空陣列表示接收所有週期。非法值會被靜默忽略

注意： intervals 應使用 JSON 陣列，不要傳送逗號分隔字串。

unsubscribe.data

欄位	類型	必填	說明
`chain_type`	string	是	鏈類型，會自動歸一化
`chain_id`	number	是	鏈 ID
`pool_address`	string	是	池合約地址
`token`	string	否	已相容保留；退訂會移除目前連線上該池已有訂閱，不依賴客戶端傳入 token

服務端訊息結構

服務端下行訊息統一為：

{
  "id": "req-001",
  "time": 1776682800000,
  "type": "subscribed",
  "code": 0,
  "data": {},
  "msg": "ok"
}

欄位	類型	必返回	說明
`id`	string	是	請求回應會回傳請求 ID；主動推送為 `""`
`time`	number	是	服務端 Unix 毫秒時間戳
`type`	string	是	`pong`、`subscribed`、`unsubscribed`、`ohlcv`、`error`
`code`	number	是	WebSocket 業務碼
`data`	object / null	是	業務負載
`msg`	string	是	可讀說明；即時推送為 `ok`，快照為 `snapshot`

訂閱與退訂範例

心跳

{ "id": "hb-001", "type": "ping", "data": {} }

回應：

{
  "id": "hb-001",
  "time": 1776682800000,
  "type": "pong",
  "code": 0,
  "data": {},
  "msg": "ok"
}

{
  "id": "sub-001",
  "type": "subscribe",
  "data": {
    "chain_type": "evm",
    "chain_id": 1,
    "pool_address": "0xabc123def456",
    "intervals": ["1m", "1h", "4h"]
  }
}

訂閱成功回應：

{
  "id": "sub-001",
  "time": 1776682800000,
  "type": "subscribed",
  "code": 0,
  "data": {
    "key": "evm:1:0xabc123def456:base",
    "token": "base",
    "intervals": ["1m", "1h", "4h"]
  },
  "msg": "ok"
}

若服務端快取中已有該池最新 tick，訂閱成功後會額外推送一筆 ohlcv，msg 為 snapshot。

退訂

{
  "id": "unsub-001",
  "type": "unsubscribe",
  "data": {
    "chain_type": "evm",
    "chain_id": 1,
    "pool_address": "0xabc123def456"
  }
}

回應：

{
  "id": "unsub-001",
  "time": 1776682800000,
  "type": "unsubscribed",
  "code": 0,
  "data": {
    "key": "evm:1:0xabc123def456:",
    "removed_keys": ["evm:1:0xabc123def456:base"]
  },
  "msg": "ok"
}

推送資料欄位

即時與快照推送都使用 type: "ohlcv"：

{
  "id": "",
  "time": 1776682800000,
  "type": "ohlcv",
  "code": 0,
  "data": {
    "chain_type": "evm",
    "chain_id": 1,
    "pool_address": "0xabc123def456",
    "token": "base",
    "interval": "1h",
    "open_time": 1776679200,
    "open": 3500.12,
    "high": 3520,
    "low": 3480.5,
    "close": 3510.88,
    "volume": 1234567.89
  },
  "msg": "ok"
}

欄位	類型	必返回	說明
`chain_type`	string / null	是	鏈類型
`chain_id`	number / null	是	鏈 ID
`pool_address`	string	是	池地址
`token`	string	是	代幣方向
`interval`	string	是	K 線週期
`open_time`	number	是	蠟燭開始時間，Unix 秒
`open`	number / null	是	開盤價
`high`	number / null	是	最高價
`low`	number / null	是	最低價
`close`	number / null	是	收盤價
`volume`	number / null	是	成交量

KlineHub 對二進位幀會靜默忽略，不返回錯誤訊息。未訂閱任何池時不會收到 ohlcv 推送。對同一池重複 subscribe 會覆蓋該池的 intervals 設定。訂閱成功時，服務端會使用目前啟用的唯一池配置生成訂閱 key；如果池不存在、未啟用或配置不唯一，會返回 error，不會寫入訂閱狀態。

WebSocket 錯誤訊息

{
  "id": "sub-001",
  "time": 1776682800000,
  "type": "error",
  "code": 4001,
  "data": null,
  "msg": "subscribe: missing required fields"
}

場景	code	msg 範例
JSON 解析失敗	`4001`	`Invalid JSON`
缺少 `id` 或 `type`	`4001`	`Missing id or type`
`subscribe` 缺少必填欄位	`4001`	`subscribe: missing required fields`
`subscribe` 未找到啟用池	`4001`	`subscribe: active pool not found`
`subscribe` 命中多個啟用池配置	`4500`	`subscribe: ambiguous active pool`
`unsubscribe` 缺少必填欄位	`4001`	`unsubscribe: missing required fields`
未知命令	`4002`	`Unknown command: xxx`

通用 WebSocket

通用 WebSocket 路徑為：

GET /kline/api/v1/ws/{topic}

topic 會作為 Durable Object 實例名稱。目前公開能力僅支援應用層 ping/pong。

客戶端訊息

{ "id": "req-001", "type": "ping", "data": {} }

服務端回應

{
  "id": "req-001",
  "time": 1704070800000,
  "type": "pong",
  "code": 0,
  "data": {},
  "msg": "ok"
}

普通 HTTP 請求存取該路徑會返回 HTTP 426 純文字：

Expected WebSocket upgrade

與 KlineHub 不同，通用 WsServer 收到二進位幀會返回 error 訊息，code 為 4001，msg 為 Binary messages are not supported。

注意： 通用 WebSocket 目前僅適合作為連通性或基礎訊息通道驗證；K 線即時行情請使用 /kline/api/v1/kline/ws。

錯誤處理與最佳實務

常見 HTTP 錯誤

HTTP	常見業務碼	說明
400	`10001` / `10002` / `10005`	請求參數缺失、格式不合法，或 WebSocket 預檢請求錯誤
404	`10003` / `60001`	路由、池或資源不存在
409	`10004`	重複建立同一池等資源衝突
500	`99001` / `99002` / `99003`	服務內部異常、資料庫異常或快取異常

呼叫方應同時關注 HTTP 狀態碼和回應體 code。業務成功以 code: 0 為準。

WebSocket 接入建議

項目	建議
心跳	客戶端定期傳送 `{ "id": "hb-001", "type": "ping", "data": {} }` JSON 訊息，並檢查服務端 `pong`
重連	連線斷開後使用指數退避重連，重連成功後重新傳送訂閱
補資料	重連後先透過 `GET /kline/api/v1/kline/ohlcv` 查詢斷線期間歷史資料，再繼續消費即時推送
冪等	對同一池、同一 `interval`、同一 `open_time` 的 K 線更新做覆蓋寫入
訂閱管理	對同一池重複 `subscribe` 會覆蓋該池的 `intervals` 設定，客戶端應維護本地訂閱狀態

時間戳處理

HTTP 查詢參數 from、to 支援 Unix 秒或毫秒；服務端會將大於 10000000000 的值按毫秒處理。
OHLCV 欄位 open_time 使用 Unix 秒，WebSocket 信封欄位 time 使用 Unix 毫秒。
客戶端展示跨時區行情時，建議統一以 UTC 儲存，再在展示層轉換時區。

價格與成交量精度

open、high、low、close、volume 可能為 null，客戶端展示和計算時需要顯式處理。
對價格、成交量和市值等數值欄位，建議使用高精度 decimal 類型或字串化儲存，避免 JavaScript number 精度問題。
Market 行情介面返回的欄位類型可能與 K-Line 自身 OHLCV 欄位不完全一致。

文件版本：v1.0.0 | 最後更新：2026-04-28

歷史 K 線查詢​

查詢 OHLCV 資料​

Market 行情介面​

取得池市場詳情​

取得代幣 Top Holders​

透過合約地址查詢代幣元資料​

K-Line WebSocket​

連線要求​

協定常量​

客戶端訊息結構​

服務端訊息結構​

訂閱與退訂範例​

推送資料欄位​

WebSocket 錯誤訊息​

通用 WebSocket​

錯誤處理與最佳實務​

常見 HTTP 錯誤​

WebSocket 接入建議​

時間戳處理​

價格與成交量精度​

歷史 K 線查詢

查詢 OHLCV 資料

Market 行情介面

取得池市場詳情

取得代幣 Top Holders

透過合約地址查詢代幣元資料

K-Line WebSocket

連線要求

協定常量

客戶端訊息結構

服務端訊息結構

訂閱與退訂範例

推送資料欄位

WebSocket 錯誤訊息

通用 WebSocket

錯誤處理與最佳實務

常見 HTTP 錯誤

WebSocket 接入建議

時間戳處理

價格與成交量精度