Portfolio Margin

Copy page

User Data Streams

Connect

• The base API endpoint is: https://papi.binance.com
• 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, if response -1125 error "This listenKey does not exist." Please use POST /papi/v1/listenKey to recreate listenKey.
• Doing a DELETE on a listenKey will close the stream and invalidate the listenKey.
• Doing a POST on an account with an active listenKey will return the currently active listenKey and extend its validity for 60 minutes.
• Connection method for Websocket:
  • Base Url: wss://fstream.binance.com/pm
  • User Data Streams are accessed at /ws/<listenKey>
  • Example: wss://fstream.binance.com/pm/ws/pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a65a1
• Message Ordering Guarantee:
  • For the same user on a single Websocket connection, messages of the same event type (e.g., ACCOUNT_UPDATE, ORDER_TRADE_UPDATE) are strictly ordered by both T (transaction time from Matching Engine) and E (event time when the message is generated).
  • Recommended: Use the E field for ordering updates, especially when:
    • Comparing events across different event types (e.g., ORDER_TRADE_UPDATE vs market data streams like aggTrade).
    • Events from different services may share the same T but have different E values due to processing timing.
    • For the same event type on the same connection, both T and E remain strictly ordered, so either field can be used reliably.
• A single connection is only valid for 24 hours; expect to be disconnected at the 24 hour mark
• Considering that RESTful endpoints may experience query delays under volatile market conditions, we strongly recommend prioritizing Websocket user data stream messages for retrieving orders, positions, and other information.

---

Event: Futures Balance and Position Update

Description

Event type is ACCOUNT_UPDATE.

• When balance or position get updated, this event will be pushed.

  • ACCOUNT_UPDATE will be pushed only when update happens on user's account, including changes on balances, positions, or margin type.
  • Unfilled orders or cancelled orders will not make the event ACCOUNT_UPDATE pushed, since there's no change on positions.
  • "position" in ACCOUNT_UPDATE: Only symbols of changed positions will be pushed.

• When "FUNDING FEE" changes to the user's balance, the event will be pushed with the brief message:

  • When "FUNDING FEE" occurs in a crossed position, ACCOUNT_UPDATE will be pushed with only the balance B (including the "FUNDING FEE" asset only), without any position P message.
  • When "FUNDING FEE" occurs in an isolated position, ACCOUNT_UPDATE will be pushed with only the balance B (including the "FUNDING FEE" asset only) and the relative position message P (including the isolated position on which the "FUNDING FEE" occurs only, without any other position message).

• The field "m" represents the reason type for the event and may shows the following possible types:

  • DEPOSIT
  • WITHDRAW
  • ORDER
  • FUNDING_FEE
  • WITHDRAW_REJECT
  • ADJUSTMENT
  • INSURANCE_CLEAR
  • ADMIN_DEPOSIT
  • ADMIN_WITHDRAW
  • MARGIN_TRANSFER
  • MARGIN_TYPE_CHANGE
  • ASSET_TRANSFER
  • OPTIONS_PREMIUM_FEE
  • OPTIONS_SETTLE_PROFIT
  • AUTO_EXCHANGE
  • COIN_SWAP_DEPOSIT
  • COIN_SWAP_WITHDRAW

• The field "bc" represents the balance change except for PnL and commission.

Event Name

ACCOUNT_UPDATE

Update Speed

50ms

Payload

Schema: accountUpdate

---

Event: Futures Order Update

Description

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

Side

• BUY
• SELL

Order Type

• MARKET
• LIMIT
• LIQUIDATION

Execution Type

• NEW
• CANCELED
• CALCULATED - Liquidation Execution
• EXPIRED
• TRADE

Order Status

• NEW
• PARTIALLY_FILLED
• FILLED
• CANCELED
• EXPIRED
• EXPIRED_IN_MATCH

Time in force

• GTC
• IOC
• FOK
• GTX

Liquidation and ADL:

• If user gets liquidated due to insufficient margin balance:
  • c shows as "autoclose-XXX", X shows as "NEW"
• If user has enough margin balance but gets ADL:
  • c shows as "adl_autoclose", X shows as "NEW"

Event Name

