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
代币方向	token 支持 base、quote，默认 base
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 连接并订阅实时推送。

---