User Data Stream

General WSS information

• A User Data Stream listenKey is valid for 60 minutes after creation.

• Doing a PUT on a listenKey will extend its validity for 60 minutes.

• Doing a DELETE on a listenKey will close the stream.

• User Data Streams are accessed at /openapi/ws/<listenKey>

• A single connection to api endpoint is only valid for 24 hours; expect to be disconnected at the 24 hour mark

• User data stream payloads are not guaranteed to be in order during heavy periods; make sure to order your updates using E

API Endpoints

Create a listenKey

POST /openapi/v1/userDataStream

Start a new user data stream. The stream will close after 60 minutes unless a keepalive is sent.

Weight: 1

Parameters:

Name	Type	Mandatory	Description
recvWindow	LONG	NO
timestamp	LONG	YES

Response:

{
  "listenKey": "1A9LWJjuMwKWYP4QQPw34GRm8gz3x5AephXSuqcDef1RnzoBVhEeGE963CoS1Sgj"
}

Ping/Keep-alive a listenKey

PUT /openapi/v1/userDataStream

Keepalive a user data stream to prevent a time out. User data streams will close after 60 minutes. It's recommended to send a ping about every 30 minutes.

Weight: 1

Parameters:

Name	Type	Mandatory	Description
listenKey	STRING	YES
recvWindow	LONG	NO
timestamp	LONG	YES

Response:

{}

Close a listenKey

DELETE /openapi/v1/userDataStream

Close out a user data stream.

Weight: 1

Parameters:

Name	Type	Mandatory	Description
listenKey	STRING	YES
recvWindow	LONG	NO
timestamp	LONG	YES

Response:

{}

Web Socket Payloads

Account Update

Account state is updated with the outboundAccountInfo event.

Payload:

{
  "e": "outboundAccountInfo",   // Event type
  "E": 1499405658849,           // Event time
  // "m": 0,                       // Maker commission rate (bips)
  // "t": 0,                       // Taker commission rate (bips)
  // "b": 0,                       // Buyer commission rate (bips)
  // "s": 0,                       // Seller commission rate (bips)
  "T": true,                    // Can trade?
  "W": true,                    // Can withdraw?
  "D": true,                    // Can deposit?
  // "u": 1499405658848,           // Time of last account update
  "B": [                        // Balances changed
    {
      "a": "LTC",               // Asset
      "f": "17366.18538083",    // Free amount
      "l": "0.00000000"         // Locked amount
    }
  ]
}

Order Update

Orders are updated with the executionReport event. Check the API documentation and below for relevant enum definitions. Average price can be found by doing Z divided by z.

Payload:

Spot:

{
  "e": "executionReport",        // Event type
  "E": 1499405658658,            // Event time
  "s": "ETHBTC",                 // Symbol
  "c": 1000087761,               // Client order ID
  "S": "BUY",                    // Side
  "o": "LIMIT",                  // Order type
  "f": "GTC",                    // Time in force
  "q": "1.00000000",             // Order quantity
  "p": "0.10264410",             // Order price
  // "P": "0.00000000",             // Stop price
  // "F": "0.00000000",             // Iceberg quantity
  // "g": -1,                       // Ignore
  // "x": "NEW",                    // Current execution type
  "X": "NEW",                    // Current order status
  // "r": "NONE",                   // Order reject reason; will be an error code.
  "i": 4293153,                  // Order ID
  "l": "0.00000000",             // Last executed quantity
  "z": "0.00000000",             // Cumulative filled quantity
  "L": "0.00000000",             // Last executed price
  "n": "0",                      // Commission amount
  "N": null,                     // Commission asset
  "u": true,                     // Is the trade normal, ignore for now
  // "T": 1499405658657,            // Transaction time
  // "t": -1,                       // Trade ID
  // "I": 8641984,                  // Ignore
  "w": true,                     // Is the order working? Stops will have
  "m": false,                    // Is this trade the maker side?
  // "M": false,                    // Ignore
  "O": 1499405658657,            // Order creation time
  "Z": "0.00000000"              // Cumulative quote asset transacted quantity
}

Contract:

{
    'e': 'contractExecutionReport',         // Event type
    'E': '1590553032232',         // Event time
    's': 'BTC-PERP-BUSDT',         // Symbol
    'c': 'abc123456',  // Client Order ID
    'S': 'SELL',        // Sidee
    'o': 'LIMIT',         // Order Type
    'f': 'IOC',         //  Time in Force
    'q': '2',         // Order Quantity
    'p': '8839.6',     // Order Price
    'X': 'FILLED',     // Current Order Status
    'i': '635999362524162048',         // Order Id
    // 'M': '',         // Ignore
    'l': '2',         // Last executed quantity
    'z': '2',         // Cumulative filled quantity
    'L': '8839.6',         // Last executed price
    'n': '0',         // Commission amount
    'N': 'BUSDT',         // Commission Token Name 
    'u': false,         // Is the trade normal, ignore for now
    'w': true,         // Is the order working? For stop orders
    'm': false,         // Is this trade the maker side?
    'O': '1590553032163',         // Order creation time
    'Z': '17679.2',         // Cumulative quote asset transacted quantity
    // 'A': '',        //Ignore
    'C': True,         // Is this a "close" order?
    'v': '3'        // Leverage
    }

Execution types:

• NEW

• PARTIALLY_FILLED

• FILLED

• CANCELED

• REJECTED

Position Update

Payload:

{
  "e": "outboundContractPositionInfo",  // Event type
  "A": "448992579076322903",            // Contract account id
  "s": "BTC-SWAP-USDT",                 // Contract symbol
  "S": "LONG",                          // Position direction
  "p": "9851.5",                        // avg price
  "P": "269",                           // Position total
  "a": "269",                           // Position avaiable
  "f": "7705.9",                        // flp
  "m": "59.7884",                       // margin
  "r": "-0.0139"                        // realized pnl
}