K-Line API 使用说明

版本：1.0.0
适用对象：接入方开发者、行情服务调用方、运维人员

本文档面向接入方开发者，介绍如何使用 K-Line API 管理采集池、查询历史 OHLCV 数据、订阅实时 K 线推送，以及调用行情代理与运维调试接口。

1. 快速开始

1.1 服务简介

K-Line API 是一个 K 线数据服务，核心能力包括：

管理需要采集的链上流动性池
查询指定池的历史 OHLCV 蜡烛图数据
通过 WebSocket 动态订阅实时 K 线推送
代理查询 CoinGecko 市场行情、Top Holders 和代币元数据
查看采集器与 KlineHub Durable Object 运行状态

所有 HTTP 接口均挂载在 /api/v1 路径前缀下。当前对外提供服务的接口统一使用公共请求头 X-API-Key 做接口鉴权和计费识别；转发层内部使用的请求头不作为对外接入要求。

1.2 Base URL

所有接口请求均以以下生产环境地址为根路径：

https://api.gelabs.org

示例：

curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/api/v1/health"

1.3 统一响应结构

大多数 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)"]
      }
    }
  }
}

注意： 运维调试接口中，/api/v1/admin/debug/ingester/ensure 返回纯文本 ok，/api/v1/admin/debug/ingester/status 和 /api/v1/admin/debug/hub/status 返回 Durable Object 裸 JSON，不使用统一响应包装。

1.4 错误码

错误码	含义	常见触发场景
`0`	成功	正常响应
`10001`	参数校验失败	query、path 或 body 字段缺失或格式不合法
`10002`	无效参数	参数值不符合业务约束
`10003`	资源不存在	路由不存在、CoinGecko 资源不存在
`10004`	资源冲突	重复创建同一池
`10005`	错误请求	WebSocket 预检等错误请求场景
`20001`	未认证	预留，当前未启用
`20002`	无权限	预留，当前未启用
`60001`	K 线资源不存在	查询不存在的池
`60002`	K 线同步失败	预留
`60003`	无效 Symbol	预留
`60004`	无效时间间隔	预留
`99001`	服务器内部错误	未捕获异常、上游异常、限流
`99002`	数据库错误	预留
`99003`	缓存错误	预留

1.5 公共约定

