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

# WebSocket：行情

> 合约 API：WebSocket 行情频道。

## 基本信息

### 基地址

**wss\://fstream.monochrome.exchange/ws/market**

### Request Headers

请求头必须添加压缩扩展协议。

Sec-Websocket-Extensions:permessage-deflate

## 请求报文格式

```javascript 订阅 theme={null}
{
    "method": "subscribe", 
    "params": [
        "{topic}@{arg},{arg}", 
        "{topic}@{arg}"
    ], 
    "id": "{id}"    //回调ID
}
```

```javascript 取消订阅 theme={null}
{
    "method": "unsubscribe", 
    "params": [
        "{topic}@{arg},{arg}"
    ], 
    "id": "{id}"   //回调ID
}
```

## 响应报文格式

```javascript 响应报文格式 theme={null}
{
    "id": "{id}",   //请求回调ID
    "code": 1,      //结果0=成功;1=失败;2=listenKey⽆效
    "msg": ""
}
```

```json Response-成功 theme={null}
{"id":"123", "code": 0, "msg": "success"}   
```

```json response-token失效 theme={null}
{"id":"123", "code": 401, "msg": "token expire"}
```

## 推送报文格式

```javascript 格式 theme={null}
{
    "topic": "trade",             //事件
    "event": "trade@btc_usdt",    //主题
    "data": { }                   //数据
}
```

```json 成交记录(实时推送报文)样例 theme={null}
{
    "topic": "trade", 
    "event": "trade@btc_usdt", 
    "data": {
        "s": "btc_usdt", 
        "i": 6316559590087222000, 
        "t": 1655992403617, 
        "p": "43000", 
        "q": "0.21", 
        "b": true
    }
}
```

## 心跳

客户端每个链接需要定期发送”ping”字符串，服务端会回复”pong”，服务端在30秒内没有收到客户端的ping消息，会主动断开链接

## 订阅参数

**结构**

\{topic}@\{arg},\{arg},…

## Orderbook 维护

**如何正确在本地维护一个orderbook副本**

1.订阅 wss\://fstream.monochrome.exchange/ws/market，depth\_update\@btc\_usdt

2.开始缓存收到的更新。同一个价位，后收到的更新覆盖前面的。

