K-Line API · 簡介

服務簡介

服務簡介

K-Line API 是一個 K 線資料服務，核心能力包括：

• 查詢指定池的歷史 OHLCV 蠟燭圖資料
• 透過 WebSocket 動態訂閱即時 K 線推送
• 查詢市場行情、Top Holders 和代幣元資料

所有 HTTP 介面均掛載在 /kline/api/v1 路徑前綴下。目前對外提供服務的介面統一使用公共請求頭 X-API-Key 做介面鑑權和計費識別。

---

Base URL

所有介面請求均以下列生產環境地址為根路徑：

https://api.gelabs.org

範例：

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

---

統一回應結構

大多數 HTTP 介面成功時返回統一結構：

{
  "code": 0,
  "message": "ok",
  "data": {}
}

欄位	類型	必返回	說明
code	integer	是	業務狀態碼。成功固定為 0
message	string	是	回應訊息。成功固定為 ok
data	object / array / string	是	業務資料，具體結構隨介面變化

失敗回應通常為：

{
  "code": 10001,
  "message": "Invalid query params",
  "error": {
    "type": "ValidationError",
    "details": {
      "formErrors": [],
      "fieldErrors": {
        "chain_type": ["String must contain at least 1 character(s)"]
      }
    }
  }
}

---

錯誤碼

錯誤碼	含義	常見觸發場景
0	成功	正常回應
10001	參數驗證失敗	query、path 或 body 欄位缺失或格式不合法
10002	無效參數	參數值不符合業務約束
10003	資源不存在	路由或資源不存在
10004	資源衝突	重複建立同一池
10005	錯誤請求	WebSocket 預檢等錯誤請求場景
20001	未認證	預留，目前未啟用
20002	無權限	預留，目前未啟用
60001	K 線資源不存在	查詢不存在的池
60002	K 線同步失敗	預留
60003	無效 Symbol	預留
60004	無效時間間隔	預留
99001	伺服器內部錯誤	未捕獲異常、服務異常或限流
99002	資料庫錯誤	預留
99003	快取錯誤	預留

---

公共約定

項	說明
公共請求頭	所有對外介面均需攜帶 X-API-Key，用於介面鑑權和計費識別
Content-Type	POST 請求體使用 application/json，WebSocket 訊息使用 JSON 文字幀
時間戳	HTTP 歷史查詢參數 from、to 接受 Unix 秒或毫秒；大於 10000000000 的值按毫秒處理
鏈類型	chain_type 會歸一化為小寫，支援別名：eth/ethereum → evm、sol/solana → svm、trx/tron → tvm、btc/bitcoin 等 → utxo、atom → cosmos、sui/aptos/apt → move
代幣方向	WebSocket 訂閱會根據目前啟用的唯一池配置自動確定 base 或 quote，客戶端無需傳 token；HTTP OHLCV 查詢按 pool_address 查詢，忽略 token
K 線週期	支援 1s、1m、15m、1h、4h、1d、1w、1M、1Y。其中 1w、1M、1Y 由 1d 聚合查詢得出
分頁	請求參數為 page、page_size；回應分頁欄位為 page、pageSize、total、totalPages
快取	目前 HTTP 查詢介面未對外承諾固定 Cache-Control 策略；即時 WebSocket 訂閱成功後可能收到服務端記憶體中的最新快照

注意： 1w、1M、1Y 週期由已落庫的 1d K 線聚合查詢得出。

---

快速接入流程

建議按以下步驟接入：

1. 使用 GET /kline/api/v1/kline/ohlcv 查詢歷史 K 線。
2. 使用 GET /kline/api/v1/kline/ws 建立 WebSocket 連線並訂閱即時推送。

---