# 深度
### 描述
获取深度数据，books是全量深度频道，books1是1档频道，books5是5档频道，books50是50档频道；
- `books` 对应全量深度数据,首次推送全量数据 `snapshot`，后续推送增量变化数据: `update`
- `books1` 对应1档位深度数据,每次推送: `snapshot`
- `books5` 对应5档位深度数据,每次推送: `snapshot`
- `books50` 对应50档位深度数据,每次推送: `snapshot`
现货
- `books1` 推送频率:1ms
- `books5` 推送频率:10ms
- `books50` 推送频率:20ms
- `books` 推送频率:50ms
合约
- `books1` 推送频率:1ms
- `books5` 推送频率:10ms
- `books50` 推送频率:20ms
- `books` 推送频率:50ms
上次推送序列号 `pseq` :
- 正常情况下，深度频道推送的序列号是增长的，即在一个推送序列里接收到的`seq`值总是大于`pseq`。
- 在系统发布等服务重启的情况下，序列号可能会被重置。此时用户大概率会收到一个 `pseq=0`的推送消息。重置后，所有后续消息将继续按正常顺序排序。
- update增量消息前一条的seq一定等于后一条的pseq
- update增量消息的seq在除币对维护的情况是递增的
- 接收snapshot全量快照后的第一条update增量数据，snapshot的seq在update增量[pseq, seq] 范围内
```json title="请求示例"
{
"op": "subscribe",
"args": [
{
"instType": "usdt-futures",
"topic": "books1",
"symbol": "BTCUSDT"
}
]
}
```
### 请求参数
| 参数名 | 参数类型 | 是否必须 | 描述 |
|:--------------|:-------------------|:-----|:----------------------------------------------------------------------------------------------------|
| op | String | 是 | 操作
`subscribe` 订阅
`unsubscribe` 退订 |
| args | List<Object> | 是 | 请求订阅的频道列表 |
| > instType | String | 是 | 产品线类型
`spot` 现货交易
`usdt-futures` USDT合约
`coin-futures` 币本位合约
`usdc-futures` USDC合约 |
| > topic | String | 是 | 频道名
`books`全部档位频道
`books1`一档频道
`books5`五档频道
`books50`五十挡频道 |
| > symbol | String | 是 | 交易对名称
例如`BTCUSDT` |
```json title="订阅返回示例"
{
"event": "subscribe",
"arg": {
"instType": "usdt-futures",
"topic": "books1",
"symbol": "BTCUSDT"
},
"connId": "xxxxxxxxxx"
}
```
### 返回参数
| 返回字段 | 参数类型 | 字段说明 |
|:--------------|:-------|:----------------------------------------------------------------------------------------------------|
| event | String | 事件 |
| arg | Object | 订阅的频道 |
| > instType | String | 产品线类型
`spot` 现货交易
`usdt-futures` USDT合约
`coin-futures` 币本位合约
`usdc-futures` USDC合约 |
| > topic | String | 频道名 |
| > symbol | String | 交易对名称 |
| code | String | 错误码 |
| msg | String | 错误消息 |
| connId | String | 连接ID |
```json title="推送返回示例"
{
"data": [
{
"a": [
[
"99756.7",
"23.9774"
]
],
"b": [
[
"99756.6",
"0.0128"
]
],
"pseq":0,
"seq": 1304314508780744705,
"maxDepth": "50",
"ts": "1746698732562"
}
],
"arg": {
"instType": "usdt-futures",
"symbol": "BTCUSDT",
"topic": "books"
},
"action": "snapshot",
"ts": 1746698732563
}
```
### 推送数据参数
| 返回字段 | 参数类型 | 字段说明 |
|:-------------------|:-------------------|:----------------------------------------------------------------------------------------------------|
| arg | Object | 订阅成功的频道 |
| > instType | String | 产品线类型
`spot` 现货交易
`usdt-futures` USDT合约
`coin-futures` 币本位合约
`usdc-futures` USDC合约 |
| > topic | String | 频道名 |
| > symbol | String | 交易对名称 |
| action | String | 推送数据动作
`snapshot`全量
`update` 增量 |
| ts | String | 数据推送时间戳 |
| data | List<Object> | 订阅的数据 |
| > a | List<String> | 卖方深度 |
| > > a[0] | String | 卖一价 |
| > > a[1] | String | 卖一量 |
| > b | List<String> | 买方深度 |
| > > b[0] | String | 买一价 |
| > > b[1] | String | 买一量 |
| > >seq | String | 序列号
订单簿更新时递增，可以用来判断是否乱序 |
| > >pseq | String | 上次推送序列号，可以用来判断是否丢包，只有books频道有值 |
| > maxDepth | String | 最大深度档位
范围为[0,1000]
正整数，不同交易对之间有差异
只有`books`频道有值 |
| > >ts | String | 撮合时间戳 |