> ## 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/user**

### Request Headers

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

Sec-Websocket-Extensions:permessage-deflate

### 订阅步骤

第一步：用户要先调用接口:/v1/user/listen-key   获取listenKey

第二步：订阅用户相关的websocket事件时需要发送：\{“method”:”SUBSCRIBE”,”params”:\[“order@\{上一步获取的listenKey}”],”id”:”test1”}

如果收到”invalid\_listen\_key”表示listenKey过期或者无效，需要重新请求获取listenKey

ps：listenKey通过接口获取

订阅之后会推送用户相关数据

## 请求报文格式

subscribe:

```js theme={null}
  {
   "method": "SUBSCRIBE/UNSUBSCRIBE",
   "params": [
          "{order}@{listenKey}",
          "{trade}@{listenKey}",
          "{balance}@{listenKey}",
          "{position}@{listenKey}",
          "{notify}@{listenKey}"
        ],
   "id": "{id}"    //用户自己定义
   }
```

```json Response theme={null}
{"method":"SUBSCRIBE",
 "params":["order@A246C3DF8EE532DC75007BC5D86698541678596355681"],
 "id":"test1"
}
```

## 响应报文格式

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

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

## 订阅参数

**结构**

\{topic}@\{listenKey},…

## 余额变更

subscribe:

```js theme={null}
  {
     "method": "SUBSCRIBE/UNSUBSCRIBE",
     "params": [
         "{balance}@{listenKey}",
      ],
     "id": "{id}"
  }
```

```json Response theme={null}
{
    "topic": "balance", 
    "event": "balance@123456", 
    "data": {
         "coin":"usdt",
         "underlyingType":1, //  1:币本位，2:U本位
         "walletBalance":"123", // 钱包余额
         "openOrderMarginFrozen":"123", // 订单冻结
         "isolatedMargin":"213",  // 逐仓保证金
         "crossedMargin":"0" //全仓保证金
       }  
}
```

## 仓位变更

subscribe:

```js theme={null}
  {
     "method": "SUBSCRIBE/UNSUBSCRIBE",
     "params": [
         "{position}@{listenKey}",
      ],
     "id": "{id}"
  }
```

```json Response theme={null}
{
    "topic": "position", 
    "event": "position@123456", 
    "data": {
           "symbol":"btc_usdt",
           "contractType": "PERPUTUAL", //合约类型，PERPUTUAL，DELIVERY
           "positionType": "ISOLATED",  // "ISOLATED", "CROSSED"
           "positionSide": "LONG",
           "positionSize":"123",  // 持仓数量
           "closeOrderSize": "100",  //  平仓挂单数量
           "availableCloseSize": "23",  //  可平仓张数
           "realizedProfit": "123"   //  已实现盈亏
           "entryPrice":"213",   //  开仓均价
           "isolatedMargin":"213",  //  逐仓保证金
           "openOrderMarginFrozen": "123", //  开仓订单占用保证金
           "underlyingType": ""// COIN_BASED, U_BASED
           "leverage":20  // 杠杆倍数
       }
}
```

## 用户成交

subscribe:

```js theme={null}
  {
     "method": "SUBSCRIBE/UNSUBSCRIBE",
     "params": [
         "{trade}@{listenKey}",
      ],
     "id": "{id}"
  }
```

```json Response theme={null}
{
    "topic": "trade", 
    "event": "trade@123456", 
    "data": {
            "orderId":"12312312",     // 订单id
            "clientOrderId":"123456", // 自定义订单id
            "price":"34244",          // 价格
            "quantity":"123",         // 数量
            "marginUnfrozen":"123",   // 保证金解冻数量
            "timestamp":1731231231,   // 时间戳
            "symbol": "btc_usdt",     //交易对
            "orderSide": "BUY",       //订单方向
            "positionSide": "LONG",   //持仓方向
            "isMaker": true,          //是否是maker,true:maker;false:taker
            "fee": 0.0002             //手续费
       }
}
```

## 用户订单

subscribe:

```js theme={null}
  {
     "method": "SUBSCRIBE/UNSUBSCRIBE",
     "params": [
         "{order}@{listenKey}",
      ],
     "id": "{id}"
  }
```

```json Response theme={null}
{
    "topic": "order", 
    "event": "order@123456", 
    "data": {
         "symbol":"btc_usdt",        // 交易对
         "orderId": "1234",          // 订单id
         "origQty": "34244",         // 下单数量
         "avgPrice": "123",          // 成交均价
         "price": "1111",            // 下单价格
         "executedQty":"34244",      // 已成交数量
         "orderSide": "BUY",         // 买卖方向
         "positionSide": "LONG",     // LONG, SHORT
         "marginFrozen":"123",       // 占用保证金
         "sourceType":"default",     // DEFAULT:普通订单， ENTRUST:计划委托，PROFIR:止盈止损
         "type" : "ORDER",           // 
         "state": "",                // 订单状态 NEW：新建订单;未成交; PARTIALLY_FILLED：部分成交；PARTIALLY_CANCELED：部分撤销；FILLED：全部成交；CANCELED：已撤销；REJECTED：下单失败；EXPIRED：已过期
         "createdTime": 1731231231,   // 下单时间
         "leverage":20,              // 杠杆倍数
         "positionType": "ISOLATED", // 仓位类型：CROSSED（全仓）；ISOLATED（逐仓）
         "orderType:": "MARKET"      // 订单类型 LIMIT：限价, MARKET：市价
       }
}
```

## 用户消息

subscribe:

```js theme={null}
  {
     "method": "SUBSCRIBE/UNSUBSCRIBE",
     "params": [
         "{notify}@{listenKey}",
      ],
     "id": "{id}"
  }
```

```json Response theme={null}
{
    "topic": "notify", 
    "event": "notify", 
    "data": {
           "symbol":"btc_usdt",
           "positionType": "ISOLATED",  
           "positionSide": "LONG",
           "positionSize":"123",  // 持仓数量
           "notifyType": "WARN",  // 通知类型:  WARN：告警，即将被强平，PARTIAL：部分强平，LIQUIDATION：全部强平，ADL：自动减仓
    }
}
```


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