项	说明
公共请求头	所有对外接口均需携带 `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.6 快速接入流程

推荐按以下步骤接入：

调用 GET /api/v1/health 确认服务可用。
调用 POST /api/v1/admin/pools 创建需要采集的流动性池。
调用 PATCH /api/v1/admin/pools/{id}/activate 激活池，触发采集器订阅上游实时数据。
使用 GET /api/v1/kline/ohlcv 查询历史 K 线。
使用 GET /api/v1/kline/ws 建立 WebSocket 连接并订阅实时推送。

2. 池管理接口

池用于描述需要采集 K 线数据的链上流动性池。创建后默认 is_active: false，需要调用激活接口后才会通知采集器订阅上游实时数据。

本模块适用于：

预先登记需要采集 OHLCV 的链上池
控制采集器是否订阅指定池的实时行情
查询当前系统内已登记池的状态和元信息

2.1 创建池

请求

POST /api/v1/admin/pools

请求体

字段	类型	必填	说明
`chain_type`	string	是	链类型，1-50 字符，服务端会归一化
`chain_id`	integer	是	链 ID，正整数
`network_id`	string	是	CoinGecko 网络标识符，1-50 字符，例如 `eth`
`pool_address`	string	是	池合约地址，1-100 字符
`token`	string	否	`base` 或 `quote`，默认 `base`
`dex_id`	string	否	DEX 标识符，1-100 字符
`label`	string	否	可读标签，最长 100 字符

curl 示例

curl -X POST "https://api.gelabs.org/api/v1/admin/pools" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chain_type": "evm",
    "chain_id": 1,
    "network_id": "eth",
    "pool_address": "0xabc123def456",
    "token": "base",
    "dex_id": "uniswap_v3",
    "label": "ETH/USDC"
  }'

成功响应

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": 42,
    "chain_type": "evm",
    "chain_id": 1,
    "network_id": "eth",
    "pool_address": "0xabc123def456",
    "token": "base",
    "dex_id": "uniswap_v3",
    "label": "ETH/USDC",
    "is_active": false,
    "created_at": "2026-04-16T08:00:00.000Z",
    "updated_at": "2026-04-16T08:00:00.000Z"
  }
}

池对象字段

字段	类型	必返回	说明
`id`	integer	是	池的内部 ID
`chain_type`	string	是	归一化后的链类型
`chain_id`	integer	是	链 ID
`network_id`	string	是	CoinGecko 网络标识符
`pool_address`	string	是	池合约地址
`token`	string	是	采集的代币方向，`base` 或 `quote`
`dex_id`	string / null	否	DEX 标识符
`label`	string / null	否	可读标签
`is_active`	boolean	是	是否已激活采集
`created_at`	string	是	ISO 8601 创建时间
`updated_at`	string	是	ISO 8601 更新时间

常见错误响应

重复创建同一池时通常返回 HTTP 409：

{
  "code": 10004,
  "message": "Pool already exists",
  "error": { "type": "ConflictError" }
}

2.2 获取池列表

请求

GET /api/v1/admin/pools

请求参数

参数	类型	必填	默认值	说明
`page`	integer	否	`1`	页码，从 1 开始
`page_size`	integer	否	`20`	每页条数，范围 1-100

curl 示例

curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/api/v1/admin/pools?page=1&page_size=20"

缓存说明

池管理接口直接读取数据库状态，当前不对外承诺固定 HTTP 缓存策略。客户端如需缓存，应在激活、停用或重新创建池后主动刷新。

成功响应

{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [
      {
        "id": 42,
        "chain_type": "evm",
        "chain_id": 1,
        "network_id": "eth",
        "pool_address": "0xabc123def456",
        "token": "base",
        "dex_id": "uniswap_v3",
        "label": "ETH/USDC",
        "is_active": true,
        "created_at": "2026-04-16T08:00:00.000Z",
        "updated_at": "2026-04-16T09:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 1,
      "totalPages": 1
    }
  }
}

2.3 获取池详情

请求

GET /api/v1/admin/pools/{id}

路径参数	类型	必填	说明
`id`	integer	是	池的内部 ID，正整数

curl 示例

curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/api/v1/admin/pools/42"

响应 data 为单个池对象，字段同创建池响应。池不存在时返回 HTTP 404，业务错误码通常为 60001。

常见错误响应

{
  "code": 60001,
  "message": "Pool not found",
  "error": { "type": "NotFoundError" }
}

2.4 激活池

请求

PATCH /api/v1/admin/pools/{id}/activate

激活后，服务会尽力通知 OhlcvIngester 订阅该池上游实时数据。通知失败不会回滚数据库状态，池状态以数据库为准。

curl 示例

curl -X PATCH "https://api.gelabs.org/api/v1/admin/pools/42/activate" \
  -H "X-API-Key: $API_KEY"

成功时返回更新后的池对象，is_active 为 true。

2.5 停用池

请求

PATCH /api/v1/admin/pools/{id}/deactivate

停用后，服务会尽力通知 OhlcvIngester 取消订阅该池上游实时数据。通知失败不会回滚数据库状态，池状态以数据库为准。

curl 示例

curl -X PATCH "https://api.gelabs.org/api/v1/admin/pools/42/deactivate" \
  -H "X-API-Key: $API_KEY"

成功时返回更新后的池对象，is_active 为 false。

3. 历史 K 线查询

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

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

3.1 查询 OHLCV 数据

请求

GET /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/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"]
      }
    }
  }
}

4. Market 行情代理接口

Market 接口代理 CoinGecko API。外层仍使用 K-Line 服务统一成功响应，data 字段为 CoinGecko 返回的原始业务结构。

本模块适用于在 K 线服务侧顺带查询池和代币的外部市场信息，例如池详情、Top Holders 和合约地址对应的代币元数据。由于业务数据透传自 CoinGecko，字段结构可能随上游版本演进。

注意： Market 接口主要用于辅助展示和调试，不等同于 K-Line 服务内部采集状态；池未登记或未激活不影响通过 Market 接口查询上游数据。

4.1 获取池市场详情

请求

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

参数	位置	类型	必填	说明
`network`	path	string	是	CoinGecko 网络标识符，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/api/v1/market/pools/eth/0xabc123def456?include=base_token,quote_token&include_volume_breakdown=true&include_composition=false"

缓存说明

当前代理接口未在文档中承诺固定缓存时长。上游 CoinGecko 的响应延迟、限流和缓存行为可能影响最终结果。

常见错误响应

上游请求失败、限流或内部异常时通常返回：

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

4.2 获取代币 Top Holders

请求

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

参数	位置	类型	必填	说明
`network`	path	string	是	CoinGecko 网络标识符，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/api/v1/market/tokens/eth/0xabc123def456/top-holders?holders=10&include_pnl_details=false"

缓存说明

当前代理接口未在文档中承诺固定缓存时长；请按上游数据更新频率和业务展示需求控制调用频率。

常见错误响应

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

4.3 通过合约地址查询代币元数据

请求

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

参数	位置	类型	必填	说明
`network`	path	string	是	CoinGecko 平台标识符，1-100 字符
`address`	path	string	是	代币合约地址，1-200 字符

curl 示例

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

缓存说明

当前代理接口未在文档中承诺固定缓存时长。代币元数据变化频率通常较低，客户端可按业务需要自行缓存。

常见错误响应

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

5. K-Line WebSocket

K-Line 实时推送使用单一 WebSocket 入口，连接建立后通过 JSON 消息动态订阅或退订多个池。

本模块适用于需要低延迟接收 K 线变更的客户端，例如行情页面、告警服务和内部数据同步任务。客户端建立连接后，可通过 subscribe / unsubscribe 动态维护多个池的订阅。

推荐客户端同时保留 HTTP 历史查询能力：首次进入页面或断线重连后先用 HTTP 补齐历史数据，再使用 WebSocket 推送更新最新蜡烛。

5.1 连接要求

连接地址

GET /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" }
}

5.2 协议常量

常量	字符串值	方向	说明
`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`	内部错误，当前预留

5.3 客户端消息结构

客户端消息必须是 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`

