跳到主要内容

WebSocket API

← 概述

Endpoint： GET /api/v1/ws（升级为 WebSocket）

环境WebSocket URL
生产wss://api.auroran.io/api/v1/ws
本地开发ws://127.0.0.1:8090/api/v1/ws

服务器推送 JSON 文本帧，并响应协议层 Ping → Pong。

两种客户端模式​

模式触发条件推送内容
Explorer 广播（默认）连接后不发订阅消息每 ingest 一个区块推送完整 block_ingested
K 线订阅（Hyperliquid 兼容）发送 subscribe / unsubscribe仅推送匹配的 channel: candle 更新

一旦存在任意 K 线订阅，客户端不再收到 block_ingested 广播；取消全部订阅后恢复广播模式。

Mode 1: Explorer 广播​

连接后不要发送订阅消息。每 ingest 一个新块，服务器推送：

{
  "event": "block_ingested",
  "block": {
    "parent": "0x…",
    "height": 12346,
    "timestamp_ms": 1717000001000,
    "digest": "0x…",
    "envelope_count": 5,
    "event_count": 42,
    "state_root": "0x…",
    "envelopes": []
  },
  "envelopes": [
    {
      "height": 12346,
      "envelope_idx": 0,
      "tx_hash": "0x…",
      "signer": "0x…",
      "nonce": 6,
      "status": "accepted",
      "action_kind": "PlaceOrder",
      "market_id": 1,
      "symbol": "BTC-USDT",
      "action": { "PlaceOrder": {} },
      "reason": null
    }
  ],
  "watermark": 12346,
  "block_count": 12347,
  "node_tip": 12350,
  "behind": 4,
  "candles": [
    {
      "market_id": 1,
      "interval_ms": 60000,
      "open_time_ms": 1717000020000,
      "close_time_ms": 1717000080000,
      "open": "50000.00",
      "high": "50100.00",
      "low": "49950.00",
      "close": "50080.00",
      "volume": "45.5",
      "trades": 12,
      "symbol": "BTC-USDT"
    }
  ]
}
FieldDescription
block新 ingest 区块头（block.envelopes 恒为空）
envelopes该区块完整 envelope 列表
watermark / block_count / node_tip / behind同 GET /api/v1/status
candles本块 fill 更新的 K 线 bucket（可为空）

前端合并 K 线： 相同 open_time_ms → 原地更新；新 open_time_ms → 追加。

EnvelopeView 字段说明见 rest.md。

Mode 2: K 线订阅​

发送 JSON 文本帧，协议兼容 Hyperliquid。

Subscribe​

{
  "method": "subscribe",
  "subscription": {
    "type": "candle",
    "coin": "BTC",
    "interval": "1h"
  }
}
  • coin：精确匹配 symbol，或前缀匹配（BTC 匹配 BTC-USDT）
  • interval：与 REST K 线相同（1m、5m、1h 等，见 rest.md）

推送格式​

{
  "channel": "candle",
  "data": {
    "t": 1717000020000,
    "T": 1717003620000,
    "s": "BTC-USDT",
    "i": "1h",
    "o": "50000.00",
    "c": "50080.00",
    "h": "50100.00",
    "l": "49950.00",
    "v": "45.5",
    "n": 12
  }
}

字段含义同 REST K 线短键格式（t、T、s、i、o、c、h、l、v、n）。

Unsubscribe​

{
  "method": "unsubscribe",
  "subscription": {
    "type": "candle",
    "coin": "BTC",
    "interval": "1h"
  }
}

取消全部订阅后，恢复 Explorer 广播模式。

Ping / Pong（应用层）​

客户端：

{ "method": "ping" }

服务器：

{ "method": "pong" }

连接示例​

// 生产
const ws = new WebSocket("wss://api.auroran.io/api/v1/ws")
// 本地：ws://127.0.0.1:8090/api/v1/ws

// Explorer 广播模式：直接监听
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data)
  if (msg.event === "block_ingested") {
    console.log("new block", msg.block.height)
  }
  if (msg.channel === "candle") {
    console.log("candle update", msg.data)
  }
}

// K 线订阅模式
ws.onopen = () => {
  ws.send(JSON.stringify({
    method: "subscribe",
    subscription: { type: "candle", coin: "BTC", interval: "1h" }
  }))
}