> ## 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: user

> Futures API: websocket: user.

## General WSS information

### Base Address

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

### Request Headers

The request header of the compression extension protocol must be added.

Sec-Websocket-Extensions:permessage-deflate

### Subscription Steps

Step 1: The user need to call the interface: /v1/user/listen-key to get the listenKey.
Step 2: When subscribing to user-related websocket events, users need to send: \{“method”:”SUBSCRIBE”,”params”:\[“order@\{listenKey obtained in the previous step}”],”id”:”test1”}
If you receive “invalid\_listen\_key”, it means that the listenKey is expired or invalid, and you need to re-request to obtain the listenKey.
ps: listenKey is obtained through the interface.
User-related data will be pushed after subscription.

## Request message format

subscribe:

```js theme={null}
  {
     "method": "SUBSCRIBE/UNSUBSCRIBE",
     "params": [
         "{order}@{listenKey}",
         "{trade}@{listenKey}",
         "{balance}@{listenKey}",
         "{position}@{listenKey}",
         "{notify}@{listenKey}"
      ],
     "id": "{id}"    //user defined
  }
```

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

## Response message format

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

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

## Subscription parameters

**format**

\{topic}@\{listenKey},…

## Balance change

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:Coin-M,2:USDT-M
         "walletBalance":"123", // Balance
         "openOrderMarginFrozen":"123", // Frozen order
         "isolatedMargin":"213",  // Isolated Margin
         "crossedMargin":"0" //Crossed Margin
       }  
}
```

## Change position

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",  // Position quantity
           "closeOrderSize": "100",  //  Pending order quantity (Cont)
           "availableCloseSize": "23",  //  Available quantity (Cont)
           "realizedProfit": "123"   //  Realized profit and loss
           "entryPrice":"213",   //  Open position average price
           "isolatedMargin":"213",  //  Isolated Margin
           "openOrderMarginFrozen": "123", //  Occupied open position margin
           "underlyingType": ""// COIN_BASED, U_BASED
           "leverage":20  // Leverage
       }
}
```

## Transactions

subscribe:

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

```json Response theme={null}
{
    "topic": "trade", 
    "event": "trade@123456", 
    "data": {
            "orderId":"12312312",       // Order ID
            "clientOrderId":"123456",   // Client order ID
            "price":"34244",            // Price
            "quantity":"123",           // Quantity
            "marginUnfrozen":"123",     // Quantity of unfrozen margin
            "timestamp":1731231231,     // Timestamp
            "symbol": "btc_usdt",       //Symbol
            "orderSide": "BUY",         //Order side
            "positionSide": "LONG",     //Position side
            "isMaker": true,            //Is maker or not, true:maker;false:taker
            "fee": 0.0002               //fee
       }
}
```

## user Order

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",        // Trading pair
         "orderId": "1234",          // Order Id
         "origQty": "34244",         // Original Quantity
         "avgPrice": "123",          // Quantity
         "price": "1111",            // Average price
         "executedQty":"34244",      // Volume (Cont)
         "orderSide": "BUY",         // BUY, SELL
         "timeInForce": "IOC",       // Valid way
         "positionSide": "LONG",     // LONG, SHORT
         "marginFrozen":"123",       // Occupied margin
         "sourceType":"default",     //  DEFAULT:normal order,ENTRUST:plan commission,PROFIR:Take Profit and Stop Loss
         "type" : "ORDER",           // 
         "state": "FILLED",          // state:NEW：New order (unfilled);PARTIALLY_FILLED:Partial deal;PARTIALLY_CANCELED:Partial revocation;FILLED:Filled;CANCELED:Cancled;REJECTED:Order failed;EXPIRED：Expired
         "createdTime": 1731231231,  // CreateTime
         "leverage":20,              //leverage
         "positionType": "ISOLATED", //position type:CROSSED;ISOLATED
         "orderType:": "MARKET"      //Order Type [LIMIT;MARKET]
       }
}
```

## Message

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",  // Position quantity
           "notifyType": "WARN",  // Notification Type:WARN:Warning, about to be levelled,PARTIAL:Partially Liquidation,LIQUIDATION:Liquidation,ADL:ADL
    }
}
```


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