Skip to main content

nautilus_binance/futures/websocket/streams/
messages.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Binance Futures WebSocket message types.
17//!
18//! Futures streams use standard JSON encoding (not SBE like Spot).
19//!
20//! The handler emits venue-specific types via [`BinanceFuturesWsStreamsMessage`].
21//! Data and execution client layers convert these to Nautilus domain types.
22
23use nautilus_core::serialization::{
24    deserialize_decimal_from_str, deserialize_optional_decimal_from_str,
25};
26use nautilus_model::identifiers::{
27    ClientOrderId, InstrumentId, StrategyId, TraderId, VenueOrderId,
28};
29use nautilus_network::websocket::WebSocketClient;
30use rust_decimal::Decimal;
31use serde::{Deserialize, Serialize};
32use ustr::Ustr;
33
34use crate::{
35    common::enums::{
36        BinanceAlgoStatus, BinanceAlgoType, BinanceFuturesOrderType, BinanceFuturesTradeType,
37        BinanceKlineInterval, BinanceMarginType, BinanceOrderStatus, BinancePositionSide,
38        BinancePriceMatch, BinanceSelfTradePreventionMode, BinanceSide, BinanceTimeInForce,
39        BinanceWorkingType, BinanceWsMethod,
40    },
41    futures::http::BinanceFuturesInstrument,
42};
43
44/// Output message from the Futures WebSocket streams handler.
45///
46/// Contains venue-specific types for both market data and user data stream
47/// events. The data and execution client layers convert these to Nautilus
48/// domain types using parse functions with instrument context.
49#[derive(Debug, Clone)]
50pub enum BinanceFuturesWsStreamsMessage {
51    /// Aggregate trade stream.
52    AggTrade(BinanceFuturesAggTradeMsg),
53    /// Trade stream.
54    Trade(BinanceFuturesTradeMsg),
55    /// Best bid/ask (book ticker) stream.
56    BookTicker(BinanceFuturesBookTickerMsg),
57    /// Order book depth update stream.
58    DepthUpdate(BinanceFuturesDepthUpdateMsg),
59    /// Mark price stream.
60    MarkPrice(BinanceFuturesMarkPriceMsg),
61    /// Kline/candlestick stream.
62    Kline(BinanceFuturesKlineMsg),
63    /// Force liquidation order stream.
64    ForceOrder(BinanceFuturesLiquidationMsg),
65    /// 24hr ticker stream.
66    Ticker(BinanceFuturesTickerMsg),
67    /// Account update (balance/position changes).
68    AccountUpdate(BinanceFuturesAccountUpdateMsg),
69    /// Order/trade update.
70    OrderUpdate(Box<BinanceFuturesOrderUpdateMsg>),
71    /// Trade Lite fill notification (low-latency subset of `OrderUpdate`).
72    TradeLite(Box<BinanceFuturesTradeLiteMsg>),
73    /// Algo order update (conditional orders via Algo Service).
74    AlgoUpdate(Box<BinanceFuturesAlgoUpdateMsg>),
75    /// Margin call warning.
76    MarginCall(BinanceFuturesMarginCallMsg),
77    /// Account configuration change (leverage, etc.).
78    AccountConfigUpdate(BinanceFuturesAccountConfigMsg),
79    /// Listen key expired.
80    ListenKeyExpired,
81    /// Error from the server.
82    Error(BinanceFuturesWsErrorMsg),
83    /// WebSocket reconnected; carries the correlation IDs of the unsubscribe
84    /// requests the old connection abandoned.
85    Reconnected(Vec<u64>),
86    /// Venue confirmation of an unsubscribe request, carrying the confirmed stream
87    /// names and the request's correlation ID when one was supplied.
88    Unsubscribed {
89        /// Confirmed stream names.
90        streams: Vec<String>,
91        /// Correlates the confirmation with the caller's unsubscribe lifecycle.
92        correlation: Option<u64>,
93    },
94}
95
96/// Error message from Binance Futures WebSocket.
97#[derive(Debug, Clone)]
98pub struct BinanceFuturesWsErrorMsg {
99    /// Error code from Binance.
100    pub code: i64,
101    /// Error message.
102    pub msg: String,
103}
104
105/// Handler command for data client-handler communication.
106#[derive(Debug)]
107pub enum BinanceFuturesWsStreamsCommand {
108    /// Set the WebSocket client reference.
109    SetClient(WebSocketClient),
110    /// Disconnect from the WebSocket.
111    Disconnect,
112    /// Subscribe to streams.
113    Subscribe { streams: Vec<String> },
114    /// Unsubscribe from streams.
115    Unsubscribe {
116        /// Streams to unsubscribe from.
117        streams: Vec<String>,
118        /// Correlates the venue confirmation with the caller's unsubscribe lifecycle.
119        correlation: Option<u64>,
120    },
121}
122
123/// Handler command for execution client-handler communication.
124#[derive(Debug)]
125pub enum ExecHandlerCommand {
126    /// Set the WebSocket client reference.
127    SetClient(WebSocketClient),
128    /// Disconnect from the WebSocket.
129    Disconnect,
130    /// Initialize instruments in the handler cache.
131    InitializeInstruments(Vec<BinanceFuturesInstrument>),
132    /// Update a single instrument in the handler cache.
133    UpdateInstrument(BinanceFuturesInstrument),
134    /// Subscribe to user data stream.
135    Subscribe { streams: Vec<String> },
136    /// Register an order for context tracking.
137    RegisterOrder {
138        client_order_id: ClientOrderId,
139        trader_id: TraderId,
140        strategy_id: StrategyId,
141        instrument_id: InstrumentId,
142    },
143    /// Register a cancel request for context tracking.
144    RegisterCancel {
145        client_order_id: ClientOrderId,
146        trader_id: TraderId,
147        strategy_id: StrategyId,
148        instrument_id: InstrumentId,
149        venue_order_id: Option<VenueOrderId>,
150    },
151    /// Register a modify request for context tracking.
152    RegisterModify {
153        client_order_id: ClientOrderId,
154        trader_id: TraderId,
155        strategy_id: StrategyId,
156        instrument_id: InstrumentId,
157        venue_order_id: Option<VenueOrderId>,
158    },
159}
160
161/// Aggregate trade stream message.
162#[derive(Debug, Clone, Deserialize)]
163pub struct BinanceFuturesAggTradeMsg {
164    /// Event type.
165    #[serde(rename = "e")]
166    pub event_type: String,
167    /// Event time in milliseconds.
168    #[serde(rename = "E")]
169    pub event_time: i64,
170    /// Symbol.
171    #[serde(rename = "s")]
172    pub symbol: Ustr,
173    /// Aggregate trade ID.
174    #[serde(rename = "a")]
175    pub agg_trade_id: u64,
176    /// Price.
177    #[serde(rename = "p")]
178    pub price: String,
179    /// Quantity.
180    #[serde(rename = "q")]
181    pub quantity: String,
182    /// First trade ID.
183    #[serde(rename = "f")]
184    pub first_trade_id: u64,
185    /// Last trade ID.
186    #[serde(rename = "l")]
187    pub last_trade_id: u64,
188    /// Trade time in milliseconds.
189    #[serde(rename = "T")]
190    pub trade_time: i64,
191    /// Is buyer the market maker.
192    #[serde(rename = "m")]
193    pub is_buyer_maker: bool,
194}
195
196/// Trade stream message.
197#[derive(Debug, Clone, Deserialize)]
198pub struct BinanceFuturesTradeMsg {
199    /// Event type.
200    #[serde(rename = "e")]
201    pub event_type: String,
202    /// Event time in milliseconds.
203    #[serde(rename = "E")]
204    pub event_time: i64,
205    /// Symbol.
206    #[serde(rename = "s")]
207    pub symbol: Ustr,
208    /// Trade ID.
209    #[serde(rename = "t")]
210    pub trade_id: u64,
211    /// Price.
212    #[serde(rename = "p")]
213    pub price: String,
214    /// Quantity.
215    #[serde(rename = "q")]
216    pub quantity: String,
217    /// Trade type.
218    #[serde(rename = "X")]
219    pub trade_type: BinanceFuturesTradeType,
220    /// Trade time in milliseconds.
221    #[serde(rename = "T")]
222    pub trade_time: i64,
223    /// Is buyer the market maker.
224    #[serde(rename = "m")]
225    pub is_buyer_maker: bool,
226}
227
228/// Order book depth update stream message.
229#[derive(Debug, Clone, Deserialize)]
230pub struct BinanceFuturesDepthUpdateMsg {
231    /// Event type.
232    #[serde(rename = "e")]
233    pub event_type: String,
234    /// Event time in milliseconds.
235    #[serde(rename = "E")]
236    pub event_time: i64,
237    /// Transaction time in milliseconds.
238    #[serde(rename = "T")]
239    pub transaction_time: i64,
240    /// Symbol.
241    #[serde(rename = "s")]
242    pub symbol: Ustr,
243    /// First update ID.
244    #[serde(rename = "U")]
245    pub first_update_id: u64,
246    /// Final update ID.
247    #[serde(rename = "u")]
248    pub final_update_id: u64,
249    /// Previous final update ID.
250    #[serde(rename = "pu")]
251    pub prev_final_update_id: u64,
252    /// Bids [price, quantity].
253    #[serde(rename = "b")]
254    pub bids: Vec<[String; 2]>,
255    /// Asks [price, quantity].
256    #[serde(rename = "a")]
257    pub asks: Vec<[String; 2]>,
258}
259
260/// Mark price stream message.
261#[derive(Debug, Clone, Deserialize)]
262pub struct BinanceFuturesMarkPriceMsg {
263    /// Event type.
264    #[serde(rename = "e")]
265    pub event_type: String,
266    /// Event time in milliseconds.
267    #[serde(rename = "E")]
268    pub event_time: i64,
269    /// Symbol.
270    #[serde(rename = "s")]
271    pub symbol: Ustr,
272    /// Mark price.
273    #[serde(rename = "p")]
274    pub mark_price: String,
275    /// Mark price moving average (added by venue, may be absent on older payloads).
276    #[serde(rename = "ap", default)]
277    pub mark_price_moving_avg: Option<String>,
278    /// Index price.
279    #[serde(rename = "i")]
280    pub index_price: String,
281    /// Estimated settle price.
282    #[serde(rename = "P")]
283    pub estimated_settle_price: String,
284    /// Funding rate.
285    #[serde(rename = "r")]
286    pub funding_rate: String,
287    /// Next funding time in milliseconds.
288    #[serde(rename = "T")]
289    pub next_funding_time: i64,
290}
291
292/// Book ticker stream message.
293#[derive(Debug, Clone, Deserialize)]
294pub struct BinanceFuturesBookTickerMsg {
295    /// Event type.
296    #[serde(rename = "e")]
297    pub event_type: String,
298    /// Update ID.
299    #[serde(rename = "u")]
300    pub update_id: u64,
301    /// Event time in milliseconds.
302    #[serde(rename = "E")]
303    pub event_time: i64,
304    /// Transaction time in milliseconds.
305    #[serde(rename = "T")]
306    pub transaction_time: i64,
307    /// Symbol.
308    #[serde(rename = "s")]
309    pub symbol: Ustr,
310    /// Best bid price.
311    #[serde(rename = "b")]
312    pub best_bid_price: String,
313    /// Best bid quantity.
314    #[serde(rename = "B")]
315    pub best_bid_qty: String,
316    /// Best ask price.
317    #[serde(rename = "a")]
318    pub best_ask_price: String,
319    /// Best ask quantity.
320    #[serde(rename = "A")]
321    pub best_ask_qty: String,
322}
323
324/// Kline/candlestick stream message.
325#[derive(Debug, Clone, Deserialize)]
326pub struct BinanceFuturesKlineMsg {
327    /// Event type.
328    #[serde(rename = "e")]
329    pub event_type: String,
330    /// Event time in milliseconds.
331    #[serde(rename = "E")]
332    pub event_time: i64,
333    /// Symbol.
334    #[serde(rename = "s")]
335    pub symbol: Ustr,
336    /// Kline data.
337    #[serde(rename = "k")]
338    pub kline: BinanceFuturesKlineData,
339}
340
341/// Kline data within kline message.
342#[derive(Debug, Clone, Deserialize)]
343pub struct BinanceFuturesKlineData {
344    /// Kline start time.
345    #[serde(rename = "t")]
346    pub start_time: i64,
347    /// Kline close time.
348    #[serde(rename = "T")]
349    pub close_time: i64,
350    /// Symbol.
351    #[serde(rename = "s")]
352    pub symbol: Ustr,
353    /// Kline interval.
354    #[serde(rename = "i")]
355    pub interval: BinanceKlineInterval,
356    /// First trade ID.
357    #[serde(rename = "f")]
358    pub first_trade_id: i64,
359    /// Last trade ID.
360    #[serde(rename = "L")]
361    pub last_trade_id: i64,
362    /// Open price.
363    #[serde(rename = "o")]
364    pub open: String,
365    /// Close price.
366    #[serde(rename = "c")]
367    pub close: String,
368    /// High price.
369    #[serde(rename = "h")]
370    pub high: String,
371    /// Low price.
372    #[serde(rename = "l")]
373    pub low: String,
374    /// Base asset volume.
375    #[serde(rename = "v")]
376    pub volume: String,
377    /// Number of trades.
378    #[serde(rename = "n")]
379    pub num_trades: i64,
380    /// Is this kline closed.
381    #[serde(rename = "x")]
382    pub is_closed: bool,
383    /// Quote asset volume.
384    #[serde(rename = "q")]
385    pub quote_volume: String,
386    /// Taker buy base asset volume.
387    #[serde(rename = "V")]
388    pub taker_buy_volume: String,
389    /// Taker buy quote asset volume.
390    #[serde(rename = "Q")]
391    pub taker_buy_quote_volume: String,
392}
393
394/// Liquidation order stream message.
395#[derive(Debug, Clone, Deserialize)]
396pub struct BinanceFuturesLiquidationMsg {
397    /// Event type.
398    #[serde(rename = "e")]
399    pub event_type: String,
400    /// Event time in milliseconds.
401    #[serde(rename = "E")]
402    pub event_time: i64,
403    /// Order data.
404    #[serde(rename = "o")]
405    pub order: BinanceFuturesLiquidationOrder,
406}
407
408/// Liquidation order details.
409#[derive(Debug, Clone, Deserialize)]
410pub struct BinanceFuturesLiquidationOrder {
411    /// Symbol.
412    #[serde(rename = "s")]
413    pub symbol: Ustr,
414    /// Order side.
415    #[serde(rename = "S")]
416    pub side: BinanceSide,
417    /// Order type.
418    #[serde(rename = "o")]
419    pub order_type: BinanceFuturesOrderType,
420    /// Time in force.
421    #[serde(rename = "f")]
422    pub time_in_force: BinanceTimeInForce,
423    /// Original quantity.
424    #[serde(rename = "q")]
425    pub original_qty: String,
426    /// Price.
427    #[serde(rename = "p")]
428    pub price: String,
429    /// Average price.
430    #[serde(rename = "ap")]
431    pub average_price: String,
432    /// Order status.
433    #[serde(rename = "X")]
434    pub status: BinanceOrderStatus,
435    /// Last filled quantity.
436    #[serde(rename = "l")]
437    pub last_filled_qty: String,
438    /// Accumulated filled quantity.
439    #[serde(rename = "z")]
440    pub accumulated_qty: String,
441    /// Trade time in milliseconds.
442    #[serde(rename = "T")]
443    pub trade_time: i64,
444}
445
446/// 24hr ticker stream message.
447#[derive(Debug, Clone, Deserialize)]
448pub struct BinanceFuturesTickerMsg {
449    /// Event type.
450    #[serde(rename = "e")]
451    pub event_type: String,
452    /// Event time in milliseconds.
453    #[serde(rename = "E")]
454    pub event_time: i64,
455    /// Symbol.
456    #[serde(rename = "s")]
457    pub symbol: Ustr,
458    /// Price change.
459    #[serde(rename = "p")]
460    pub price_change: String,
461    /// Price change percent.
462    #[serde(rename = "P")]
463    pub price_change_percent: String,
464    /// Weighted average price.
465    #[serde(rename = "w")]
466    pub weighted_avg_price: String,
467    /// Last price.
468    #[serde(rename = "c")]
469    pub last_price: String,
470    /// Last quantity.
471    #[serde(rename = "Q")]
472    pub last_qty: String,
473    /// Open price.
474    #[serde(rename = "o")]
475    pub open_price: String,
476    /// High price.
477    #[serde(rename = "h")]
478    pub high_price: String,
479    /// Low price.
480    #[serde(rename = "l")]
481    pub low_price: String,
482    /// Total traded base asset volume.
483    #[serde(rename = "v")]
484    pub volume: String,
485    /// Total traded quote asset volume.
486    #[serde(rename = "q")]
487    pub quote_volume: String,
488    /// Statistics open time in milliseconds.
489    #[serde(rename = "O")]
490    pub open_time: i64,
491    /// Statistics close time in milliseconds.
492    #[serde(rename = "C")]
493    pub close_time: i64,
494    /// First trade ID.
495    #[serde(rename = "F")]
496    pub first_trade_id: i64,
497    /// Last trade ID.
498    #[serde(rename = "L")]
499    pub last_trade_id: i64,
500    /// Total number of trades.
501    #[serde(rename = "n")]
502    pub num_trades: i64,
503}
504
505/// WebSocket subscription request.
506#[derive(Debug, Clone, Serialize)]
507pub struct BinanceFuturesWsSubscribeRequest {
508    /// Request method.
509    pub method: BinanceWsMethod,
510    /// Stream names to subscribe.
511    pub params: Vec<String>,
512    /// Request ID.
513    pub id: u64,
514}
515
516/// WebSocket subscription response.
517#[derive(Debug, Clone, Deserialize)]
518pub struct BinanceFuturesWsSubscribeResponse {
519    /// Response result (null on success).
520    pub result: Option<serde_json::Value>,
521    /// Request ID echoed back.
522    pub id: u64,
523}
524
525/// WebSocket error response.
526#[derive(Debug, Clone, Deserialize)]
527pub struct BinanceFuturesWsErrorResponse {
528    /// Error code.
529    pub code: i64,
530    /// Error message.
531    pub msg: String,
532    /// Request ID if available.
533    pub id: Option<u64>,
534}
535
536/// Account update event from user data stream.
537#[derive(Debug, Clone, Deserialize)]
538pub struct BinanceFuturesAccountUpdateMsg {
539    /// Event type.
540    #[serde(rename = "e")]
541    pub event_type: String,
542    /// Event time in milliseconds.
543    #[serde(rename = "E")]
544    pub event_time: i64,
545    /// Transaction time in milliseconds.
546    #[serde(rename = "T")]
547    pub transaction_time: i64,
548    /// Account update data.
549    #[serde(rename = "a")]
550    pub account: AccountUpdateData,
551}
552
553/// Account update data payload.
554#[derive(Debug, Clone, Deserialize)]
555pub struct AccountUpdateData {
556    /// Reason for account update.
557    #[serde(rename = "m")]
558    pub reason: AccountUpdateReason,
559    /// Balance updates.
560    #[serde(rename = "B", default)]
561    pub balances: Vec<BalanceUpdate>,
562    /// Position updates.
563    #[serde(rename = "P", default)]
564    pub positions: Vec<PositionUpdate>,
565    /// Symbol associated with a funding-fee update, when provided.
566    #[serde(rename = "S", default)]
567    pub symbol: Option<Ustr>,
568}
569
570/// Account update reason type.
571#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
572#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
573pub enum AccountUpdateReason {
574    Deposit,
575    Withdraw,
576    Order,
577    FundingFee,
578    WithdrawReject,
579    Adjustment,
580    InsuranceClear,
581    AdminDeposit,
582    AdminWithdraw,
583    MarginTransfer,
584    MarginTypeChange,
585    AssetTransfer,
586    OptionsPremiumFee,
587    OptionsSettleProfit,
588    AutoExchange,
589    Adl,
590    CoinSwapDeposit,
591    CoinSwapWithdraw,
592    #[serde(other)]
593    Unknown,
594}
595
596/// Balance update within account update.
597#[derive(Debug, Clone, Deserialize)]
598pub struct BalanceUpdate {
599    /// Asset name.
600    #[serde(rename = "a")]
601    pub asset: Ustr,
602    /// Wallet balance.
603    #[serde(rename = "wb", deserialize_with = "deserialize_decimal_from_str")]
604    pub wallet_balance: Decimal,
605    /// Cross wallet balance.
606    #[serde(rename = "cw", deserialize_with = "deserialize_decimal_from_str")]
607    pub cross_wallet_balance: Decimal,
608    /// Balance change (except for PnL and commission).
609    #[serde(
610        rename = "bc",
611        default,
612        deserialize_with = "deserialize_optional_decimal_from_str"
613    )]
614    pub balance_change: Option<Decimal>,
615}
616
617/// Position update within account update.
618#[derive(Debug, Clone, Deserialize)]
619pub struct PositionUpdate {
620    /// Symbol.
621    #[serde(rename = "s")]
622    pub symbol: Ustr,
623    /// Position amount.
624    #[serde(rename = "pa")]
625    pub position_amount: String,
626    /// Entry price.
627    #[serde(rename = "ep")]
628    pub entry_price: String,
629    /// Break-even price.
630    #[serde(rename = "bep", default)]
631    pub break_even_price: Option<String>,
632    /// Accumulated realized (pre-fee).
633    #[serde(rename = "cr")]
634    pub accumulated_realized: String,
635    /// Unrealized PnL.
636    #[serde(rename = "up")]
637    pub unrealized_pnl: String,
638    /// Margin type.
639    #[serde(rename = "mt")]
640    pub margin_type: BinanceMarginType,
641    /// Isolated wallet (if isolated position).
642    #[serde(rename = "iw")]
643    pub isolated_wallet: String,
644    /// Position side.
645    #[serde(rename = "ps")]
646    pub position_side: BinancePositionSide,
647}
648
649/// Order/trade update event from user data stream.
650#[derive(Debug, Clone, Deserialize)]
651pub struct BinanceFuturesOrderUpdateMsg {
652    /// Event type.
653    #[serde(rename = "e")]
654    pub event_type: String,
655    /// Event time in milliseconds.
656    #[serde(rename = "E")]
657    pub event_time: i64,
658    /// Transaction time in milliseconds.
659    #[serde(rename = "T")]
660    pub transaction_time: i64,
661    /// Order data.
662    #[serde(rename = "o")]
663    pub order: OrderUpdateData,
664}
665
666/// Order update data payload.
667#[derive(Debug, Clone, Deserialize)]
668pub struct OrderUpdateData {
669    /// Symbol.
670    #[serde(rename = "s")]
671    pub symbol: Ustr,
672    /// Client order ID.
673    #[serde(rename = "c")]
674    pub client_order_id: String,
675    /// Order side.
676    #[serde(rename = "S")]
677    pub side: BinanceSide,
678    /// Order type.
679    #[serde(rename = "o")]
680    pub order_type: BinanceFuturesOrderType,
681    /// Time in force.
682    #[serde(rename = "f")]
683    pub time_in_force: BinanceTimeInForce,
684    /// Original quantity.
685    #[serde(rename = "q")]
686    pub original_qty: String,
687    /// Original price.
688    #[serde(rename = "p")]
689    pub original_price: String,
690    /// Average price.
691    #[serde(rename = "ap")]
692    pub average_price: String,
693    /// Stop price.
694    #[serde(rename = "sp")]
695    pub stop_price: String,
696    /// Execution type.
697    #[serde(rename = "x")]
698    pub execution_type: BinanceExecutionType,
699    /// Order status.
700    #[serde(rename = "X")]
701    pub order_status: BinanceOrderStatus,
702    /// Order ID.
703    #[serde(rename = "i")]
704    pub order_id: i64,
705    /// Last executed quantity.
706    #[serde(rename = "l")]
707    pub last_filled_qty: String,
708    /// Cumulative filled quantity.
709    #[serde(rename = "z")]
710    pub cumulative_filled_qty: String,
711    /// Last executed price.
712    #[serde(rename = "L")]
713    pub last_filled_price: String,
714    /// Commission asset.
715    #[serde(rename = "N", default)]
716    pub commission_asset: Option<Ustr>,
717    /// Commission amount.
718    #[serde(rename = "n", default)]
719    pub commission: Option<String>,
720    /// Order trade time.
721    #[serde(rename = "T")]
722    pub trade_time: i64,
723    /// Trade ID.
724    #[serde(rename = "t")]
725    pub trade_id: i64,
726    /// Bids notional.
727    #[serde(rename = "b", default)]
728    pub bids_notional: Option<String>,
729    /// Asks notional.
730    #[serde(rename = "a", default)]
731    pub asks_notional: Option<String>,
732    /// Is maker.
733    #[serde(rename = "m")]
734    pub is_maker: bool,
735    /// Is reduce only.
736    #[serde(rename = "R")]
737    pub is_reduce_only: bool,
738    /// Working type.
739    #[serde(rename = "wt")]
740    pub working_type: BinanceWorkingType,
741    /// Original order type.
742    #[serde(rename = "ot")]
743    pub original_order_type: BinanceFuturesOrderType,
744    /// Position side.
745    #[serde(rename = "ps")]
746    pub position_side: BinancePositionSide,
747    /// Close all (for stop orders).
748    #[serde(rename = "cp", default)]
749    pub close_position: Option<bool>,
750    /// Activation price (for trailing stop).
751    #[serde(rename = "AP", default)]
752    pub activation_price: Option<String>,
753    /// Callback rate (for trailing stop).
754    #[serde(rename = "cr", default)]
755    pub callback_rate: Option<String>,
756    /// Price protection.
757    #[serde(rename = "pP", default)]
758    pub price_protect: Option<bool>,
759    /// Realized profit.
760    #[serde(rename = "rp")]
761    pub realized_profit: String,
762    /// Self-trade prevention mode.
763    #[serde(rename = "V", default)]
764    pub stp_mode: Option<BinanceSelfTradePreventionMode>,
765    /// Price match mode.
766    #[serde(rename = "pm", default)]
767    pub price_match: Option<BinancePriceMatch>,
768    /// Good till date for GTD orders.
769    #[serde(rename = "gtd", default)]
770    pub good_till_date: Option<i64>,
771}
772
773impl OrderUpdateData {
774    /// Returns true if this is a liquidation order.
775    #[must_use]
776    pub fn is_liquidation(&self) -> bool {
777        self.client_order_id.starts_with("autoclose-")
778    }
779
780    /// Returns true if this is an ADL (Auto-Deleveraging) order.
781    #[must_use]
782    pub fn is_adl(&self) -> bool {
783        self.client_order_id.starts_with("adl_autoclose")
784    }
785
786    /// Returns true if this is a settlement order.
787    ///
788    /// USDT-margined futures use `settlement_autoclose-` for funding/margin
789    /// settlement; coin-margined delivery futures use `delivery_autoclose-`
790    /// when an expiring contract auto-closes.
791    #[must_use]
792    pub fn is_settlement(&self) -> bool {
793        self.client_order_id.starts_with("settlement_autoclose-")
794            || self.client_order_id.starts_with("delivery_autoclose-")
795    }
796
797    /// Returns true if this is an exchange-generated order.
798    #[must_use]
799    pub fn is_exchange_generated(&self) -> bool {
800        self.is_liquidation() || self.is_adl() || self.is_settlement()
801    }
802}
803
804/// Trade Lite event from user data stream.
805///
806/// Binance pushes `TRADE_LITE` alongside `ORDER_TRADE_UPDATE` as a lower-latency
807/// subset containing only the fields needed to recognize a fill. Clients that
808/// prioritize latency can opt to act on `TRADE_LITE` and dedup the matching
809/// fill portion of the full `ORDER_TRADE_UPDATE` event.
810#[derive(Debug, Clone, Deserialize)]
811pub struct BinanceFuturesTradeLiteMsg {
812    /// Event type.
813    #[serde(rename = "e")]
814    pub event_type: String,
815    /// Event time in milliseconds.
816    #[serde(rename = "E")]
817    pub event_time: i64,
818    /// Transaction time in milliseconds.
819    #[serde(rename = "T")]
820    pub transaction_time: i64,
821    /// Symbol.
822    #[serde(rename = "s")]
823    pub symbol: Ustr,
824    /// Client order ID.
825    #[serde(rename = "c")]
826    pub client_order_id: String,
827    /// Order side.
828    #[serde(rename = "S")]
829    pub side: BinanceSide,
830    /// Original quantity.
831    #[serde(rename = "q")]
832    pub original_qty: String,
833    /// Original price.
834    #[serde(rename = "p")]
835    pub original_price: String,
836    /// Order ID.
837    #[serde(rename = "i")]
838    pub order_id: i64,
839    /// Last executed quantity.
840    #[serde(rename = "l")]
841    pub last_filled_qty: String,
842    /// Last executed price.
843    #[serde(rename = "L")]
844    pub last_filled_price: String,
845    /// Trade ID.
846    #[serde(rename = "t")]
847    pub trade_id: i64,
848    /// Is maker.
849    #[serde(rename = "m")]
850    pub is_maker: bool,
851}
852
853/// Execution type for order updates.
854#[derive(Debug, Clone, Copy, Deserialize, PartialEq, Eq)]
855#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
856pub enum BinanceExecutionType {
857    /// New order accepted.
858    New,
859    /// Order canceled.
860    Canceled,
861    /// Calculated (liquidation, ADL).
862    Calculated,
863    /// Order expired.
864    Expired,
865    /// Trade (partial or full fill).
866    Trade,
867    /// Amendment (order modified).
868    Amendment,
869    /// Unknown or undocumented execution type.
870    #[serde(other)]
871    Unknown,
872}
873
874/// Margin call event from user data stream.
875#[derive(Debug, Clone, Deserialize)]
876pub struct BinanceFuturesMarginCallMsg {
877    /// Event type.
878    #[serde(rename = "e")]
879    pub event_type: String,
880    /// Event time in milliseconds.
881    #[serde(rename = "E")]
882    pub event_time: i64,
883    /// Cross wallet balance.
884    #[serde(rename = "cw")]
885    pub cross_wallet_balance: String,
886    /// Positions at risk.
887    #[serde(rename = "p")]
888    pub positions: Vec<MarginCallPosition>,
889}
890
891/// Position at risk in margin call.
892#[derive(Debug, Clone, Deserialize)]
893pub struct MarginCallPosition {
894    /// Symbol.
895    #[serde(rename = "s")]
896    pub symbol: Ustr,
897    /// Position side.
898    #[serde(rename = "ps")]
899    pub position_side: BinancePositionSide,
900    /// Position amount.
901    #[serde(rename = "pa")]
902    pub position_amount: String,
903    /// Margin type.
904    #[serde(rename = "mt")]
905    pub margin_type: BinanceMarginType,
906    /// Isolated wallet (if any).
907    #[serde(rename = "iw")]
908    pub isolated_wallet: String,
909    /// Mark price.
910    #[serde(rename = "mp")]
911    pub mark_price: String,
912    /// Unrealized PnL.
913    #[serde(rename = "up")]
914    pub unrealized_pnl: String,
915    /// Maintenance margin required.
916    #[serde(rename = "mm")]
917    pub maintenance_margin: String,
918}
919
920/// Account configuration update event.
921#[derive(Debug, Clone, Deserialize)]
922pub struct BinanceFuturesAccountConfigMsg {
923    /// Event type.
924    #[serde(rename = "e")]
925    pub event_type: String,
926    /// Event time in milliseconds.
927    #[serde(rename = "E")]
928    pub event_time: i64,
929    /// Transaction time in milliseconds.
930    #[serde(rename = "T")]
931    pub transaction_time: i64,
932    /// Leverage configuration data.
933    #[serde(rename = "ac", default)]
934    pub leverage_config: Option<LeverageConfig>,
935    /// Asset index price data (for multi-assets mode).
936    #[serde(rename = "ai", default)]
937    pub asset_index: Option<AssetIndexConfig>,
938}
939
940/// Leverage configuration change.
941#[derive(Debug, Clone, Deserialize)]
942pub struct LeverageConfig {
943    /// Symbol.
944    #[serde(rename = "s")]
945    pub symbol: Ustr,
946    /// New leverage value.
947    #[serde(rename = "l")]
948    pub leverage: u32,
949}
950
951/// Asset index configuration (multi-assets mode).
952#[derive(Debug, Clone, Deserialize)]
953pub struct AssetIndexConfig {
954    /// Symbol.
955    #[serde(rename = "s")]
956    pub symbol: Ustr,
957}
958
959/// Algo order update event from user data stream (Binance Futures Algo Service).
960///
961/// This event is triggered for conditional orders (STOP_MARKET, STOP_LIMIT,
962/// TAKE_PROFIT, TAKE_PROFIT_MARKET, TRAILING_STOP_MARKET) managed by the
963/// Algo Service.
964///
965/// # References
966///
967/// - <https://developers.binance.com/docs/derivatives/usds-margined-futures/user-data-streams/Event-Algo-Order-Update>
968#[derive(Debug, Clone, Deserialize)]
969pub struct BinanceFuturesAlgoUpdateMsg {
970    /// Event type ("ALGO_UPDATE").
971    #[serde(rename = "e")]
972    pub event_type: String,
973    /// Event time in milliseconds.
974    #[serde(rename = "E")]
975    pub event_time: i64,
976    /// Transaction time in milliseconds.
977    #[serde(rename = "T")]
978    pub transaction_time: i64,
979    /// Algo order data.
980    #[serde(rename = "o", alias = "ao")]
981    pub algo_order: AlgoOrderUpdateData,
982}
983
984/// Algo order update data payload.
985#[derive(Debug, Clone, Deserialize)]
986pub struct AlgoOrderUpdateData {
987    /// Client algo order ID.
988    #[serde(rename = "caid")]
989    pub client_algo_id: String,
990    /// Algo order ID.
991    #[serde(rename = "aid")]
992    pub algo_id: i64,
993    /// Algo type (currently only `Conditional`).
994    #[serde(rename = "at")]
995    pub algo_type: BinanceAlgoType,
996    /// Order type (STOP_MARKET, STOP, TAKE_PROFIT, TAKE_PROFIT_MARKET, TRAILING_STOP_MARKET).
997    #[serde(rename = "o")]
998    pub order_type: BinanceFuturesOrderType,
999    /// Symbol.
1000    #[serde(rename = "s")]
1001    pub symbol: Ustr,
1002    /// Order side.
1003    #[serde(rename = "S")]
1004    pub side: BinanceSide,
1005    /// Position side.
1006    #[serde(rename = "ps")]
1007    pub position_side: BinancePositionSide,
1008    /// Time in force.
1009    #[serde(rename = "f")]
1010    pub time_in_force: BinanceTimeInForce,
1011    /// Order quantity.
1012    #[serde(rename = "q")]
1013    pub quantity: String,
1014    /// Algo order status (NEW, TRIGGERING, TRIGGERED, FINISHED, CANCELED, EXPIRED, REJECTED).
1015    #[serde(rename = "X")]
1016    pub algo_status: BinanceAlgoStatus,
1017    /// Trigger price.
1018    #[serde(rename = "tp")]
1019    pub trigger_price: String,
1020    /// Limit price.
1021    #[serde(rename = "p")]
1022    pub price: String,
1023    /// Working type for trigger price calculation.
1024    #[serde(rename = "wt")]
1025    pub working_type: BinanceWorkingType,
1026    /// Price match mode.
1027    #[serde(rename = "pm", default)]
1028    pub price_match: Option<BinancePriceMatch>,
1029    /// Close position flag.
1030    #[serde(rename = "cp", default)]
1031    pub close_position: Option<bool>,
1032    /// Price protection flag.
1033    #[serde(rename = "pP", default)]
1034    pub price_protect: Option<bool>,
1035    /// Reduce-only flag.
1036    #[serde(rename = "R", default)]
1037    pub reduce_only: Option<bool>,
1038    /// Trigger time in milliseconds.
1039    #[serde(rename = "tt", default)]
1040    pub trigger_time: Option<i64>,
1041    /// Good till date in milliseconds.
1042    #[serde(rename = "gtd", default)]
1043    pub good_till_date: Option<i64>,
1044    /// Order ID in matching engine (populated when triggered).
1045    #[serde(rename = "ai", default)]
1046    pub actual_order_id: Option<String>,
1047    /// Average fill price in matching engine (populated when triggered).
1048    #[serde(rename = "ap", default)]
1049    pub avg_price: Option<String>,
1050    /// Executed quantity in matching engine (populated when triggered).
1051    #[serde(rename = "aq", default)]
1052    pub executed_qty: Option<String>,
1053    /// Actual order type in matching engine (populated when triggered).
1054    #[serde(rename = "act", default)]
1055    pub actual_order_type: Option<String>,
1056    /// Callback rate for trailing stop (0.1 to 10, where 1 = 1%).
1057    #[serde(rename = "cr", default)]
1058    pub callback_rate: Option<String>,
1059    /// Self-trade prevention mode.
1060    #[serde(rename = "V", default)]
1061    pub stp_mode: Option<BinanceSelfTradePreventionMode>,
1062}
1063
1064/// Listen key expired event.
1065#[derive(Debug, Clone, Deserialize)]
1066pub struct BinanceFuturesListenKeyExpiredMsg {
1067    /// Event type.
1068    #[serde(rename = "e")]
1069    pub event_type: String,
1070    /// Event time in milliseconds.
1071    #[serde(rename = "E")]
1072    pub event_time: i64,
1073}
1074
1075#[cfg(test)]
1076mod tests {
1077    use rstest::rstest;
1078    use rust_decimal_macros::dec;
1079
1080    use super::*;
1081
1082    #[rstest]
1083    #[case(
1084        include_str!("../../../../test_data/futures/user_data_json/account_update_funding_fee_usdm.json"),
1085        "BTCUSDT",
1086        "USDT",
1087        [1786060800001, 1786060800000],
1088        [dec!(1024.12345678), dec!(1010.87654321), dec!(-0.01234567)]
1089    )]
1090    #[case(
1091        include_str!("../../../../test_data/futures/user_data_json/account_update_funding_fee_coinm.json"),
1092        "BTCUSD_PERP",
1093        "BTC",
1094        [1786089600002, 1786089600000],
1095        [dec!(1.23456789), dec!(1.12345678), dec!(0.00001234)]
1096    )]
1097    fn test_account_update_funding_fee_symbol(
1098        #[case] payload: &str,
1099        #[case] symbol: &str,
1100        #[case] asset: &str,
1101        #[case] times: [i64; 2],
1102        #[case] balances: [Decimal; 3],
1103    ) {
1104        let msg: BinanceFuturesAccountUpdateMsg = serde_json::from_str(payload).unwrap();
1105
1106        assert_eq!(msg.event_type, "ACCOUNT_UPDATE");
1107        assert_eq!(msg.event_time, times[0]);
1108        assert_eq!(msg.transaction_time, times[1]);
1109        assert_eq!(msg.account.reason, AccountUpdateReason::FundingFee);
1110        assert_eq!(msg.account.symbol, Some(Ustr::from(symbol)));
1111        assert_eq!(msg.account.balances.len(), 1);
1112        assert_eq!(msg.account.positions.len(), 0);
1113        let balance = &msg.account.balances[0];
1114        assert_eq!(balance.asset, Ustr::from(asset));
1115        assert_eq!(balance.wallet_balance, balances[0]);
1116        assert_eq!(balance.cross_wallet_balance, balances[1]);
1117        assert_eq!(balance.balance_change, Some(balances[2]));
1118    }
1119
1120    #[rstest]
1121    #[case(include_str!("../../../../test_data/futures/user_data_json/account_update.json"), 1, 3)]
1122    #[case(include_str!("../../../../test_data/futures/user_data_json/account_update_bnfcr.json"), 1, 0)]
1123    fn test_account_update_without_symbol(
1124        #[case] payload: &str,
1125        #[case] balances: usize,
1126        #[case] positions: usize,
1127    ) {
1128        let msg: BinanceFuturesAccountUpdateMsg = serde_json::from_str(payload).unwrap();
1129
1130        assert_eq!(msg.account.reason, AccountUpdateReason::Order);
1131        assert_eq!(msg.account.symbol, None);
1132        assert_eq!(msg.account.balances.len(), balances);
1133        assert_eq!(msg.account.positions.len(), positions);
1134    }
1135
1136    #[rstest]
1137    #[case(include_str!("../../../../test_data/futures/user_data_json/account_update_funding_fee_usdm.json"))]
1138    #[case(include_str!("../../../../test_data/futures/user_data_json/account_update_funding_fee_coinm.json"))]
1139    fn test_account_update_funding_fee_without_symbol(#[case] payload: &str) {
1140        let mut payload: serde_json::Value = serde_json::from_str(payload).unwrap();
1141        payload["a"].as_object_mut().unwrap().remove("S");
1142
1143        let msg: BinanceFuturesAccountUpdateMsg = serde_json::from_value(payload).unwrap();
1144
1145        assert_eq!(msg.account.reason, AccountUpdateReason::FundingFee);
1146        assert_eq!(msg.account.symbol, None);
1147    }
1148
1149    #[rstest]
1150    fn test_account_update_reason_adl_deserializes() {
1151        let value: AccountUpdateReason = serde_json::from_str("\"ADL\"").unwrap();
1152        assert_eq!(value, AccountUpdateReason::Adl);
1153    }
1154
1155    #[rstest]
1156    fn test_account_update_reason_unknown_fallback() {
1157        let value: AccountUpdateReason = serde_json::from_str("\"SOMETHING_NEW\"").unwrap();
1158        assert_eq!(value, AccountUpdateReason::Unknown);
1159    }
1160}