【公共】深度频道

获取交易对的深度数据。

推送规则

无需用户登录
订阅后会直接返回当前的数据，之后有变化才推送

请求

请求

{
  "action":"subscribe",
  "args":["futures/depth20:BTCUSDT@200ms"]
}

消息格式: {"action":"subscribe","args":["<channel:symbol><@speed>"]}

channel: 频道名, 如futures/depth20
symbol: 交易对, 如BTCUSDT
speed: 更新速度, 支持100ms或200ms

请求其他频道列表

频道名	频道描述
futures/depth5	5档深度频道 (返回前五档的深度数据)
futures/depth20	20档深度频道 (返回前二十档的深度数据)
futures/depth50	50档深度频道 (返回前五十档的深度数据)

返回

{
    "group":"futures/depth20:BTCUSDT@200ms",
    "data":{
            "symbol":"BTCUSDT",
            "way":1,
            "depths":[
              {"price":"5","vol":"97"}
            ],
            "ms_t": 1542337219120
        }
}

返回data字段说明:

字段	类型	描述
symbol	String	合约交易对（如`BTCUSDT`）
way	Long	深度方向 -`1`=买方 -`2`=卖方
depths	List	深度数组
ms_t	Long	数据推送时间戳 (精确到毫秒)

解释说明 depths字段描述

字段	类型	描述
price	String	价格
vol	String	数量

【公共】深度全量频道

获取交易对的深度数据。

推送规则

无需用户登录
订阅后会直接返回当前的数据，之后有变化才推送

请求

请求

{
  "action":"subscribe",
  "args":["futures/depthAll20:BTCUSDT@200ms"]
}

消息格式: {"action":"subscribe","args":["<channel:symbol><@speed>"]}

channel: 频道名, 如futures/depth20
symbol: 交易对, 如BTCUSDT
speed: 更新速度, 支持100ms或200ms

请求其他频道列表

频道名	频道描述
futures/depthAll5	5档深度频道 (返回前五档的深度数据)
futures/depthAll20	20档深度频道 (返回前二十档的深度数据)
futures/depthAll50	50档深度频道 (返回前五十档的深度数据)

返回

{
    "data": {
        "symbol": "BTCUSDT",
        "asks": [
            {
                "price": "70294.4",
                "vol": "455"
            }
        ],
        "bids": [
            {
                "price": "70293.9",
                "vol": "1856"
            }
        ],
        "ms_t": 1730399750402
    },
    "group": "futures/depthAll20:BTCUSDT@200ms"
}

返回data字段说明:

字段	类型	描述
symbol	String	合约交易对（如`BTCUSDT`）
asks	List	卖方深度数组
bids	List	买方深度数组
ms_t	Long	数据推送时间戳 (精确到毫秒)

解释说明 asks bids字段描述

字段	类型	描述
price	String	价格
vol	String	数量

【公共】深度增量频道

返回深度数据, 支持维护一个本地的全量深度数据

推送规则

无需用户登录
订阅后会直接返回当前的数据，之后有变化才推送

请求

订阅请求

{
  "action":"subscribe",
  "args":["futures/depthIncrease20:BTCUSDT@200ms"]
}

全量请求

{ 
  "action": "request", 
  "args":["futures/depthIncrease20:BTCUSDT@200ms"]
}

消息格式: {"action":"subscribe","args":["<channel:symbol><@speed>"]}

op: subscribe=订阅,会收到一个订阅成功的消息及全量深度快照，而后会收到实时推送的增量深度数据, request=单次请求最新深度快照,会马上收到一个全量深度的数据
channel:频道名, 如futures/depthIncrease20
symbol: 交易对, 如BTCUSDT
speed: 更新速度, 支持100ms或200ms

请求其他频道列表

频道名	频道描述
futures/depthIncrease5	5档深度频道 (返回前五档的深度数据)
futures/depthIncrease20	20档深度频道 (返回前二十档的深度数据)
futures/depthIncrease50	50档深度频道 (返回前五十档的深度数据)

全量深度快照

{
    "data": {
        "symbol": "BTCUSDT",
        "asks": [
            {
                "price": "70391.6",
                "vol": "3550"
            }
        ],
        "bids": [
            {
                "price": "70391.2",
                "vol": "1335"
            }
        ],
        "ms_t": 1730400086184,
        "version": 980361,
        "type": "snapshot"
    },
    "group": "futures/depthIncrease20:BTCUSDT@200ms"
}

增量深度数据

