> ## 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\://stream.monochrome.exchange/public**

### 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",           //symbol
        "i": 6316559590087222000,  //成交id
        "t": 1655992403617,        //时间
        "oi": 6616559590087222666, //订单id
        "p": "43000",              //价格
        "q": "0.21",               //数量
        "v": "9030"                //金额
        "b": true                  //是否是buyerMaker
    }
}
```

## 心跳

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

## 订阅参数

**结构**

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

## Orderbook 维护

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

1.订阅 wss\://stream.monochrome.exchange/public，depth\_update\@btc\_usdt

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

3.访问Rest接口 [https://sapi.monochrome.exchange/v4/public/depth?symbol=btc\_usdt\&limit=500](https://sapi.monochrome.exchange/v4/public/depth?symbol=btc_usdt\&limit=500) 获得一个500档的深度快照

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

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

6.每一个新event的fi应该恰好等于上一个event的i+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_usdt",           //symbol
        "i": 6316559590087222000,  //成交id
        "t": 1655992403617,        //时间
        "oi": 6616559590087222666, //订单id
        "p": "43000",              //价格
        "q": "0.21",               //数量
        "v": "9030"                //金额
        "b": true                  //是否是buyerMaker
    }
}
```

## 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_usdt",       // symbol 交易对
            "t": 1656043200000,    // time 时间
            "i": "5m",             // interval 间隔
            "o": "44000",          // open 开盘价
            "c": "50000",          // close 收盘价
            "h": "52000",          // high 最⾼价
            "l": "36000",          // low 最低价
            "q": "34.2",           // qty 成交量
            "v": "230000"          // volume 成交额
            }
}
```

## 有限深度

**请求**

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

levels: 5, 10, 20, 50

示例: depth\@btc\_usdt,20

速率: 1000ms

```json Response theme={null}
{
    "topic": "depth", 
    "event": "depth@btc_usdt,20", 
    "data": {
        "s": "btc_usdt",        // symbol 交易对
        "i": 12345678,          // updateId
        "t": 1657699200000,     // time 时间戳
        "a": [                  // asks 卖盘
            [                   //[0]价格, [1]数量
                "34000",        //价格
                "1.2"           //数量 
            ], 
            [
                "34001", 
                "2.3"
            ]
        ], 
        "b": [                   // bids 买盘
            [
                "32000", 
                "0.2"
            ], 
            [
                "31000", 
                "0.5"
            ]
        ]
    }
}
```

## 增量深度

**请求**

语法: depth\_update@\{symbol}

示例: depth\_update\@btc\_usdt

速率：100ms

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

## ticker

**请求**

语法: ticker@\{symbol}

示例: ticker\@btc\_usdt

速率: 1000ms

```json Response theme={null}
{
    "topic": "ticker", 
    "event": "ticker@btc_usdt", 
    "data": {
        "s": "btc_usdt",      // symbol 交易对
        "t": 1657586700119,   // time 最后成交时间
        "cv": "-200",         // priceChangeValue 24⼩时价格变化
        "cr": "-0.02",        // priceChangeRate 24⼩时价格变化(百分⽐)
        "o": "30000",         // open 第⼀笔
        "c": "39000",         // close 最后⼀笔
        "h": "38000",         // high 最⾼价
        "l": "40000",         // low 最低价
        "q": "4",             // quantity 成交量
        "v": "150000",        // volume 成交额
    }
}
```


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