> ## Documentation Index
> Fetch the complete documentation index at: https://developer.wooxpro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 【公共】深度频道

获取交易对的深度数据。

### 推送规则

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

### 请求

> 请求

```json theme={null}
{
  "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档深度频道 (返回前五十档的深度数据) |

### 返回

> 返回

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

返回data字段说明:

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

**解释说明**

`depths`字段描述

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

<aside class="notice">
  depths数组举例说明：`{"price":"20159.6","vol":"7284"}`，price为深度价格，vol为此价格数量
</aside>

***

## 【公共】深度全量频道

获取交易对的深度数据。

### 推送规则

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

### 请求

> 请求

```json theme={null}
{
  "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档深度频道 (返回前五十档的深度数据) |

### 返回

> 返回

```json theme={null}
{
    "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 | 数量 |

<aside class="notice">
  深度数组举例说明：`{"price":"20159.6","vol":"7284"}`，price为深度价格，vol为此价格数量
</aside>

***

## 【公共】深度增量频道

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

### 推送规则

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

### 请求

> 订阅请求

```json theme={null}
{
  "action":"subscribe",
  "args":["futures/depthIncrease20:BTCUSDT@200ms"]
}
```

> 全量请求

```json theme={null}
{ 
  "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档深度频道 (返回前五十档的深度数据) |

### 返回

> 全量深度快照

```json theme={null}
{
    "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"
}
```

> 增量深度数据

```json theme={null}
{
    "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 | 数据类型<br />-`snapshot`=全量深度快照 <br />-`update`=增量深度数据 |

**解释说明**

`asks` `bids`字段描述

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

<aside class="notice">
  深度数组举例说明：`{"price":"20159.6","vol":"7284"}`，price为深度价格，vol为此价格数量
</aside>

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

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

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

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

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

### 推送规则

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

### 请求

> 请求

```json theme={null}
{
  "action":"subscribe",
  "args":["futures/bookticker:BTCUSDT"]
}
```

消息格式:

`{"action":"subscribe","args":["<channel:symbol>"]}`

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

### 返回

> 返回

```json theme={null}
{
    "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   | 数据推送时间戳 (精确到毫秒)   |

***