Web-Socket User Data Streams

  • The base API endpoint is: https://fapi.binance.com
  • A User Data Stream listenKey is valid for 30 minutes after creation.
  • Doing a PUT on a listenKey will extend its validity for 30 minutes.
  • Doing a DELETE on a listenKey will close the stream.
  • The base websocket endpoint is: wss://fstream.binance.com
  • User Data Streams are accessed at /ws/<listenKey>
  • User data stream payloads are not guaranteed to be in order during heavy periods; make sure to order your updates using E

User Data Stream Endpoints

Start user data stream (USER_STREAM)

POST /fapi/v1/listenKey (HMAC SHA256)

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

Weight: 1

Parameters:

Name Type Mandatory Description
recvWindow LONG NO
timestamp LONG YES

Response:

{
  "listenKey": "pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a65a1"
}

Keepalive user data stream (USER_STREAM)

PUT /fapi/v1/listenKey (HMAC SHA256)

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

Weight: 1

Parameters:

Name Type Mandatory Description
recvWindow LONG NO
timestamp LONG YES

Response:

{}

Close user data stream (USER_STREAM)

DELETE /fapi/v1/listenKey (HMAC SHA256)

Close out a user data stream.

Weight: 1

Parameters:

Name Type Mandatory Description
recvWindow LONG NO
timestamp LONG YES

Response:

{}

Websocket Event

Balance and Position update

Event Type is ACCOUNT_UPDATE. When balance or position get updated, will push this event.

Payload:

{
  "e": "ACCOUNT_UPDATE",         // Event type
  "E": 1564745798939             // Event time
  "a": [
    {
      "B":[                      // Balances
        {
          "a":"USDT",            // Asset
          "wb":"122624"          // Wallet Balance
        },
        {
          "a":"BTC",
          "wb":"0"
        }
      ],
      "P":[                      // Positions
        {
          "s":"BTCUSDT",         // Symbol
          "pa":"1",              // Position Amount
          "ep":"9000",           // Entry Price
          "cr":"200"             // (Pre-fee) accumulated realized
        }
      ]
    }
  ]
}

Order Update

When new order created, order status changed will push such event. Event type is ORDER_TRADE_UPDATE.

Payload:

{
  "e": "ORDER_TRADE_UPDATE",       // Event type
  "E": 1564745798939               // Event time
  "o":
  {
    "s": "BTCUSDT",                // Symbol
    "c": "211",                    // Client Order Id
    "S": "BUY",                    // Side
    "o": "LIMIT",                  // Order Type
    "f": "GTC",                    // Time In Force
    "q": "1.00000000",             // Original quantity
    "p": "0.10264410",             // Price
    "ap": "0.10264410",            // Average Price
    "sp": "0.10264410",            // Stop Price
    "x": "NEW",                    // Execution Type
    "X": "NEW",                    // Order Status
    "i": 4293153,                  // Order Id
    "l": "0.00000000",             // Order Last Filled Quantity
    "z": "0.00000000",             // Order Filled Accumulated Quantity
    "L": "0.00000000",             // Last Filled Price
    "N": "USDT",                   // Commission Asset (Will not push if no commission)
    "n": "0",                      // Commission (Will not push if no commission)
    "T": 1499405658657,            // Order Trade Time
    "t": -1,                       // Trade Id
    "b": 100,                      // Bids Notional
    "a": 100                       // Ask Notional
    "m": False                     // Is this trade the maker side?
  }

}

Side

  • BUY
  • SELL

Order Type

  • MARKET
  • LIMIT
  • STOP

Execution Type

  • NEW
  • PARTIAL_FILL
  • FILL
  • CANCELED
  • PENDING_CANCEL
  • REJECTED
  • CALCULATED // Liquidation Execution
  • EXPIRED
  • TRADE
  • RESTATED

Order Status

  • NEW
  • PARTIALLY_FILLED
  • FILLED
  • CANCELED
  • REPLACED
  • PENDING_CANCEL
  • STOPPED
  • REJECTED
  • EXPIRED
  • NEW_INSURANCE // Liquidation with Insurance Fund
  • NEW_ADL // Counterparty Liquidation

Time In Force

  • GTC
  • IOC
  • FOK
  • GTX