{
    "data": {
        "symbol": "BTCUSDT",
        "asks": [
            {
                "price": "70395.3",
                "vol": "341"
            },
            {
                "price": "70395.4",
                "vol": "323"
            }
        ],
        "bids": [
            {
                "price": "70391.2",
                "vol": "0"
            },
            {
                "price": "70353.4",
                "vol": "11435"
            }
        ],
        "ms_t": 1730400086194,
        "version": 980362,
        "type": "update"
    },
    "group": "futures/depthIncrease20:BTCUSDT@200ms"
}

返回data字段说明:

字段	类型	描述
symbol	String	合约交易对（如`BTCUSDT`）
asks	List	卖方深度数组
bids	List	买方深度数组
ms_t	Long	数据推送时间戳 (精确到毫秒)
version	Long	数据版本号
type	String	数据类型 -`snapshot`=全量深度快照 -`update`=增量深度数据

解释说明 asks bids字段描述

字段	类型	描述
price	String	价格
vol	String	数量

如何正确在本地维护一个OrderBook副本:

首先Client端通过订阅请求 {"action": "subscribe", "args": ["futures/depthIncrease20:<symbol>"] }
订阅成功后会收到两种类型的消息，type=snapshot(全量)和type=update(更新)
如果收到type=snapshot类型消息，将深度快照内容全覆盖更新至本地缓存，如果没有本地缓存则创建一个。
如果收到type=update类型消息，将深度快照中的数据更新至本地缓存，更新规则如下：
- 4.1 如果收到的消息里字段version小于等于本地缓存中的version(new version<=local version)，则可以丢弃此数据。
- 4.2 如果收到的消息里字段version等于本地缓存中的version加1(new version==local version+1)，则将对应价格的数量更新到本地缓存中。
- 4.3 如果收到的消息里字段version大于本地缓存中的version加1(new version>local version+1)，请从步骤7获取最新的深度快照，覆盖本地缓存。
每一个返回的消息中的挂单量代表这个价格目前的挂单量绝对值，而不是相对变化。
如何更新本地缓存？在4.2的前提下：
- 6.1 新增操作：如果本地没有对应的价格，说明是新挂单，需要新增到缓存中。
- 6.2 修改或者移除操作：如果本地有对应的价格，说明是挂单量变化，如果挂单量是0，则直接从缓存中移除，否则只修改挂单量即可。
通过request请求{"action": "request", "args": ["futures/depthIncrease20:<symbol>"] } 获得一个最新深度快照(消息里type=snapshot)，并将深度快照中的内容覆盖至本地缓存，然后继续从步骤2执行逻辑。

异常情况：
1. 因为深度快照对价格档位数量有限制，初始快照之外的价格档位并且没有数量变化的价格档位不会出现在增量深度的更新信息内。因此，即使应用来自增量深度的所有更新，这些价格档位也不会在本地 order book 中可见，所以本地的 order book 与真实的 order book 可能会有一些差异。

【公共】按Symbol的最优挂单频道

实时推送指定交易对最优挂单信息

推送规则

无需用户登录
订阅后会直接返回当前的数据，之后有变化才推送
实时推送

请求

请求

{
  "action":"subscribe",
  "args":["futures/bookticker:BTCUSDT"]
}

消息格式: {"action":"subscribe","args":["<channel:symbol>"]}

channel: 频道名, 如futures/bookticker
symbol: 交易对, 如BTCUSDT

返回

{
    "data": {
        "symbol": "BTCUSDT",
        "best_bid_price": "97315",
        "best_bid_vol": "156",
        "best_ask_price": "97315.4",
        "best_ask_vol": "333",
        "ms_t": 1733891542244
    },
    "group": "futures/bookticker:BTCUSDT"
}

返回data字段说明:

字段	类型	描述
symbol	String	合约交易对（如`BTCUSDT`）
best_bid_price	String	买一价格
best_bid_vol	String	买一量
best_ask_price	String	卖一价格
best_ask_vol	String	卖一量
ms_t	Long	数据推送时间戳 (精确到毫秒)

​推送规则

​请求

​返回

​【公共】深度全量频道

​推送规则

​请求

​返回

​【公共】深度增量频道

​推送规则

​请求

​返回

​如何正确在本地维护一个OrderBook副本:

​【公共】按Symbol的最优挂单频道

​推送规则

​请求

​返回

推送规则

请求

返回

【公共】深度全量频道

推送规则

请求

返回

【公共】深度增量频道

推送规则

请求

返回

如何正确在本地维护一个OrderBook副本:

【公共】按Symbol的最优挂单频道

推送规则

请求

返回