ORDER_TRADE_UPDATE

Payload

Schema: orderTradeUpdate

---

Event: Futures Account Configuration Update (Leverage Update)

Description

When the account configuration is changed, the event type will be pushed as ACCOUNT_CONFIG_UPDATE. When the leverage of a trade pair changes, the payload will contain the object ac to represent the account configuration of the trade pair, where s represents the specific trade pair and l represents the leverage.

Event Name

ACCOUNT_CONFIG_UPDATE

Payload

Schema: accountConfigUpdate

---

Event: Conditional Order Trade Update

Description

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

Side

• BUY
• SELL

Conditional Order Type

• STOP
• TAKE_PROFIT
• STOP_MARKET
• TAKE_PROFIT_MARKET
• TRAILING_STOP_MARKET

Execution Type

• NEW
• CANCELED
• CALCULATED - Liquidation Execution
• EXPIRED
• TRADE

Order Status

• NEW
• CANCELED
• EXPIRED
• TRIGGERED
• FINISHED

Time in force

• GTC
• IOC
• FOK
• GTX

Event Name

CONDITIONAL_ORDER_TRADE_UPDATE

Payload

Schema: conditionalOrderTradeUpdate

---

Event: Margin Balance Update

Description

Margin Balance Update

Event Name

balanceUpdate

Payload

Schema: balanceUpdate

---

Event: Margin Order Update

Description

Margin orders are updated with the executionReport event.

Execution types:

• NEW - The order has been accepted into the engine.
• CANCELED - The order has been canceled by the user.
• REJECTED - The order has been rejected and was not processed (This message appears only with Cancel Replace Orders wherein the new order placement is rejected but the request to cancel request succeeds.)
• TRADE - Part of the order or all of the order's quantity has filled.
• EXPIRED - The order was canceled according to the order type's rules (e.g. LIMIT FOK orders with no fill, LIMIT IOC or MARKET orders that partially fill) or by the exchange, (e.g. orders canceled during liquidation, orders canceled during maintenance).
• TRADE_PREVENTION - The order has expired due to STP trigger.

Event Name

executionReport

Payload

Schema: executionReport

---

Event: Margin Account Update

Description

outboundAccountPosition is sent any time an account balance has changed and contains the assets that were possibly changed by the event that generated the balance change.

Event Name

outboundAccountPosition

Payload

Schema: outboundAccountPosition

---

Event: Liability Update

Description

Margin Liability update

Event Name

liabilityChange

Payload

Schema: liabilityChange

---

Event: OpenOrderLoss Update

Description

Cross margin order margin stream

Event Name

openOrderLoss

Payload

Schema: openOrderLoss

---

Event: Risk Level Change

Description

• When the user's position risk ratio is too high, this stream will be pushed.
• This message is only used as risk guidance information and is not recommended for investment strategies.
• RISK_LEVEL_CHANGE includes following types: MARGIN_CALL, REDUCE_ONLY, FORCE_LIQUIDATION
• In the case of a highly volatile market, there may be the possibility that the user's position has been liquidated at the same time when this stream is pushed out.

Event Name

RISK_LEVEL_CHANGE

Payload

Schema: riskLevelChange

---

Event: Algo Order Update

Description

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

Algo Status:

• NEW: Conditional order was successfully placed but has not yet been triggered.
• CANCELED: Conditional order has been canceled.
• TRIGGERING: Order has met the triggering condition and has been forwarded to the matching engine.
• TRIGGERED: Order has been successfully placed into the matching engine.
• FINISHED: Triggered conditional order has been filled or canceled in the matching engine.
• REJECTED: Conditional order has been denied by the matching engine (e.g. margin check failures).
• EXPIRED: Conditional order has been canceled by the system.

Event Name

ALGO_UPDATE

Payload

Schema: algoOrderUpdate

---

Event: User Data Stream Expired

Description

When the listenKey used for the user data stream turns expired, this event will be pushed.

Notice:

• This event is not related to the websocket disconnection.
• This event will be received only when a valid listenKey in connection got expired.
• No more user data event will be updated after this event received until a new valid listenKey used.

Event Name

listenKeyExpired

Payload

Schema: listenKeyExpired