HKbitEX 开发文档

🌙 主题

WebSocket 行情接口文档 ​

最近更新：2025-05-06

1. 基本信息 ​

  • WebSocket Base URL: ws://10.1.9.121:8088

  • 组合 Streams URL 格式: /stream?streams=<streamName1>/<streamName2>/<streamName3>

  • Stream Payload 格式: 当订阅组合 Streams 时：

    json
    {
  "stream": "<streamName>", // 订阅的 Stream 名称
  "data": <rawPayload>      // 原始数据
}

    Stream 名称中的所有交易对均为小写。

  • 连接有效期: 每个连接有效期不超过 24 小时，请妥善处理断线重连。

  • 时间戳单位: 所有时间和时间戳字段均以毫秒为单位。

  • 账户信息限制: Base URL 仅支持订阅市场信息流，账户相关数据无法通过此 URL 获取。

2. WebSocket 连接限制 ​

  • 消息大小限制: 如果用户发送的消息超过限制，连接将被断开。反复断开连接的 IP 有可能被服务器屏蔽。
  • 订阅限制: 单个连接最多可以订阅 1024 个 Streams。

3. 实时订阅/取消数据流 ​

  • 以下数据可以通过websocket发送以实现订阅或取消订阅数据流。示例如下.
  • 请求中的id被用作唯一标识来区分来回传递的消息。以下格式被接受:
    • 64位有符号整数
    • 字母数字字符串；最大长度36
    • null
  • 如果相应内容中的result 为 null，表示请求发送成功。

3.1 订阅一个信息流 ​

3.1.1 请求示例 ​

json
{
  "method": "SUBSCRIBE",
  "params": [
    "btc_usdt@aggTrade",
    "btc_usdt@depth"
  ],
  "id": 1
}

3.1.2 响应示例 ​

json
{
  "result": null,
  "id": 1
}

3.2 取消订阅一个信息流 ​

3.2.1 请求示例 ​

json
{
  "method": "UNSUBSCRIBE",
  "params": [
    "btc_usdt@depth"
  ],
  "id": 312
}

3.2.2 响应示例 ​

json
{
  "result": null,
  "id": 312
}

3.3 已订阅信息流 ​

3.3.1 请求示例 ​

json
{
  "method": "LIST_SUBSCRIPTIONS",
  "id": 3
}

3.3.2 响应示例 ​

json
{
  "result": [
    "btc_usdt@aggTrade"
  ],
  "id": 3
}

3.4 设定属性 ​

  • 支持的属性:
    • combined: 是否启用组合信息流模式（默认启用）。

3.4.1 设置 combined 属性请求示例 ​

3.4.1.1 请求示例 ​
json
{
  "method": "SET_PROPERTY",
  "params": [
    "combined",
    true
  ],
  "id": 5
}
3.4.1.2 响应示例 ​
json
{
  "result": null,
  "id": 5
}
3.4.1.3 Payload 示例 ​
  • combined=true
json
{
  "stream": "btc_usdt@aggTrade",
  "data": <rawPayload>
}
  • combined=false
json
{
  "<rawPayload>"
}

3.5 检索属性 ​

3.5.1 请求示例 ​

json
{
  "method": "GET_PROPERTY",
  "params": [
    "combined"
  ],
  "id": 7
}

3.5.2 响应示例 ​

json
{
  "result": true,
  "id": 7
}

4. Stream 详细定义 ​

4.1 归集交易 ​

归集交易与逐笔交易的区别在于，同一价格的成交会被归集为一笔成交。

Stream 名称: <symbol>@aggTrade

更新速度: 250ms

Payload:

json
{
  "e": 12,                // 事件类型
  "s": "btc_usd",         // 交易对
  "t": {
    "p": "0.001",         // 成交价格
    "q": "100",           // 成交数量
    "t": 1672515782136,   // 成交时间
    "s": "btc_usd",       // 交易对
    "m": true             // 买方是否是做市方。如 true，则此次成交是一个主动卖出单，否则是一个主动买入单。
  }
}

4.2 逐笔交易 ​

逐笔交易推送每一笔成交的信息。

Stream 名称: <symbol>@trade

更新速度: 250ms

Payload:

