K-Line API · 接口详情

历史 K 线查询

本模块用于查询已经采集并落库的 OHLCV 蜡烛图数据，适用于绘制历史 K 线图、补齐客户端断线期间数据，以及在实时订阅前加载初始行情。

查询时需要同时指定链、池、代币方向和 K 线周期。接口返回数组结构，未命中数据时通常返回空数组。

查询 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	是	-	池合约地址
`token`	string	否	`base`	`base` 或 `quote`

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&token=base"

成功响应

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`，默认 `base`
`intervals`	string[]	否	合法 K 线周期数组；省略或空数组表示接收所有周期。非法值会被静默忽略

注意： intervals 应使用 JSON 数组，不要发送逗号分隔字符串。

unsubscribe.data

字段	类型	必填	说明
`chain_type`	string	是	链类型，会自动归一化
`chain_id`	number	是	链 ID
`pool_address`	string	是	池合约地址
`token`	string	否	`base` 或 `quote`，默认 `base`

服务端消息结构

服务端下行消息统一为：

{
  "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",
    "token": "base",
    "intervals": ["1m", "1h", "4h"]
  }
}

订阅成功响应：

{
  "id": "sub-001",
  "time": 1776682800000,
  "type": "subscribed",
  "code": 0,
  "data": {
    "key": "evm:1:0xabc123def456: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",
    "token": "base"
  }
}

响应：

{
  "id": "unsub-001",
  "time": 1776682800000,
  "type": "unsubscribed",
  "code": 0,
  "data": {
    "key": "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 设置。

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`
`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 接入建议

时间戳处理

价格与成交量精度