实时行情

:::info 本文档范围

专讲 实时行情（盘口、最新成交、BBO、Mark、Summary）。数据 仅驻内存。
不含 K 线 — 见同组 K 线 · WebSocket 主题。
本组入口见行情数据概述。

:::

实时行情接口在链节点上提供，与交易与账户读方法路径对齐的实时行情读接口（REST + WebSocket）。数据 仅驻内存；进程重启后 re-seed + WS 续订。内部实现细节 对接方无需关心；相关变更见 接口变更清单。

第三方行情 SDK 通常 只需改 base URL 即可接入；调用方 只认 symbol。

环境	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`

两个域名功能一致，任选其一。 Schema 权威定义见 schemas — §12 实时行情。

1. 设计原则

原则	说明
对外只用 `symbol`	HTTP 路径与 WS 订阅均使用 Zepto 链上市场符号（如 `BTC`、`ETH`、`xyz:NVDA`、`BTC-USDT`）
统一读路径	所有市场共用同一套 REST / WS；路由与数据源在节点内部完成，调用方无需分支
实时、不入库	盘口 / 成交 / BBO / Mark / Summary 仅内存；与 K 线（SQLite 索引）无关
Mark 以链为准	`mark_price` / `marks` 来自链节点 `getAllMarks`（清算 / uPnL 同源）
路径对齐 Chain	REST 路径与链读路径一致，便于在同一节点上切换使用

1.1 与 Chain API 的分工

场景	推荐
做市 / 下单 / 账户 / 写操作	链读写（`POST /api/v1/query` / `/action`）
深度图 / 最新成交 ticker	读侧实时行情（本页）
K 线 / 图表	K 线
历史成交 / 委托 / 对账	历史索引 REST

详见 做市商对接指南 §1.2。

2. Symbol 解析

所有实时行情接口通过 Zepto 完整 symbol 或前缀解析市场：

规则	说明
精确匹配	`BTC-USDT` → 该 symbol 对应的市场
前缀匹配	`BTC` → 匹配以 `BTC` 开头且最短的 symbol（如同时存在 `BTC` 与 `BTC-USDT` 时，`BTC` 优先匹配更短的 `BTC`）
大小写	不敏感（内部归一化为小写）
HIP-3 市场	使用链上完整符号，如 `xyz:NVDA`、`xyz:JPY`

WS `coin` 与 REST `symbol`

REST `{symbol}`	WS `coin`	说明
`BTC-USDT`	`BTC`	带 `-` 的 symbol 取 `-` 前基础资产作为 `coin`
`BTC`	`BTC`	与 REST symbol 相同
`xyz:NVDA`	`xyz:NVDA`	与 REST symbol 相同

REST 推荐使用 完整 Zepto symbol 以避免前缀歧义；WS 订阅时使用上表 coin 值。

3. 数据新鲜度与 HTTP 元数据

3.1 `GET /api/v1/status` — `hot_feed`

{
  "watermark": 2046216,
  "hot_feed": {
    "native_ready": true,
    "hl_ready": true,
    "stale": false,
    "chain_height": 2046216,
    "book_updated_at_ms": 1717200000123
  },
  "markets": {
    "native": 1,
    "external_peg": 4
  }
}

Field	Type	Description
`hot_feed.native_ready`	`boolean`	实时行情 feed seed 状态
`hot_feed.hl_ready`	`boolean`	实时行情 feed seed 状态
`hot_feed.stale`	`boolean`	上游 WS 断开或长时间未更新时为 `true`
`hot_feed.chain_height`	`number`	热缓存关联的链高度（各 slot 最大值）
`hot_feed.book_updated_at_ms`	`number`	盘口最近更新时间（ms，各 slot 最大值）
`markets`	`object`	服务端路由计数（对接可忽略）

依赖本页 REST 前，确认 hot_feed.native_ready 与 hot_feed.hl_ready 均为 true。完整 status 见 历史索引 — status。

3.2 REST 响应包装

成功时 body 为 扁平 JSON（meta 与 data 同级）：

{
  "chain_height": 2046216,
  "book_updated_at_ms": 1717200000123,
  "stale": false,
  "ready": true,
  "data": { }
}

Field	Type	Description
`chain_height`	`number`	同 status `hot_feed.chain_height`
`book_updated_at_ms`	`number`	盘口最近更新时间（ms）
`stale`	`boolean`	上游 stale 时为 `true`；仍返回 200 与内存中最近数据
`ready`	`boolean`	Feed 已 seed 且 slot 可读
`data`	`object` / `array`	业务载荷（见各端点）

响应 Header（可选读取）

Header	说明
`X-Chain-Height`	同 `chain_height`
`X-Book-Updated-At-Ms`	同 `book_updated_at_ms`
`X-Market-Data-Stale: true`	仅当 `stale == true` 时出现

3.3 HTTP 状态码

HTTP	场景	Body
`200`	正常；或 stale 但有缓存	见上
`404`	未知 / 已下架 symbol	`{ "error": "market not found" }`
`503`	Feed seeding 中，slot 尚未建立	`{ "error": "market feed seeding" }`，Header `Retry-After: 2`
`500`	内部错误	`{ "error": "..." }`

禁止在收到 503 时自行打链补数；应退避重试（建议 ≥2s）。

4. REST — 盘口与成交

`GET /api/v1/market/orderbook/{symbol}`

对齐 Chain GET /api/v1/orderbook/{symbol}。

Path

Param	说明
`{symbol}`	Zepto 市场符号，如 `BTC`、`BTC-USDT`、`xyz:NVDA`

Query

Param	Type	Default	Description
`depth`	`number`	全量 cap	每侧返回档数；在服务端 cap 内再截断

深度上限：每侧最多 50 档（部分市场服务端 cap 可能更低）。

Response 200 — data 为 OrderbookSnapshot

{
  "chain_height": 2046216,
  "book_updated_at_ms": 1717200000123,
  "stale": false,
  "ready": true,
  "data": {
    "symbol": "BTC",
    "height": 2046216,
    "state_hash": "0x…",
    "source": "index",
    "bids": [
      { "price": "65490.0", "qty": "1.50000", "cumulative_qty": "" }
    ],
    "asks": [
      { "price": "65495.0", "qty": "0.80000", "cumulative_qty": "" }
    ]
  }
}

Field	Type	Description
`symbol`	`string`	Zepto 完整 symbol
`height`	`number`	关联链高度（部分热读场景可能为 `0`）
`state_hash`	`string`	链状态 hash（无链关联时可能为空字符串）
`source`	`string`	内部字段；对接方无需使用
`bids` / `asks`	`OrderbookLevel[]`	价格降序 bids / 升序 asks
`price` / `qty`	`string`	decimal 字符串，精度见 Chain `getMarkets`

每次更新为 整包 snapshot 覆盖（非 level 增量 patch）。

`GET /api/v1/market/trades/{symbol}`

对齐 Chain RPC getRecentTrades。

Query

Param	Type	Default	Max	Description
`offset`	`number`	`0`	—	跳过最新 N 条（新→旧分页）
`limit`	`number`	`50`	`1000`	返回条数

排序：新 → 旧（最新成交在前）。

Ring 容量：每市场内存 ring 10_000 条，超出 FIFO 丢弃最旧。

Response 200 — data 为 RecentTrade[]

{
  "chain_height": 2046216,
  "book_updated_at_ms": 1717200000123,
  "stale": false,
  "ready": true,
  "data": [
    {
      "block_height": 2046210,
      "event_seq": 3,
      "timestamp_ms": 1717199000000,
      "market_id": 1,
      "symbol": "BTC",
      "price": "65492.0",
      "qty": "0.01000",
      "notional": "654.920000",
      "side": "Bid",
      "hl_tid": 9876543210
    }
  ]
}

Field	Type	Description
`block_height`	`number`	链上成交区块高度（无链关联时可能为 `0`）
`event_seq`	`number`	链 event 序号
`timestamp_ms`	`number`	成交时间（ms）
`market_id`	`number`	链上 market ID
`symbol`	`string`	Zepto symbol
`side`	`string`	`"Bid"` 或 `"Ask"`
`hl_tid`	`number`	可选；外部 trade id，用于 dedup

5. REST — BBO / Mark / Summary

`GET /api/v1/bbos`

对齐 Chain GET /api/v1/bbos。

Response 200 — data 为 BboItem[]（按 symbol 字典序）

{
  "chain_height": 2046216,
  "book_updated_at_ms": 1717200000123,
  "stale": false,
  "ready": true,
  "data": [
    {
      "symbol": "BTC",
      "bid": "65490.0",
      "ask": "65495.0",
      "spread": "5.0"
    }
  ]
}

BBO 由内存 orderbook 顶档 derive，不单独存副本。

`GET /api/v1/marks`

对齐 Chain GET /api/v1/marks。

Response 200 — data 为 MarksMap（symbol → mark_price 对象）

{
  "chain_height": 2046216,
  "book_updated_at_ms": 1717200000123,
  "stale": false,
  "ready": true,
  "data": {
    "BTC": "65495.0",
    "ETH": "1919.40",
    "xyz:NVDA": "210.750",
    "BTC-USDT": "0"
  }
}

Mark 每区块从链 getAllMarks 刷新，为清算 / uPnL 权威价。

`GET /api/v1/markets/{symbol}/summary`

对齐 Chain GET /api/v1/markets/{symbol}/summary。

Response 200 — data 为 MarketSummary

{
  "chain_height": 2046216,
  "book_updated_at_ms": 1717200000123,
  "stale": false,
  "ready": true,
  "data": {
    "symbol": "BTC",
    "mark_price": "65495.0",
    "best_bid": "65490.0",
    "best_ask": "65495.0",
    "spread": "5.0",
    "open_interest": "1234.50000",
    "open_interest_notional": "80801234.567890",
    "fills_in_block": 12,
    "bid_levels": 20,
    "ask_levels": 18,
    "open_orders": 0,
    "prev_day_price": "66034.0",
    "day_ntl_volume": "0.000000",
    "day_base_volume": "0.00000"
  }
}

Field	Type	Description
`mark_price`	`string`	链 mark（同 `marks`）
`best_bid` / `best_ask` / `spread`	`string \| null`	由热 orderbook 顶档 derive
`open_interest` 等统计项	多种	来自链 `getMarketSummary` / 块钩子缓存
`bid_levels` / `ask_levels`	`number`	当前 orderbook 档数
`open_orders`	`number`	链侧 resting 订单数

未设置的 optional 字段可能从 JSON 中省略。

6. WebSocket — 实时行情主题

连接：ws://{node}/api/v1/ws（与链 WS、blocks.live、K 线主题同一连接）。

协议：{"op":"subscribe","topics":[...]} 订阅制（旧 method/subscription 已删除）。 K 线 用 candles.{symbol}.{interval} 主题 — 见 K 线 · 读侧 WS。

6.1 订阅类型

主题	参数	说明
`book.{symbol}[.{depth}]`	symbol（`depth` 默认 50，`0`=全深度）	全量 orderbook 快照（变化时全量推）
`trades.{symbol}`	symbol	成交推送（每块增量 batch）
`bbo.{symbol}`	symbol	最优买卖价（变化时推）
`marks`	—	全市场 mark map

Subscribe 示例

{
  "op": "subscribe",
  "topics": ["book.BTC.20", "trades.ETH", "bbo.BTC", "marks"]
}

6.2 订阅快照

订阅成功后，若热缓存可读，服务端 立即推送一份当前快照：

主题	快照内容
`book.{symbol}`	当前完整 orderbook
`bbo.{symbol}`	当前顶档 BBO
`marks`	当前全市场 marks
`trades.{symbol}`	无初始快照（历史用 REST `/api/v1/market/trades/{symbol}`）

Feed seeding 中（503 等价状态）时，快照可能 静默跳过，待 ready 后靠增量更新。

6.3 推送格式（节点 decimal-string 帧）

`book.{symbol}`

{
  "topic": "book.BTC",
  "symbol": "BTC",
  "height": 2046216,
  "timestamp_ms": 1717200001000,
  "state_hash": "0x…",
  "bids": [{ "price": "65490.0", "qty": "1.50000", "cumulative_qty": "1.50000" }],
  "asks": [{ "price": "65495.0", "qty": "0.80000", "cumulative_qty": "0.80000" }]
}

`trades.{symbol}`

{
  "topic": "trades.BTC",
  "symbol": "BTC",
  "height": 2046210,
  "timestamp_ms": 1717199000000,
  "trades": [
    {
      "block_height": 2046210,
      "event_seq": 3,
      "timestamp_ms": 1717199000000,
      "market_id": 1,
      "price": "65492.0",
      "qty": "0.01000",
      "notional": "654.920000",
      "side": "Bid"
    }
  ]
}

`bbo.{symbol}`

{
  "topic": "bbo.BTC",
  "symbol": "BTC",
  "height": 2046216,
  "timestamp_ms": 1717200001000,
  "best_bid": "65490.0",
  "best_ask": "65495.0"
}

`marks`

{
  "topic": "marks",
  "height": 2046216,
  "timestamp_ms": 1717200001000,
  "marks": { "BTC": "65495.0", "ETH": "1919.40" }
}

6.4 与链主题共存

同一 WebSocket 连接可同时：

订阅 链主题（book.* / trades.* / bbo.* / marks 与链读同源；account.* / userFills.* / orderUpdates.* 等交易主题见链 WS）
订阅 blocks.live（新区块广播）与 candles.{symbol}.{interval}（K 线）

各主题独立过滤，互不影响。

7. 端点速查

Method	Path	Chain 等价	Response `data`
GET	`/api/v1/market/orderbook/{symbol}`	`GET /orderbook/{symbol}`	`OrderbookSnapshot`
GET	`/api/v1/market/trades/{symbol}`	`getRecentTrades`	`RecentTrade[]`
GET	`/api/v1/bbos`	`GET /bbos`	`BboItem[]`
GET	`/api/v1/marks`	`GET /marks`	`MarksMap`
GET	`/api/v1/markets/{symbol}/summary`	`GET /markets/{symbol}/summary`	`MarketSummary`
GET	`/api/v1/ws`	—	WS 行情主题（见 §6）

K 线（/candles、POST /info、channel: candle）见 K 线。

8. 对接清单

步骤	动作
1	确认 `GET /api/v1/status` 中 `hot_feed.*` 均为 `true`
2	用 Chain `getMarkets` 获取完整 `symbol` 列表
3	REST：处理 `503` + `Retry-After`；stale 时读 `X-Market-Data-Stale`
4	WS：`op/topics` 订阅行情主题，等待 snapshot（`trades` 无初始快照）后再处理增量
5	写操作仍走链读写（`POST /api/v1/action`）

要做 K 线图表？ → K 线

1. 设计原则​

1.1 与 Chain API 的分工​

2. Symbol 解析​

WS coin 与 REST symbol​

3. 数据新鲜度与 HTTP 元数据​

3.1 GET /api/v1/status — hot_feed​

3.2 REST 响应包装​

3.3 HTTP 状态码​

4. REST — 盘口与成交​

GET /api/v1/market/orderbook/{symbol}​

GET /api/v1/market/trades/{symbol}​

5. REST — BBO / Mark / Summary​

GET /api/v1/bbos​

GET /api/v1/marks​

GET /api/v1/markets/{symbol}/summary​

6. WebSocket — 实时行情主题​

6.1 订阅类型​

6.2 订阅快照​

6.3 推送格式（节点 decimal-string 帧）​

book.{symbol}​

trades.{symbol}​

bbo.{symbol}​

marks​

6.4 与链主题共存​

7. 端点速查​

8. 对接清单​