3.访问Rest接口 [https://fapi(或dapi).monochrome.exchange/future/market/v1/public/q/depth?symbol=btc\_usdt\&level=500](https://fapi\(或dapi\).monochrome.exchange/future/market/v1/public/q/depth?symbol=btc_usdt\&level=500) 获得一个500档的深度快照

4.将目前缓存到的信息中u \<= 步骤3中获取到的快照中的lastUpdateId的部分丢弃(丢弃更早的信息，已经过期)。

5.将深度快照中的内容更新到本地orderbook副本中，并从websocket接收到的第一个fu \<= lastUpdateId+1 且 u >= lastUpdateId+1 的event开始继续更新本地副本。

6.每一个新event的fu应该恰好等于上一个event的u+1，否则可能出现了丢包，请从step3重新进行初始化。

7.每一个event中的挂单量代表这个价格目前的挂单量绝对值，而不是相对变化。

8.如果某个价格对应的挂单量为0，表示该价位的挂单已经撤单或者被吃，应该移除这个价位。

注意: 因为深度快照对价格档位数量有限制，初始快照之外的价格档位并且没有数量变化的价格档位不会出现在增量深度的更新信息内。因此，即使应用来自增量深度的所有更新，这些价格档位也不会在本地 order book 中可见，
所以本地的 order book 与真实的 order book 可能会有一些差异。 不过对于大多数用例，500 的深度限制足以有效地了解市场和交易。

## 成交记录

**请求**

语法: trade@\{symbol}

示例: trade\@btc\_usdt

速率: 实时

```json Response theme={null}
{
    "topic": "trade", 
    "event": "trade@btc_usdt", 
    "data": {
        "s":"btc_index", //交易对
        "p":"50000",    //价格
        "a":"0.1"   //数量
        "m": "BID"   //成交方向  BID 买 ASK卖
        "t":123124124   //时间戳
    }
}
```

## K线

**请求**

语法: kline@\{symbol},\{interval}

interval: 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1M

示例: kline\@btc\_usdt,5m

速率: 1000ms

```json Response theme={null}
{
        "topic": "kline",
        "event": "kline@btc_usdt,5m",
            "data": {
                "s":"btc_index", //交易对
                "o":"49000", // open 开盘价
                "c":"50000",    //cloes 收盘价
                "h":"0.1", //high 最高价
                "l":"0.1", //low 最低价
                "a":"0.1", //amount 成交量
                "v":"0.1", //volume 成交额
                "ch":"0.21",   //change 涨跌幅
                "t":123124124   //时间戳
            }
}
```

## ticker

**请求**

语法: ticker@\{symbol}

示例: ticker\@btc\_usdt

速率: 1000ms

```json Response theme={null}
{
    "topic": "ticker", 
    "event": "ticker@btc_usdt", 
    "data": {
        "s":"btc_index", //交易对
        "o":"49000", // open 开盘价
        "c":"50000",    //cloes 收盘价
        "h":"0.1", //high 最高价
        "l":"0.1", //low 最低价
        "a":"0.1", //amount 成交量
        "v":"0.1", //volume 成交额
        "ch":"0.21"   //change 涨跌幅
        "t":123124124   //时间戳
    }
}
```

## agg ticker

**请求**

语法: agg\_ticker@\{symbol}

示例: agg\_ticker\@btc\_usdt

速率: 1000ms

```json Response theme={null}
{
    "topic": "agg_ticker", 
    "event": "agg_ticker@btc_usdt", 
    "data": {
        "s":"btc_index", //交易对
        "o":"49000",     // open 开盘价
        "c":"50000",    //cloes 收盘价
        "h":"0.1",      //high 最高价
        "l":"0.1",       //low 最低价
        "a":"0.1",      //amount 成交量
        "v":"0.1",       //volume 成交额
        "ch":"0.21",   //change 涨跌幅

        "i":"0.21" ,   //index 指数价格

        "m":"0.21",   //mark 标记价格

        "bp":"0.21",   //bid price 买一价格

        "ap":"0.21" ,  //ask price 卖一价格

        "t":123124124   //时间戳
    }
}
```

## 指数价格

**请求**

语法: index\_price@\{symbol}

示例: index\_price\@btc\_usdt

速率: 1000ms

```json Response theme={null}
{
    "topic": "index_price", 
    "event": "index_price@btc_usdt", 
    "data": {
        "s":"btc_usdt", //交易对
        "p":"50000",    //价格
        "t":123124124   //时间戳
    }
}
```

## 标记价格

**请求**

语法: mark\_price@\{symbol}

示例: mark\_price\@btc\_usdt

速率: 1000ms

```json Response theme={null}
{
    "topic": "mark_price", 
    "event": "mark_price@btc_usdt", 
    "data": {
        "s":"btc_usdt", //交易对
        "p":"50000",    //价格
        "t":123124124   //时间戳
    }
}
```

## 增量深度

**请求**

语法: depth\_update@\{symbol},\{interval}

interval: 100/250/500/1000 默认速率100ms

示例: depth\_update\@btc\_usdt,100ms

```json Response theme={null}
{
    "topic": "depth_update", 
    "event": "depth_update@btc_usdt", 
    "data": {
        "s": "btc_usdt",        // symbol 交易对
        "pu": 120,              // previousUpdateId 等于上一次推送的lastUpdateId
        "fu": 121,              // firstUpdateId 等于上一次推送的lastUpdateId + 1
        "u": 123,               // lastUpdateId
        "a": [                  // asks 卖盘
            [                   // [0]价格, [1]数量
                "34000",        //价格
                "1.2"           //数量
            ], 
            [
                "34001", 
                "2.3"
            ]
        ], 
        "b": [                  // bids 买盘
            [
                "32000", 
                "0.2"
            ], 
            [
                "31000", 
                "0.5"
            ]
        ],
        "t": 123456789 // 时间戳
    }
}
```

## 有限深度

**请求**

语法: depth@\{symbol},\{levels},\{interval}

levels: 5/10/20/50

interval: 100/250/500/1000 默认速率1000ms

示例: depth\@btc\_usdt,50,1000ms

```json Response theme={null}
{
    "topic": "depth", 
    "event": "depth@btc_usdt,50", 
    "data": {
        "id": "1234", //lastUpdateId
        "s":"btc_index", //交易对
        "a":[["50000","0.1"],["50001","0.2"]],    //ask 卖单队列， [价格，数量]
        "b":[["49999","0.1"],["48888","0.2"]],   //bid 买单队列
        "t": 123456789 // 时间戳
    }
}
```

## 资金费率

**请求**

语法: fund\_rate@\{symbol}

示例: fund\_rate\@btc\_usdt

速率: 60s

```json Response theme={null}
{
    "topic": "fund_rate", 
    "event": "fund_rate@btc_usdt", 
    "data": {
        "s":"btc_usdt", //交易对
        "r":"0.01",    // 资金费率
        "t":123124124   //时间戳
    }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.