5.4 服务端消息结构

服务端下行消息统一为：

{
  "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`

5.5 订阅与退订示例

心跳

{ "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"
}

5.6 推送数据字段

实时与快照推送都使用 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 设置。

5.7 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`

6. 通用 WebSocket

通用 WebSocket 路径为：

GET /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 线实时行情请使用 /api/v1/kline/ws。

7. 运维调试接口（附录）

这些接口直接访问 Durable Object 内部状态，当前无鉴权保护，建议仅在受控网络或调试环境使用。

注意： 运维调试接口不完全遵循统一 JSON 响应结构，调用方应按各接口说明分别处理 text/plain 或 Durable Object 裸 JSON。

7.1 确保采集器运行

请求

POST /api/v1/admin/debug/ingester/ensure

curl 示例

curl -X POST "https://api.gelabs.org/api/v1/admin/debug/ingester/ensure" \
  -H "X-API-Key: $API_KEY"

成功响应

ok

该接口返回 text/plain，不使用统一 JSON 包装。

7.2 查询采集器状态

请求

GET /api/v1/admin/debug/ingester/status

成功响应

{
  "connected": true,
  "channelConfirmed": true,
  "lastTickAt": "2026-04-16T08:01:00.000Z",
  "poolCount": 1,
  "pools": [
    {
      "poolId": 42,
      "chainRefId": 1,
      "chainType": "evm",
      "chainId": 1,
      "networkId": "eth",
      "poolAddress": "0xabc123def456",
      "token": "base"
    }
  ]
}

字段	类型	必返回	说明
`connected`	boolean	是	是否已连接上游 CoinGecko WebSocket
`channelConfirmed`	boolean	是	上游 Action Cable 频道是否已确认
`lastTickAt`	string / null	是	最近一次收到 tick 的时间
`poolCount`	integer	是	当前订阅池数量
`pools`	array	是	采集器内存中的池订阅列表

7.3 查询 KlineHub 状态

请求

GET /api/v1/admin/debug/hub/status

成功响应

{
  "wsCount": 8,
  "poolCount": 2,
  "pools": [
    {
      "key": "evm:1:0xabc123def456:base",
      "clientCount": 5
    }
  ],
  "lastIngestAt": "2026-04-16T08:01:00.000Z",
  "lastIngestKey": "evm:1:0xabc123def456:base"
}

字段	类型	必返回	说明
`wsCount`	integer	是	当前连接到 KlineHub 的 WebSocket 客户端数量
`poolCount`	integer	是	当前有订阅客户端的池键数量
`pools[].key`	string	是	池订阅键，格式 `chain_type:chain_id:pool_address:token`
`pools[].clientCount`	integer	是	订阅该池键的客户端数量
`lastIngestAt`	string / null	是	最近一次收到 Ingester 推送的时间
`lastIngestKey`	string / null	是	最近一次收到 tick 对应的池键

8. 健康检查（附录）

请求

GET /api/v1/health

curl 示例

curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/api/v1/health"

成功响应

{
  "code": 0,
  "message": "ok",
  "data": {
    "status": "ok",
    "timestamp": "2026-04-16T08:00:00.000Z"
  }
}

9. 错误处理与最佳实践

9.1 常见 HTTP 错误

HTTP	常见业务码	说明
400	`10001` / `10002` / `10005`	请求参数缺失、格式不合法，或 WebSocket 预检请求错误
404	`10003` / `60001`	路由、池或上游资源不存在
409	`10004`	重复创建同一池等资源冲突
500	`99001` / `99002` / `99003`	服务内部异常、数据库异常或缓存异常

调用方应同时关注 HTTP 状态码和响应体 code。业务成功以 code: 0 为准；部分运维接口不使用统一 JSON 包装，需要按接口单独处理。

9.2 WebSocket 接入建议

项目	建议
心跳	客户端定期发送 `{ "id": "hb-001", "type": "ping", "data": {} }` JSON 消息，并检查服务端 `pong`
重连	连接断开后使用指数退避重连，重连成功后重新发送订阅
补数据	重连后先通过 `GET /api/v1/kline/ohlcv` 查询断线期间历史数据，再继续消费实时推送
幂等	对同一池、同一 `interval`、同一 `open_time` 的 K 线更新做覆盖写入
订阅管理	对同一池重复 `subscribe` 会覆盖该池的 `intervals` 设置，客户端应维护本地订阅状态

9.3 时间戳处理

HTTP 查询参数 from、to 支持 Unix 秒或毫秒；服务端会将大于 10000000000 的值按毫秒处理。
OHLCV 字段 open_time 使用 Unix 秒，WebSocket 信封字段 time 使用 Unix 毫秒。
客户端展示跨时区行情时，建议统一以 UTC 存储，再在展示层转换时区。

9.4 价格与成交量精度

open、high、low、close、volume 可能为 null，客户端展示和计算时需要显式处理。
对价格、成交量和市值等数值字段，建议使用高精度 decimal 类型或字符串化存储，避免 JavaScript number 精度问题。
Market 代理接口透传 CoinGecko 业务数据，字段类型可能与 K-Line 自身 OHLCV 字段不完全一致。

文档版本：v1.0.0 | 最后更新：2026-04-28

目录​

1. 快速开始​

1.1 服务简介​

1.2 Base URL​

1.3 统一响应结构​

1.4 错误码​

1.5 公共约定​

1.6 快速接入流程​

2. 池管理接口​

2.1 创建池​

2.2 获取池列表​

2.3 获取池详情​

2.4 激活池​

2.5 停用池​

3. 历史 K 线查询​

3.1 查询 OHLCV 数据​

4. Market 行情代理接口​

4.1 获取池市场详情​

4.2 获取代币 Top Holders​

4.3 通过合约地址查询代币元数据​

5. K-Line WebSocket​

5.1 连接要求​

5.2 协议常量​

5.3 客户端消息结构​

5.4 服务端消息结构​

5.5 订阅与退订示例​

5.6 推送数据字段​

5.7 WebSocket 错误消息​

6. 通用 WebSocket​

7. 运维调试接口（附录）​

7.1 确保采集器运行​

7.2 查询采集器状态​

7.3 查询 KlineHub 状态​

8. 健康检查（附录）​

9. 错误处理与最佳实践​

9.1 常见 HTTP 错误​

9.2 WebSocket 接入建议​

9.3 时间戳处理​

9.4 价格与成交量精度​

目录

1. 快速开始

1.1 服务简介

1.2 Base URL

1.3 统一响应结构

1.4 错误码

1.5 公共约定

1.6 快速接入流程

2. 池管理接口

2.1 创建池

2.2 获取池列表

2.3 获取池详情

2.4 激活池

2.5 停用池

3. 历史 K 线查询

3.1 查询 OHLCV 数据

4. Market 行情代理接口

4.1 获取池市场详情

4.2 获取代币 Top Holders

4.3 通过合约地址查询代币元数据

5. K-Line WebSocket

5.1 连接要求

5.2 协议常量

5.3 客户端消息结构

5.4 服务端消息结构

5.5 订阅与退订示例

5.6 推送数据字段

5.7 WebSocket 错误消息

6. 通用 WebSocket

7. 运维调试接口（附录）

7.1 确保采集器运行

7.2 查询采集器状态

7.3 查询 KlineHub 状态

8. 健康检查（附录）

9. 错误处理与最佳实践

9.1 常见 HTTP 错误

9.2 WebSocket 接入建议

9.3 时间戳处理

9.4 价格与成交量精度