json
{
  "e": 6,                // 事件类型
  "s": "btc_usd",         // 交易对
  "t": {
    "p": "0.001",         // 成交价格
    "q": "100",           // 成交数量
    "t": 1672515782136,   // 成交时间
    "s": "btc_usd",       // 交易对
    "m": true             // 买方是否是做市方。如 true，则此次成交是一个主动卖出单，否则是一个主动买入单。
  }
}

4.3 K线 ​

K线stream逐秒推送所请求的K线种类（最新一根K线）的更新。此更新是基于 UTC+0 时区的。

订阅Kline需要提供间隔参数，最短为分钟线，最长为月线。支持以下间隔:

m -> 分钟; h -> 小时; d -> 天; w -> 周; M -> 月

  • 1m
  • 3m
  • 5m
  • 15m
  • 30m
  • 1h
  • 2h
  • 4h
  • 6h
  • 8h
  • 12h
  • 1d
  • 3d
  • 1w
  • 1M

Stream 名称: <symbol>@kline_<interval>

更新速度: 500ms

Payload:

json
{
    "e": 5,                // 事件类型
    "k": {
        "oT": 1736408400000,  // 这根K线的起始时间
        "cT": 1736408459999,  // 这根K线的结束时间
        "s": "btc_usd",       // 交易对
        "i": "1m",            // K线间隔
        "o": "90899",         // 这根K线期间第一笔成交价
        "c": "90899",         // 这根K线期间末一笔成交价
        "h": "90899",         // 这根K线期间最高成交价
        "l": "90899",         // 这根K线期间最低成交价
        "v": "0",             // 这根K线期间成交量
        "q": "0",             // 这根K线期间成交数量
        "n": 0,               // 这根K线期间成交笔数
        "t": 1736408439841    // 这根K线的起始时间
    },
    "s": "btc_usd"           // 交易对
}

4.4 按Symbol的精简Ticker ​

按Symbol逐秒刷新的24小时精简ticker信息。

Stream 名称: <symbol>@miniTicker

更新速度: 1000ms

Payload:

json
{
    "e": 9,                  // 事件类型
    "m": {
        "t": 1672515782136,  // 事件时间
        "s": "btc_usd",      // 交易对
        "c": "0.0025",       // 最新成交价格
        "o": "0.0010",       // 24小时前开始第一笔成交价格
        "h": "0.0025",       // 24小时内最高成交价
        "l": "0.0010",       // 24小时内最低成交价
        "v": "10000",        // 成交量
        "q": "18"            // 成交额
    },
    "s": "btc_usd"           // 交易对
}

4.5 全市场所有Symbol的精简Ticker ​

与单个Symbol的精简Ticker类似，只是推送所有交易对的信息。

Stream 名称: !miniTicker@arr

更新速度: 1000ms

Payload:

json
{
    "e": 10,          // 事件类型
    "data": [
        {
            // 数组中的每一个元素对应一个交易对，内容与 <symbol>@miniTicker 的结构相同
            "t": 1672515782136, // 事件时间
            "s": "btc_usd",     // 交易对
            "c": "0.0025",      // 最新成交价格
            "o": "0.0010",      // 24小时前开始第一笔成交价格
            "h": "0.0025",      // 24小时内最高成交价
            "l": "0.0010",      // 24小时内最低成交价
            "v": "10000",       // 成交量
            "q": "18"           // 成交额
        },
        {
            // 其他交易对的精简Ticker信息
        }
    ]
}

4.6 全量深度信息 ​

提供全市场深度信息，按 1 分钟间隔推送。

Stream 名称: <symbol>@depthAll

更新速度: 1000ms

Payload:

json
{
    "e": 8,                // 事件类型
    "s": "btc_usd",        // 交易对
    "l": 245853,    // 最后更新ID
    "d": {
        "s": "btc_usd",    // 交易对
        "bids": [          // 买单
            [
                "0.0024",  // 价格
                "10"      // 数量
            ],
            []
        ],
        "asks": [          // 卖单
            [
                "0.0026",  // 价格
                "100"     // 数量
            ],
            []
        ]
    }
}

4.7 增量深度信息 ​

每秒推送 OrderBook 的变化部分（如果有）。

