K 线

:::info 本文档范围

专讲 K 线 OHLCV（GET /candles、POST /info、WS candles.{symbol}.{interval} 主题）。数据来自 SQLite 索引 + 内存 当前根。
不含实时盘口/成交 — 见同组 实时行情。
本组入口见行情数据概述。

:::

环境	Base URL	WebSocket
生产	`https://rpc.auroran.io` · `https://api.auroran.io`	`wss://rpc.auroran.io/api/v1/ws` · `wss://api.auroran.io/api/v1/ws`

两个域名功能一致，任选其一。 :::info 与实时行情的区别

	K 线（本页）	实时行情
数据	按 interval 聚合的 OHLCV 柱	当前盘口 / 成交 / BBO / Mark
存储	SQLite 索引 + 内存当前根	仅内存
典型用途	图表、`getBars`、历史回测	深度图、最新成交列表
WS	主题 `candles.{symbol}.{interval}`	主题 `book.` / `trades.` / `bbo.*` / `marks`
就绪	`candle_watermark` / `candle_lag_blocks`	`hot_feed.*`（REST 可能 503）
Schema	schemas §10	schemas §12

:::

Symbol 解析

与实时行情 §2 相同：REST 用完整 symbol 或前缀；WS coin 规则一致。

对接清单

步骤	动作
1	读 `GET /api/v1/status` 的 `candle_watermark` / `candle_lag_blocks`
2	历史：`GET /api/v1/candles` 或 `POST /info` `candleSnapshot`
3	实时：WS 订阅 `candles.{symbol}.{interval}` 主题
4	首屏偏空时短间隔重试（异步回填缺口）
5	盘口/成交另接实时行情，不要从 K 线推导

TradingView / 第三方图表：历史 → getBars → 本页 REST；实时 → WS candles.{symbol}.{interval} 主题。to ≥ now 时 HTTP 合并内存 进行中 bucket；无成交 bucket 不补零。

全部市场共用同一套 API；Symbol 示例：BTC、ETH、xyz:NVDA、BTC-USDT。

`GET /api/v1/candles`

由 derive → candle 异步 worker 聚合 OHLCV（不阻塞 ingest）。

Query

Param	Type	Required	Default	Max	Description
`symbol`	`string`	yes	—	—	市场符号
`interval`	`string`	no	`1h`	—	K 线周期
`from`	`number`	no	`0`	—	起始时间（ms，含）
`to`	`number`	no	无上限	—	结束时间（ms，含）
`limit`	`number`	no	`500`	`2000`	最大返回根数

Supported interval

Value	Duration
`1m`	1 minute
`3m`	3 minutes
`5m`	5 minutes
`15m`	15 minutes
`30m`	30 minutes
`1h`	1 hour
`2h`	2 hours
`4h`	4 hours
`8h`	8 hours
`12h`	12 hours
`1d`	1 day
`3d`	3 days
`1w`	1 week
`1M`	1 calendar month (UTC)

未知 interval 默认 1h。

Response 200 — 裸数组 Candle[]，按 t 升序：

[
  {
    "t": 1717000000000,
    "T": 1717003600000,
    "s": "BTC-USDT",
    "i": "1h",
    "o": "50000.00",
    "c": "50100.00",
    "h": "50200.00",
    "l": "49900.00",
    "v": "123.456",
    "n": 42
  }
]

Field	Type	Description
`t`	`number`	bucket 开盘时间（ms）
`T`	`number`	bucket 收盘时间（ms）
`s`	`string`	市场符号
`i`	`string`	interval
`o`, `c`, `h`, `l`	`string`	开 / 收 / 高 / 低
`v`	`string`	成交量
`n`	`number`	成交笔数

Response 404 — symbol 不在 market cache。

字段契约见 schemas §10。

`POST /info`

按 body 中 type 分发。

POST /info
Content-Type: application/json

Supported types

`type`	Description
`candleSnapshot`	历史 K 线查询

未知 type → 400：{ "error": "unknown request type: …" }

`candleSnapshot`

Request body

{
  "type": "candleSnapshot",
  "req": {
    "coin": "BTC",
    "interval": "1h",
    "startTime": 1717000000000,
    "endTime": 1717086400000
  }
}

Field	Type	Default	Description
`req.coin`	`string`	—	symbol 或前缀（同 GET）
`req.interval`	`string`	`"1h"`	同 GET
`req.startTime`	`number`	`0`	起始（ms，含）
`req.endTime`	`number`	max	结束（ms，含）

Response 200 — 与 GET 相同 Candle[]。无匹配市场 → []（非错误）。单次最多 5000 根。

WebSocket — K 线主题

详见 统一 WebSocket：订阅 {"op":"subscribe","topics":["candles.BTC-USDT.1h"]}，推送帧 {"topic":"candles.BTC-USDT.1h","data":{t,T,s,i,o,c,h,l,v,n}}。

端点速查

Method	Path	说明
GET	`/api/v1/candles`	K 线 OHLCV
POST	`/info`	`candleSnapshot`
GET	`/api/v1/ws`	`candles.{symbol}.{interval}` 主题订阅

getCandles

JSON-RPC 入口：POST /api/v1/query method getCandles，参数与响应契约与上方 REST 一致。

K 线历史（journal 聚合）。无 start_time_ms/end_time_ms 时走块级缓存（按 (market_id, interval_ms) 缓存，新块失效），适合图表轮询。

参数	类型	必填	说明
`symbol`	String	是	交易对名
`market_id`	u32	否	精确寻址；携带时优先于 `symbol`
`interval_ms`	u64	是	K 线周期（毫秒），必须 > 0
`start_time_ms`	u64	否	起始时间（毫秒）
`end_time_ms`	u64	否	结束时间（毫秒）
`limit`	usize	否	默认 500，最大 2000

响应 data · CandleResponse[]：

字段	类型	说明
`open_time_ms`	u64	蜡烛起始（对齐 interval 边界）
`close_time_ms`	u64	蜡烛结束 = open_time_ms + interval_ms
`open`	String	开盘价（px 精度）
`high`	String	最高价（px 精度）
`low`	String	最低价（px 精度）
`close`	String	收盘价（px 精度）
`volume`	String	成交量（sz 精度）
`trades`	u64	成交笔数

常用 interval_ms：1m=60000, 5m=300000, 15m=900000, 1h=3600000, 4h=14400000, 1d=86400000

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": [{
      "open_time_ms": 1717200000000,
      "close_time_ms": 1717200060000,
      "open": "97100.00",
      "high": "97300.00",
      "low": "97050.00",
      "close": "97234.50",
      "volume": "12.50000",
      "trades": 48
    }],
    "page": { "offset": 0, "limit": 500, "total": null }
  }
}

Symbol 解析​

对接清单​

GET /api/v1/candles​

POST /info​

candleSnapshot​

WebSocket — K 线主题​

端点速查​

getCandles​