Stream 名称: <symbol>@depth

更新速度: 100ms

Payload:

json
{
    "e": 7,                // 事件类型
    "s": "btc_usd",        // 交易对
    "f": 245853,    // 从上次推送至今新增的第一个 update Id
    "l": 245858,    // 从上次推送至今新增的最后一个 update Id
    "d": {
        "s": "btc_usd",    // 交易对
        "bids": [          // 买单
            [
                "0.0024",  // 价格
                "10"      // 数量
            ],
            []
        ],
        "asks": [          // 卖单
            [
                "0.0026",  // 价格
                "100"     // 数量
            ]
            []
        ]
    }
}

4.8 增量深度信息(实时推送) ​

每秒推送 OrderBook 的变化部分（如果有）。

Stream 名称: <symbol>@depth@0ms

更新速度: 0ms

Payload:

json
{
    "e": 13,                // 事件类型
    "s": "btc_usd",        // 交易对
    "f": 245853,    // 从上次推送至今新增的第一个 update Id
    "l": 245858,    // 从上次推送至今新增的最后一个 update Id
    "d": {
        "s": "btc_usd",    // 交易对
        "bids": [          // 买单
            [
                "0.0024",  // 价格
                "10"      // 数量
            ],
            []
        ],
        "asks": [          // 卖单
            [
                "0.0026",  // 价格
                "100"     // 数量
            ]
            []
        ]
    }
}

5. 错误信息 ​

错误信息描述
{"code":1001,"msg":"Invalid JSON: %s"}JSON 语法有误
{"code": 1002, "msg": "Invalid request: ID must be an unsigned integer"}参数id未提供或id值是无效类型
{"code": 1002, "msg": "Invalid request: params can not be empty"}params不能为空
{"code": 1002, "msg": "Invalid request: params unsupported channel"}不支持的订阅频道
{"code": 1002, "msg": "Invalid request: params too many"}params参数太多
{"code": 1002, "msg": "Invalid request: params too few"}params参数太少
{"code": 1002, "msg": "Invalid request: params unsupported property"}不支持的属性名
{"code": 1003, "msg": "params value must be a string"}参数类型错误
{"code": 1003, "msg": "params value must be boolean"}参数类型错误
{"code":1004,"msg":"A server internal error occurred. Please try again later or contact support if the issue persists."}服务器内部错误

6. 事件类型枚举定义 ​

  • 5 - K线
  • 6 - 逐笔成交
  • 7 - 深度信息(增量数据)
  • 8 - 深度信息(全量数据)
  • 9 - 24hr价格变动情况
  • 10 - 24hr价格变动情况(全部交易对)
  • 11 - 市场价格事件(全部交易对)
  • 12 - 聚合成交

7. 如何正确在本地维护一个order book副本 ​

  1. 打开与 ws://10.1.9.121:8088 的 WebSocket 连接。
  2. 开始缓存收到的event。请记录您收到的第一个event的 f值。
  3. 访问 http://10.1.9.121:8080/market/depth 获取深度快照。
  4. 如果快照中的 lastUpdateId 小于等于步骤 2 中的 f 值，请返回步骤 3。
  5. 在收到的event中，丢弃快照中 l <= lastUpdateId 的所有event。现在第一个event的 lastUpdateId 应该在 [f;l] 范围以内。
  6. 将本地order book设置为快照。它的更新ID 为 lastUpdateId。
  7. 更新所有缓存的event，以及后续的所有event。

要将event应用于您的本地order book，请遵循以下更新过程：

  1. 如果event l (最后一次更新 ID) < 您本地order book的更新 ID，请忽略该事件。
  2. 如果event f (第一次更新 ID) 不等于 您本地order book的更新 ID+1，则说明出现问题。请丢弃您的本地order book并从头开始开始重建。
  3. 对于买价 (b) 和卖价 (a) 中的每个价位，在order book中设置新的数量：
    • 如果order book中不存在价位，则插入新的数量。
    • 如果数量为零，则从order book中删除此价位。
  4. 将order book更新 ID 设置为处理过event中的最后一次更新 ID (l)。

🚀 构建现代化数字资产交易平台

Copyright © 2025 HKbitEX Development Team