Skip to main content

nautilus_binance/futures/
execution.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//! Live execution client implementation for the Binance Futures adapter.
17
18use std::{
19    future::Future,
20    sync::{
21        Arc,
22        atomic::{AtomicBool, Ordering},
23    },
24    time::Duration,
25};
26
27use ahash::AHashSet;
28use anyhow::Context;
29use async_trait::async_trait;
30use dashmap::DashMap;
31use indexmap::IndexMap;
32use nautilus_common::{
33    clients::ExecutionClient,
34    enums::LogLevel,
35    live::runner::get_exec_event_sender,
36    messages::execution::{
37        BatchCancelOrders, CancelAllOrders, CancelOrder, GenerateFillReports,
38        GenerateFillReportsBuilder, GenerateOrderStatusReport, GenerateOrderStatusReports,
39        GeneratePositionStatusReports, GeneratePositionStatusReportsBuilder, ModifyOrder,
40        PARAMS_CLOSE_POSITION, QueryAccount, QueryOrder, SubmitOrder, SubmitOrderList,
41    },
42};
43use nautilus_core::{
44    AtomicSet, DurationNanos, Params, UUID4, UnixNanos,
45    datetime::{NANOSECONDS_IN_MILLISECOND, NANOSECONDS_IN_SECOND},
46    string::secret::SecretString,
47    time::{AtomicTime, get_atomic_clock_realtime},
48};
49use nautilus_live::{
50    ExecutionClientCore, ExecutionEventEmitter, SocketControlFactory,
51    execution::failure::CommandFailure,
52    task::{TaskGroup, TaskGroupGuard, TaskJoinOutcome, TaskShutdownError, TaskSlot, finish_task},
53};
54use nautilus_model::{
55    accounts::AccountAny,
56    enums::{
57        AccountType, OmsType, OrderStatus, OrderType, PositionSide, TimeInForce,
58        TrailingOffsetType, TriggerType,
59    },
60    events::{
61        AccountState, OrderCancelDenied, OrderCancelRejected, OrderCanceled, OrderDeniedReason,
62        OrderEventAny, OrderModifyDenied, OrderModifyRejected, OrderRejected, OrderUpdated,
63    },
64    identifiers::{
65        AccountId, ClientId, ClientOrderId, InstrumentId, PositionId, Venue, VenueOrderId,
66    },
67    instruments::{Instrument, InstrumentAny},
68    orders::{Order, OrderAny},
69    reports::{ExecutionMassStatus, FillReport, OrderStatusReport, PositionStatusReport},
70    types::{AccountBalance, Currency, MarginBalance, Money, Quantity},
71};
72use parking_lot::{Mutex, RwLock};
73use rust_decimal::Decimal;
74use tokio_util::sync::CancellationToken;
75
76use super::{
77    http::{
78        BinanceFuturesHttpError,
79        client::{
80            BinanceFuturesAlgoOrderQueryResult, BinanceFuturesHttpClient, BinanceFuturesInstrument,
81            is_algo_order_type,
82        },
83        models::{BatchOrderResult, BinanceFuturesAlgoOrder, BinancePositionRisk},
84        query::{
85            BatchCancelItem, BinanceAllOrdersParamsBuilder, BinanceOpenOrdersParamsBuilder,
86            BinanceOrderQueryParamsBuilder, BinancePositionRiskParamsBuilder,
87            BinanceSetLeverageParams, BinanceSetMarginTypeParams, BinanceUserTradesParamsBuilder,
88        },
89    },
90    websocket::{
91        streams::{
92            client::BinanceFuturesWebSocketClient,
93            dispatch::{
94                DispatchCtx, dispatch_user_stream_message, make_venue_position_id,
95                run_user_stream_dispatch, with_venue_position_id,
96            },
97            recovery::{
98                RecoveryCtx, WsBuildParams, build_and_connect_user_stream, run_recovery_driver,
99            },
100        },
101        trading::{client::BinanceFuturesWsTradingClient, dispatch::dispatch_ws_trading_message},
102    },
103};
104use crate::{
105    common::{
106        consts::{
107            BINANCE_FUTURES_DUAL_SIDE_SYNC_REJECT_CODE, BINANCE_FUTURES_USD_WS_API_TESTNET_URL,
108            BINANCE_FUTURES_USD_WS_API_URL, BINANCE_GTX_ORDER_REJECT_CODE,
109            BINANCE_NAUTILUS_FUTURES_BROKER_ID, BINANCE_VENUE, BINANCE_WS_HEARTBEAT_SECS,
110        },
111        credential::resolve_credentials,
112        dispatch::{OrderIdentity, PendingOperation, PendingRequest, WsDispatchState},
113        encoder::{encode_broker_id, legacy_client_order_id},
114        enums::{
115            BinanceEnvironment, BinanceFuturesOrderType, BinancePositionSide, BinancePriceMatch,
116            BinanceProductType, BinanceSide, BinanceTimeInForce, BinanceWorkingType,
117        },
118        failure::{classify_futures_batch_failure, classify_futures_http_failure, sanitize_reason},
119        instruments::BinanceInstrumentSelector,
120        symbol::{format_binance_symbol, format_instrument_id},
121        urls::{get_usdm_ws_route_base_url, get_ws_private_base_url},
122    },
123    config::BinanceExecutionClientConfig,
124    futures::{
125        conversions::{
126            determine_position_side, normalize_futures_asset, reduce_only_param,
127            trailing_offset_to_callback_rate, trailing_offset_to_callback_rate_string,
128        },
129        http::{
130            client::order_type_to_binance_futures,
131            models::BinanceFuturesAccountInfo,
132            query::{
133                BatchOrderItem, BinanceCancelOrderParamsBuilder, BinanceModifyOrderParamsBuilder,
134                BinanceNewOrderParams,
135            },
136        },
137    },
138};
139
140/// Listen key keepalive interval (30 minutes).
141const LISTEN_KEY_KEEPALIVE_SECS: u64 = 30 * 60;
142
143/// Consecutive keepalive failures before a listenKey rotation is triggered.
144const MAX_KEEPALIVE_FAILURES: u32 = 1;
145
146const USER_TRADES_MAX_INTERVAL_MS: i64 = 7 * 24 * 60 * 60 * 1_000;
147
148const USER_TRADES_PAGE_LIMIT: u32 = 1_000;
149
150// Binance does not define whether its three-month retention is calendar-based or fixed-duration
151// An 88-day interval leaves at least one day inside either interpretation
152// https://developers.binance.com/en/docs/products/derivatives-trading-usds-futures/change-log
153const USER_TRADES_COMPLETE_INTERVAL: DurationNanos = DurationNanos::from_days(88);
154
155// Keep half the one-day retention safety margin when a command waits before execution
156const USER_TRADES_MAX_TS_INIT_AGE: DurationNanos = DurationNanos::from_hours(12);
157
158const BINANCE_GTD_MIN_LEAD_SECS: u64 = 600;
159
160const BINANCE_GTD_MAX_MILLIS: u64 = 253_402_300_799_000;
161
162/// Query parameter declaring that the command's venue order ID is a Binance Algo Service
163/// `algoId`, rather than a regular matching-engine `orderId` or triggered `actualOrderId`.
164pub const BINANCE_VENUE_ORDER_ID_IS_ALGO_ID_PARAM: &str = "venue_order_id_is_algo_id";
165
166/// Live execution client for Binance Futures trading.
167///
168/// Implements the [`ExecutionClient`] trait for order management on Binance
169/// USD-M and COIN-M Futures markets. Uses HTTP API for order operations and
170/// WebSocket for real-time order updates via user data stream.
171///
172/// Uses a two-tier architecture with an execution handler that maintains
173/// pending order maps for correlating WebSocket updates with order context.
174#[derive(Debug)]
175pub struct BinanceFuturesExecutionClient {
176    core: ExecutionClientCore,
177    clock: &'static AtomicTime,
178    config: BinanceExecutionClientConfig,
179    emitter: ExecutionEventEmitter,
180    dispatch_state: Arc<WsDispatchState>,
181    product_type: BinanceProductType,
182    http_client: BinanceFuturesHttpClient,
183    ws_client: Arc<Mutex<Option<BinanceFuturesWebSocketClient>>>,
184    socket_factory: SocketControlFactory,
185    ws_trading_client: Option<BinanceFuturesWsTradingClient>,
186    listen_key: Arc<RwLock<Option<SecretString>>>,
187    recovery_listen_key: Arc<RwLock<Option<SecretString>>>,
188    cancellation_token: CancellationToken,
189    triggered_algo_order_ids: Arc<AtomicSet<ClientOrderId>>,
190    ws_task: Arc<tokio::sync::Mutex<TaskSlot<()>>>,
191    recovery_lock: Arc<tokio::sync::Mutex<()>>,
192    recovery_tx: Option<tokio::sync::mpsc::UnboundedSender<()>>,
193    session_tasks: TaskGroup,
194    pending_tasks: TaskGroup,
195    is_hedge_mode: AtomicBool,
196    shutdown_errors: Vec<String>,
197}
198
199impl BinanceFuturesExecutionClient {
200    /// Creates a new [`BinanceFuturesExecutionClient`].
201    ///
202    /// # Errors
203    ///
204    /// Returns an error if the HTTP client fails to initialize, credentials are
205    /// missing, or the product type is not a futures type (UsdM or CoinM).
206    pub fn new(
207        core: ExecutionClientCore,
208        config: BinanceExecutionClientConfig,
209    ) -> anyhow::Result<Self> {
210        config.validate()?;
211        let product_type = config.product_type;
212        match product_type {
213            BinanceProductType::UsdM | BinanceProductType::CoinM => {}
214            _ => {
215                anyhow::bail!(
216                    "BinanceFuturesExecutionClient requires UsdM or CoinM product type, was {product_type:?}"
217                );
218            }
219        }
220
221        let (api_key, api_secret) = resolve_credentials(
222            config
223                .api_key
224                .as_ref()
225                .map(|value| value.expose_secret().to_owned()),
226            config
227                .api_secret
228                .as_ref()
229                .map(|value| value.expose_secret().to_owned()),
230            config.environment,
231            product_type,
232        )?;
233        let proxy_url = config
234            .proxy_url
235            .as_ref()
236            .map(|value| value.expose_secret().to_owned());
237
238        let clock = get_atomic_clock_realtime();
239        let socket_factory = SocketControlFactory::new(core.client_id, Some(*BINANCE_VENUE));
240
241        let http_client = BinanceFuturesHttpClient::new(
242            product_type,
243            config.environment,
244            clock,
245            Some(api_key.clone()),
246            Some(api_secret.clone()),
247            config.base_url_http.clone(),
248            Some(config.recv_window_ms),
249            None, // timeout_secs
250            proxy_url.clone(),
251            config.treat_expired_as_canceled,
252        )
253        .context("failed to construct Binance Futures HTTP client")?
254        .with_retry_config(config.retry_config());
255
256        let ws_trading_client = if config.use_ws_trading && product_type == BinanceProductType::UsdM
257        {
258            let ws_trading_url =
259                config
260                    .base_url_ws_trading
261                    .clone()
262                    .or_else(|| match config.environment {
263                        BinanceEnvironment::Testnet | BinanceEnvironment::Demo => {
264                            Some(BINANCE_FUTURES_USD_WS_API_TESTNET_URL.to_string())
265                        }
266                        _ => Some(BINANCE_FUTURES_USD_WS_API_URL.to_string()),
267                    });
268
269            Some(
270                BinanceFuturesWsTradingClient::new(
271                    ws_trading_url,
272                    api_key,
273                    api_secret,
274                    Some(BINANCE_WS_HEARTBEAT_SECS),
275                    config.transport_backend,
276                )
277                .with_proxy(proxy_url)
278                .with_recv_window(Some(config.recv_window_ms))
279                .with_socket_control(socket_factory.control("binance-futures-trading")),
280            )
281        } else {
282            None
283        };
284
285        let emitter = ExecutionEventEmitter::new(
286            clock,
287            core.trader_id,
288            core.account_id,
289            core.account_type,
290            core.base_currency,
291        );
292
293        let session_tasks = TaskGroup::new();
294        let pending_tasks = TaskGroup::new();
295
296        Ok(Self {
297            core,
298            clock,
299            config,
300            emitter,
301            dispatch_state: Arc::new(WsDispatchState::default()),
302            product_type,
303            http_client,
304            ws_client: Arc::new(Mutex::new(None)),
305            socket_factory,
306            ws_trading_client,
307            listen_key: Arc::new(RwLock::new(None)),
308            recovery_listen_key: Arc::new(RwLock::new(None)),
309            cancellation_token: CancellationToken::new(),
310            triggered_algo_order_ids: Arc::new(AtomicSet::new()),
311            ws_task: Arc::new(tokio::sync::Mutex::new(TaskSlot::new())),
312            recovery_lock: Arc::new(tokio::sync::Mutex::new(())),
313            recovery_tx: None,
314            session_tasks,
315            pending_tasks,
316            is_hedge_mode: AtomicBool::new(false),
317            shutdown_errors: Vec::new(),
318        })
319    }
320
321    fn restore_active_orders(&self) -> anyhow::Result<()> {
322        for order in crate::common::execution::active_orders(&self.core) {
323            let Some(instrument) = self
324                .http_client
325                .instrument_reconciliation(&order.instrument_id())
326            else {
327                continue;
328            };
329
330            let (_, venue_position_id) = resolve_order_position_identity(
331                self.is_hedge_mode(),
332                self.config.use_position_ids,
333                &order,
334            )
335            .map_err(|e| {
336                anyhow::anyhow!(
337                    "Failed to restore Binance Futures order {}: {e}",
338                    order.client_order_id()
339                )
340            })?;
341
342            self.dispatch_state.restore_order(
343                &order,
344                venue_position_id,
345                instrument.price_precision(),
346            );
347        }
348
349        Ok(())
350    }
351
352    /// Returns whether the account is in hedge mode (dual side position).
353    #[must_use]
354    pub fn is_hedge_mode(&self) -> bool {
355        self.is_hedge_mode.load(Ordering::Acquire)
356    }
357
358    fn resolve_algo_lookup(
359        &self,
360        client_order_id: Option<ClientOrderId>,
361        params: Option<&Params>,
362    ) -> BinanceFuturesAlgoLookup {
363        if params.and_then(|p| p.get_bool(BINANCE_VENUE_ORDER_ID_IS_ALGO_ID_PARAM)) == Some(true) {
364            return BinanceFuturesAlgoLookup::AlgoId;
365        }
366
367        let Some(client_order_id) = client_order_id else {
368            return BinanceFuturesAlgoLookup::ClientAlgoId;
369        };
370        let cache = self.core.cache();
371        match cache.order(&client_order_id) {
372            Some(order) if !is_algo_order_type(order.order_type()) => {
373                BinanceFuturesAlgoLookup::Skip
374            }
375            _ => BinanceFuturesAlgoLookup::ClientAlgoId,
376        }
377    }
378
379    /// Returns a clone of the HTTP client's instruments cache Arc.
380    #[doc(hidden)]
381    #[must_use]
382    pub fn instruments_cache(&self) -> Arc<DashMap<ustr::Ustr, BinanceFuturesInstrument>> {
383        self.http_client.instruments_cache()
384    }
385
386    /// Converts Binance futures account info to Nautilus account state.
387    fn create_account_state(&self, account_info: &BinanceFuturesAccountInfo) -> AccountState {
388        Self::create_account_state_from(
389            account_info,
390            self.core.account_id,
391            self.core.account_type,
392            self.config.bnfcr_currency,
393            self.clock,
394        )
395    }
396
397    fn create_account_state_from(
398        account_info: &BinanceFuturesAccountInfo,
399        account_id: AccountId,
400        account_type: AccountType,
401        bnfcr_currency: Currency,
402        clock: &'static AtomicTime,
403    ) -> AccountState {
404        let ts_now = clock.get_time_ns();
405
406        let balances: Vec<AccountBalance> = account_info
407            .assets
408            .iter()
409            .filter_map(|b| {
410                if b.wallet_balance.is_zero() {
411                    return None;
412                }
413
414                let currency = normalize_futures_asset(b.asset, bnfcr_currency);
415                AccountBalance::from_total_and_free(b.wallet_balance, b.available_balance, currency)
416                    .ok()
417            })
418            .collect();
419
420        // Emit account-wide (cross-margin) margin balances per collateral asset.
421        // Binance reports per-asset `initialMargin` / `maintMargin` which covers both
422        // USDT-M (typically USDT, or USDT+BNB under multi-assets mode) and COIN-M
423        // (one entry per base coin, e.g. BTC / ETH).
424        let mut margins: Vec<MarginBalance> = Vec::new();
425
426        for asset in &account_info.assets {
427            let initial_dec = asset.initial_margin.unwrap_or_default();
428            let maint_dec = asset.maint_margin.unwrap_or_default();
429
430            if initial_dec.is_zero() && maint_dec.is_zero() {
431                continue;
432            }
433
434            let currency = normalize_futures_asset(asset.asset, bnfcr_currency);
435            let initial = Money::from_decimal(initial_dec, currency)
436                .unwrap_or_else(|_| Money::zero(currency));
437            let maintenance =
438                Money::from_decimal(maint_dec, currency).unwrap_or_else(|_| Money::zero(currency));
439            margins.push(MarginBalance::new(initial, maintenance, None));
440        }
441
442        let mut info = IndexMap::new();
443
444        let mut push_decimal = |key: &str, val: Option<Decimal>| {
445            if let Some(decimal) = val {
446                info.insert(
447                    key.to_string(),
448                    serde_json::Value::from(decimal.to_string()),
449                );
450            }
451        };
452        push_decimal("total_wallet_balance", account_info.total_wallet_balance);
453        push_decimal("total_margin_balance", account_info.total_margin_balance);
454        push_decimal("total_initial_margin", account_info.total_initial_margin);
455        push_decimal("total_maint_margin", account_info.total_maint_margin);
456        push_decimal(
457            "total_unrealized_profit",
458            account_info.total_unrealized_profit,
459        );
460        push_decimal(
461            "total_cross_wallet_balance",
462            account_info.total_cross_wallet_balance,
463        );
464        push_decimal("total_cross_unpnl", account_info.total_cross_un_pnl);
465        push_decimal("available_balance", account_info.available_balance);
466        push_decimal("max_withdraw_amount", account_info.max_withdraw_amount);
467
468        let info = if info.is_empty() {
469            None
470        } else {
471            Some(Params::new(info))
472        };
473
474        AccountState::new(
475            account_id,
476            account_type,
477            balances,
478            margins,
479            true, // reported
480            UUID4::new(),
481            ts_now,
482            ts_now,
483            None, // base currency
484        )
485        .with_info(info)
486    }
487
488    async fn refresh_account_state(&self) -> anyhow::Result<AccountState> {
489        let account_info = match self.http_client.query_account().await {
490            Ok(info) => info,
491            Err(e) => anyhow::bail!("Binance Futures account state request failed: {e}"),
492        };
493
494        Ok(self.create_account_state(&account_info))
495    }
496
497    fn update_account_state(&self) {
498        let http_client = self.http_client.clone();
499        let account_id = self.core.account_id;
500        let account_type = self.core.account_type;
501        let bnfcr_currency = self.config.bnfcr_currency;
502        let emitter = self.emitter.clone();
503        let clock = self.clock;
504
505        self.spawn_task("query_account", async move {
506            let account_info = http_client
507                .query_account()
508                .await
509                .context("Binance Futures account state request failed")?;
510            let account_state = Self::create_account_state_from(
511                &account_info,
512                account_id,
513                account_type,
514                bnfcr_currency,
515                clock,
516            );
517            let ts_now = clock.get_time_ns();
518            emitter.emit_account_state(
519                account_state.balances.clone(),
520                account_state.margins.clone(),
521                account_state.is_reported,
522                ts_now,
523                account_state.info,
524            );
525            Ok(())
526        });
527    }
528
529    async fn init_hedge_mode(&self) -> anyhow::Result<bool> {
530        let response = self.http_client.query_hedge_mode().await?;
531        Ok(response.dual_side_position)
532    }
533
534    /// Returns whether the WS trading client is connected and active.
535    fn ws_trading_active(&self) -> bool {
536        self.ws_trading_client
537            .as_ref()
538            .is_some_and(|c| c.is_active())
539    }
540
541    fn submit_order_internal(
542        &self,
543        cmd: &SubmitOrder,
544        lifetime: FuturesOrderLifetime,
545        position_side: Option<BinancePositionSide>,
546        venue_position_id: Option<PositionId>,
547    ) -> anyhow::Result<()> {
548        let order = self.core.cache().try_order_owned(&cmd.client_order_id)?;
549
550        let emitter = self.emitter.clone();
551        let trader_id = self.core.trader_id;
552        let account_id = self.core.account_id;
553        let clock = self.clock;
554        let client_order_id = order.client_order_id();
555        let strategy_id = order.strategy_id();
556        let instrument_id = order.instrument_id();
557        let order_side = order.order_side();
558        let order_type = order.order_type();
559        let quantity = order.quantity();
560        let time_in_force = lifetime.time_in_force;
561        let good_till_date = lifetime.good_till_date;
562        let price = order.price();
563        let trigger_price = order.trigger_price();
564        let reduce_only = order.is_reduce_only();
565        let post_only = order.is_post_only();
566        let activation_price = order.activation_price();
567        let trailing_offset = order.trailing_offset();
568        let trigger_type = order.trigger_type();
569
570        let close_position = cmd
571            .params
572            .as_ref()
573            .and_then(|p| p.get_bool(PARAMS_CLOSE_POSITION))
574            .unwrap_or(false);
575        let rpi = cmd
576            .params
577            .as_ref()
578            .and_then(|p| p.get_bool("rpi"))
579            .unwrap_or(false);
580
581        let use_algo_api = is_algo_order_type(order_type);
582        let use_ws = self.ws_trading_active() && !use_algo_api;
583        if !use_ws
584            && let Err(e) = self
585                .http_client
586                .instrument_metadata(instrument_id)
587                .and_then(|metadata| Ok(metadata.precisions()?))
588        {
589            let reason = OrderDeniedReason::ValidationFailed {
590                detail: e.to_string(),
591            };
592            self.emitter.emit_order_denied(&order, &reason.to_string());
593            return Ok(());
594        }
595
596        // Register identity for tracked/external dispatch routing
597        self.dispatch_state.order_identities.insert(
598            client_order_id,
599            OrderIdentity {
600                instrument_id,
601                strategy_id,
602                order_side,
603                order_type,
604                price,
605                quantity,
606                is_quote_quantity: false,
607                venue_position_id,
608            },
609        );
610
611        let price_match = cmd
612            .params
613            .as_ref()
614            .and_then(|p| p.get_str("price_match"))
615            .map(BinancePriceMatch::from_param)
616            .transpose()?;
617
618        let callback_rate = trailing_offset
619            .map(trailing_offset_to_callback_rate_string)
620            .transpose()?;
621
622        let working_type = match trigger_type {
623            Some(TriggerType::MarkPrice) => Some(BinanceWorkingType::MarkPrice),
624            Some(TriggerType::LastPrice | TriggerType::Default) => {
625                Some(BinanceWorkingType::ContractPrice)
626            }
627            _ => None,
628        };
629
630        // Non-algo orders can route through WS trading API when active
631        if use_ws {
632            let ws_client = self.ws_trading_client.as_ref().unwrap().clone();
633            let dispatch_state = self.dispatch_state.clone();
634
635            let symbol = format_binance_symbol(&instrument_id);
636            let binance_side = BinanceSide::try_from(order_side)?;
637            let binance_order_type = order_type_to_binance_futures(order_type)?;
638            let binance_tif = if rpi {
639                BinanceTimeInForce::Rpi
640            } else if post_only {
641                BinanceTimeInForce::Gtx
642            } else {
643                BinanceTimeInForce::try_from(time_in_force)?
644            };
645
646            let requires_time_in_force = matches!(
647                order_type,
648                OrderType::Limit | OrderType::StopLimit | OrderType::LimitIfTouched
649            );
650
651            let client_id_str =
652                encode_broker_id(&client_order_id, BINANCE_NAUTILUS_FUTURES_BROKER_ID);
653
654            let params = BinanceNewOrderParams {
655                symbol,
656                side: binance_side,
657                order_type: binance_order_type,
658                time_in_force: if requires_time_in_force {
659                    Some(binance_tif)
660                } else {
661                    None
662                },
663                quantity: Some(quantity.to_string()),
664                price: if price_match.is_some() {
665                    None
666                } else {
667                    price.map(|p| p.to_string())
668                },
669                new_client_order_id: Some(client_id_str),
670                stop_price: trigger_price.map(|p| p.to_string()),
671                reduce_only: reduce_only_param(reduce_only, position_side),
672                position_side,
673                close_position: None,
674                activation_price: activation_price.map(|p| p.to_string()),
675                callback_rate,
676                working_type,
677                price_protect: None,
678                new_order_resp_type: None,
679                good_till_date,
680                recv_window: None,
681                price_match,
682                self_trade_prevention_mode: None,
683            };
684
685            self.emitter.emit_order_submitted(&order);
686
687            // Pre-register before sending to avoid response racing the insert
688            let request_id = ws_client.next_request_id();
689            dispatch_state.pending_requests.insert(
690                request_id.clone(),
691                PendingRequest {
692                    command_id: None,
693                    client_order_id,
694                    venue_order_id: None,
695                    operation: PendingOperation::Place,
696                },
697            );
698
699            self.spawn_task("submit_order_ws", async move {
700                if let Err(e) = ws_client
701                    .place_order_with_id(request_id.clone(), params)
702                    .await
703                {
704                    dispatch_state.pending_requests.remove(&request_id);
705                    log::warn!("WS submit request failed for {client_order_id}: {e}");
706                    anyhow::bail!("WS submit order failed: {e}");
707                }
708                Ok(())
709            });
710
711            return Ok(());
712        }
713
714        let http_client = self.http_client.clone();
715        let dispatch_state = self.dispatch_state.clone();
716
717        self.emitter.emit_order_submitted(&order);
718
719        self.spawn_task("submit_order", async move {
720            let result = if use_algo_api {
721                http_client
722                    .submit_algo_order(
723                        account_id,
724                        instrument_id,
725                        client_order_id,
726                        order_side,
727                        order_type,
728                        quantity,
729                        time_in_force,
730                        price,
731                        trigger_price,
732                        reduce_only,
733                        close_position,
734                        position_side,
735                        activation_price,
736                        callback_rate,
737                        working_type,
738                        good_till_date,
739                    )
740                    .await
741            } else {
742                http_client
743                    .submit_order(
744                        account_id,
745                        instrument_id,
746                        client_order_id,
747                        order_side,
748                        order_type,
749                        quantity,
750                        time_in_force,
751                        price,
752                        trigger_price,
753                        reduce_only,
754                        post_only,
755                        rpi,
756                        position_side,
757                        price_match,
758                        good_till_date,
759                    )
760                    .await
761            };
762
763            match result {
764                Ok(report) => {
765                    log::debug!(
766                        "Order submit accepted: client_order_id={}, venue_order_id={}",
767                        client_order_id,
768                        report.venue_order_id
769                    );
770                }
771                Err(e) => {
772                    // Keep order registered on ambiguous evidence - if HTTP failed due to
773                    // timeout but the order reached Binance, WebSocket updates will still
774                    // arrive. The order resolves via the stream or reconciliation.
775                    let http_error = e.downcast_ref::<BinanceFuturesHttpError>();
776                    let failure = http_error.map_or_else(
777                        || CommandFailure::Ambiguous(e.to_string()),
778                        classify_futures_http_failure,
779                    );
780
781                    match failure {
782                        CommandFailure::Ambiguous(reason) => {
783                            log::warn!(
784                                "Ambiguous submit failure for {client_order_id}, awaiting reconciliation: {reason}"
785                            );
786                        }
787                        CommandFailure::NotSent(reason) | CommandFailure::VenueRejected(reason) => {
788                            let due_post_only = classify_submit_order_error(&e);
789                            let ts_now = clock.get_time_ns();
790
791                            let rejected = OrderRejected::new(
792                                trader_id,
793                                strategy_id,
794                                instrument_id,
795                                client_order_id,
796                                account_id,
797                                format!("submit-order-error: {}", sanitize_reason(&reason)).into(),
798                                UUID4::new(),
799                                ts_now,
800                                ts_now,
801                                false,
802                                due_post_only,
803                            );
804
805                            dispatch_state.cleanup_terminal(client_order_id);
806                            emitter.send_order_event(OrderEventAny::Rejected(rejected));
807                        }
808                    }
809
810                    return Err(e);
811                }
812            }
813
814            Ok(())
815        });
816
817        Ok(())
818    }
819
820    fn cancel_order_internal(&self, cmd: &CancelOrder) {
821        let command = cmd.clone();
822        self.dispatch_state
823            .cancels_unresolved
824            .insert(command.client_order_id);
825
826        // Non-triggered algo orders use algo cancel endpoint, triggered use regular
827        let is_algo = self
828            .core
829            .cache()
830            .order(&command.client_order_id)
831            .is_some_and(|order| is_algo_order_type(order.order_type()));
832        let promoted_venue_order_id = self
833            .dispatch_state
834            .promoted_algo_order_id(&command.client_order_id);
835        let use_algo_cancel = should_use_algo_cancel(
836            is_algo,
837            self.triggered_algo_order_ids
838                .contains(&command.client_order_id),
839            promoted_venue_order_id.is_some(),
840        );
841
842        let emitter = self.emitter.clone();
843        let trader_id = self.core.trader_id;
844        let account_id = self.core.account_id;
845        let clock = self.clock;
846        let instrument_id = command.instrument_id;
847        let venue_order_id =
848            cancel_venue_order_id(is_algo, command.venue_order_id, promoted_venue_order_id);
849        let client_order_id = command.client_order_id;
850
851        // Non-algo cancels can route through WS trading API when active
852        if self.ws_trading_active() && !use_algo_cancel {
853            let ws_client = self.ws_trading_client.as_ref().unwrap().clone();
854            let dispatch_state = self.dispatch_state.clone();
855
856            let mut cancel_builder = BinanceCancelOrderParamsBuilder::default();
857            cancel_builder.symbol(format_binance_symbol(&instrument_id));
858
859            if let Some(venue_id) = venue_order_id {
860                match venue_id.inner().parse::<i64>() {
861                    Ok(order_id) => {
862                        cancel_builder.order_id(order_id);
863                    }
864                    Err(e) => {
865                        log::warn!(
866                            "Unable to parse venue_order_id {venue_id} for cancel {client_order_id}, canceling by client_order_id: {e}"
867                        );
868                    }
869                }
870            }
871
872            cancel_builder.orig_client_order_id(encode_broker_id(
873                &client_order_id,
874                BINANCE_NAUTILUS_FUTURES_BROKER_ID,
875            ));
876
877            let params = cancel_builder.build().unwrap();
878
879            // Pre-register before sending to avoid response racing the insert
880            let request_id = ws_client.next_request_id();
881            dispatch_state.pending_requests.insert(
882                request_id.clone(),
883                PendingRequest {
884                    command_id: Some(command.command_id),
885                    client_order_id,
886                    venue_order_id,
887                    operation: PendingOperation::Cancel,
888                },
889            );
890
891            let http_client = self.http_client.clone();
892            self.spawn_task("cancel_order_ws", async move {
893                let mut params = params;
894                http_client
895                    .inner()
896                    .resolve_order_identity(
897                        &params.symbol,
898                        &mut params.order_id,
899                        &mut params.orig_client_order_id,
900                        false,
901                    )
902                    .await
903                    .inspect_err(|e| {
904                        dispatch_state.pending_requests.remove(&request_id);
905                        let ts_now = clock.get_time_ns();
906
907                        let mut rejected = OrderCancelDenied::new(
908                            trader_id,
909                            command.strategy_id,
910                            command.instrument_id,
911                            command.client_order_id,
912                            format!(
913                                "cancel identity lookup failed before submission: {}",
914                                sanitize_reason(&e.to_string())
915                            )
916                            .into(),
917                            UUID4::new(),
918                            ts_now,
919                            ts_now,
920                            command.venue_order_id,
921                            Some(account_id),
922                        );
923                        rejected.causation_id = Some(command.command_id);
924                        emitter.send_order_event(OrderEventAny::CancelDenied(rejected));
925                    })?;
926
927                let result = ws_client
928                    .cancel_order_with_id(request_id.clone(), params)
929                    .await;
930
931                if let Err(e) = result {
932                    dispatch_state.pending_requests.remove(&request_id);
933                    log::warn!("WS cancel request failed for {client_order_id}: {e}");
934                    anyhow::bail!("WS cancel order failed: {e}");
935                }
936                Ok(())
937            });
938
939            return;
940        }
941
942        let http_client = self.http_client.clone();
943        let cancels_unresolved = self.dispatch_state.cancels_unresolved.clone();
944
945        self.spawn_task("cancel_order", async move {
946            let result = cancel_order_http(
947                &http_client, instrument_id, venue_order_id, client_order_id, use_algo_cancel,
948            ).await;
949
950            match result {
951                Ok(()) => {
952                    cancels_unresolved.remove(&client_order_id);
953                    log::debug!("Cancel request accepted: client_order_id={client_order_id}");
954                }
955                Err(e) => {
956                    let failure = e.downcast_ref::<BinanceFuturesHttpError>().map_or_else(
957                        || CommandFailure::Ambiguous(e.to_string()),
958                        classify_futures_http_failure,
959                    );
960
961                    match failure {
962                        CommandFailure::Ambiguous(reason) => {
963                            log::warn!(
964                                "Ambiguous cancel failure for {client_order_id}, awaiting reconciliation: {reason}"
965                            );
966                        }
967                        CommandFailure::NotSent(reason) => {
968                            let ts_now = clock.get_time_ns();
969
970                            let mut rejected = OrderCancelDenied::new(
971                                trader_id,
972                                command.strategy_id,
973                                command.instrument_id,
974                                client_order_id,
975                                format!("cancel-order-error: {}", sanitize_reason(&reason)).into(),
976                                UUID4::new(),
977                                ts_now,
978                                ts_now,
979                                command.venue_order_id,
980                                Some(account_id),
981                            );
982                            rejected.causation_id = Some(command.command_id);
983
984                            emitter.send_order_event(OrderEventAny::CancelDenied(rejected));
985                        }
986                        CommandFailure::VenueRejected(reason) => {
987                            let ts_now = clock.get_time_ns();
988
989                            let mut rejected = OrderCancelRejected::new(
990                                trader_id,
991                                command.strategy_id,
992                                command.instrument_id,
993                                client_order_id,
994                                format!("cancel-order-error: {}", sanitize_reason(&reason)).into(),
995                                UUID4::new(),
996                                ts_now,
997                                ts_now,
998                                false,
999                                command.venue_order_id,
1000                                Some(account_id),
1001                            );
1002                            rejected.causation_id = Some(command.command_id);
1003
1004                            emitter.send_order_event(OrderEventAny::CancelRejected(rejected));
1005                        }
1006                    }
1007
1008                    return Err(e);
1009                }
1010            }
1011
1012            Ok(())
1013        });
1014    }
1015
1016    fn cancel_all_orders_for_side(&self, cmd: &CancelAllOrders) -> anyhow::Result<()> {
1017        // Cancel-all has no side parameter, and batch covers regular orders only
1018        let (regular_cancels, algo_cancels): (Vec<CancelOrder>, Vec<CancelOrder>) = {
1019            let cache = self.core.cache();
1020            let mut regular = Vec::new();
1021            let mut algo = Vec::new();
1022
1023            for order in cache.orders_open(
1024                None,
1025                Some(&cmd.instrument_id),
1026                None,
1027                Some(&self.core.account_id),
1028                cmd.order_side,
1029            ) {
1030                let cancel = CancelOrder {
1031                    trader_id: order.trader_id(),
1032                    client_id: cmd.client_id,
1033                    strategy_id: order.strategy_id(),
1034                    instrument_id: order.instrument_id(),
1035                    client_order_id: order.client_order_id(),
1036                    venue_order_id: order.venue_order_id(),
1037                    command_id: cmd.command_id,
1038                    ts_init: cmd.ts_init,
1039                    params: cmd.params.clone(),
1040                    correlation_id: cmd.correlation_id,
1041                    causation_id: cmd.causation_id,
1042                };
1043
1044                if is_algo_order_type(order.order_type()) {
1045                    algo.push(cancel);
1046                } else {
1047                    regular.push(cancel);
1048                }
1049            }
1050
1051            (regular, algo)
1052        };
1053
1054        if regular_cancels.is_empty() && algo_cancels.is_empty() {
1055            log::debug!("No open orders to cancel for {}", cmd.instrument_id);
1056            return Ok(());
1057        }
1058
1059        if !regular_cancels.is_empty() {
1060            self.batch_cancel_orders(BatchCancelOrders {
1061                trader_id: cmd.trader_id,
1062                client_id: cmd.client_id,
1063                strategy_id: cmd.strategy_id,
1064                instrument_id: cmd.instrument_id,
1065                cancels: regular_cancels,
1066                command_id: cmd.command_id,
1067                ts_init: cmd.ts_init,
1068                params: cmd.params.clone(),
1069                correlation_id: cmd.correlation_id,
1070                causation_id: cmd.causation_id,
1071            })?;
1072        }
1073
1074        for cancel in &algo_cancels {
1075            self.cancel_order_internal(cancel);
1076        }
1077
1078        Ok(())
1079    }
1080
1081    fn spawn_task<F>(&self, description: &'static str, fut: F)
1082    where
1083        F: Future<Output = anyhow::Result<()>> + Send + 'static,
1084    {
1085        crate::common::execution::spawn_task(&self.pending_tasks, description, fut);
1086    }
1087
1088    fn begin_generation_shutdown(&mut self) {
1089        self.cancellation_token.cancel();
1090        self.abort_session_tasks();
1091
1092        if let Some(client) = self.ws_client.lock().as_ref() {
1093            client.begin_shutdown();
1094        }
1095
1096        if let Some(client) = self.ws_trading_client.as_ref() {
1097            client.begin_shutdown();
1098        }
1099
1100        if let Ok(mut task_slot) = self.ws_task.try_lock() {
1101            task_slot.abort();
1102        }
1103
1104        self.recovery_tx.take();
1105
1106        self.abort_pending_tasks();
1107        self.core.set_disconnected();
1108    }
1109
1110    fn abort_pending_tasks(&self) {
1111        crate::common::execution::abort_pending_tasks(&self.pending_tasks);
1112    }
1113
1114    fn abort_session_tasks(&self) {
1115        self.session_tasks.begin_shutdown();
1116    }
1117
1118    async fn await_pending_tasks(&self) -> anyhow::Result<()> {
1119        crate::common::execution::await_pending_tasks(&self.pending_tasks).await
1120    }
1121
1122    async fn await_session_tasks(&self) -> anyhow::Result<()> {
1123        self.finish_session_tasks().await.map_err(|e| {
1124            anyhow::anyhow!("Failed to terminate Binance Futures session tasks: {e}")
1125        })?;
1126        Ok(())
1127    }
1128
1129    async fn finish_session_tasks(&self) -> Result<(), TaskShutdownError> {
1130        self.session_tasks.begin_shutdown();
1131        self.session_tasks
1132            .finish_shutdown(Duration::from_secs(1), Duration::from_secs(2))
1133            .await?;
1134        Ok(())
1135    }
1136
1137    async fn await_dispatch_task(&self) -> anyhow::Result<()> {
1138        let _recovery_guard = self.recovery_lock.lock().await;
1139        let mut task_slot = self.ws_task.lock().await;
1140        let Some(outcome) = finish_task(
1141            &mut task_slot,
1142            Duration::from_secs(1),
1143            Duration::from_secs(2),
1144        )
1145        .await
1146        else {
1147            return Ok(());
1148        };
1149
1150        match outcome {
1151            TaskJoinOutcome::Completed(()) | TaskJoinOutcome::Aborted => Ok(()),
1152            TaskJoinOutcome::Failed(e) => {
1153                Err(anyhow::anyhow!("Binance Futures dispatch task failed: {e}"))
1154            }
1155            TaskJoinOutcome::Incomplete => Err(anyhow::anyhow!(
1156                "Binance Futures dispatch task did not stop after abort"
1157            )),
1158        }
1159    }
1160
1161    async fn close_listen_key_slot(
1162        &self,
1163        slot: &RwLock<Option<SecretString>>,
1164        context: &str,
1165    ) -> anyhow::Result<()> {
1166        let key = slot.read().clone();
1167        let Some(key) = key else {
1168            return Ok(());
1169        };
1170
1171        self.http_client
1172            .close_listen_key(key.expose_secret())
1173            .await
1174            .with_context(|| context.to_string())?;
1175        let mut owned = slot.write();
1176        if owned.as_ref().map(SecretString::expose_secret) == Some(key.expose_secret()) {
1177            *owned = None;
1178        }
1179        Ok(())
1180    }
1181
1182    /// Returns the (price_precision, size_precision) for an instrument.
1183    fn get_instrument_precision(&self, instrument_id: InstrumentId) -> anyhow::Result<(u8, u8)> {
1184        self.http_client
1185            .instrument_reconciliation(&instrument_id)
1186            .map(|instrument| (instrument.price_precision(), instrument.size_precision()))
1187            .ok_or_else(|| {
1188                anyhow::anyhow!(
1189                    "Binance Futures instrument {instrument_id} is not loaded for reconciliation"
1190                )
1191            })
1192    }
1193
1194    fn is_instrument_out_of_scope(&self, instrument_id: InstrumentId) -> bool {
1195        self.config.instrument_provider.excludes(instrument_id)
1196    }
1197
1198    /// Creates a position status report from Binance position risk data.
1199    fn create_position_report(
1200        &self,
1201        position: &BinancePositionRisk,
1202        instrument_id: InstrumentId,
1203        size_precision: u8,
1204    ) -> anyhow::Result<PositionStatusReport> {
1205        let position_amount: Decimal = position
1206            .position_amt
1207            .parse()
1208            .context("invalid position_amt")?;
1209
1210        if position_amount.is_zero() {
1211            anyhow::bail!("Position is flat");
1212        }
1213
1214        let entry_price: Decimal = position
1215            .entry_price
1216            .parse()
1217            .context("invalid entry_price")?;
1218
1219        let position_side = if position_amount > Decimal::ZERO {
1220            PositionSide::Long
1221        } else {
1222            PositionSide::Short
1223        };
1224
1225        if self.config.use_position_ids {
1226            match position.position_side {
1227                Some(BinancePositionSide::Long) => anyhow::ensure!(
1228                    position_side == PositionSide::Long,
1229                    "position_side LONG conflicts with negative position_amt"
1230                ),
1231                Some(BinancePositionSide::Short) => anyhow::ensure!(
1232                    position_side == PositionSide::Short,
1233                    "position_side SHORT conflicts with positive position_amt"
1234                ),
1235                _ => {}
1236            }
1237        }
1238
1239        let venue_position_id = make_venue_position_id(
1240            self.config.use_position_ids,
1241            instrument_id,
1242            position.position_side,
1243        )?;
1244
1245        if let Some(venue_position_id) = venue_position_id {
1246            self.ensure_cached_position_id_compatible(
1247                instrument_id,
1248                position_side,
1249                venue_position_id,
1250            )?;
1251        }
1252
1253        let ts_now = self.clock.get_time_ns();
1254
1255        Ok(PositionStatusReport::new(
1256            self.core.account_id,
1257            instrument_id,
1258            position_side,
1259            Quantity::from_decimal_dp(position_amount.abs(), size_precision)?,
1260            ts_now,
1261            ts_now,
1262            Some(UUID4::new()),
1263            venue_position_id,
1264            Some(entry_price),
1265        ))
1266    }
1267
1268    fn ensure_cached_position_id_compatible(
1269        &self,
1270        instrument_id: InstrumentId,
1271        position_side: PositionSide,
1272        venue_position_id: PositionId,
1273    ) -> anyhow::Result<()> {
1274        let cache = self.core.cache();
1275        let mut incompatible_ids: Vec<_> = cache
1276            .positions_open(
1277                Some(&BINANCE_VENUE),
1278                Some(&instrument_id),
1279                None,
1280                Some(&self.core.account_id),
1281                Some(position_side),
1282            )
1283            .into_iter()
1284            .filter(|position| position.id != venue_position_id)
1285            .map(|position| position.id.to_string())
1286            .collect();
1287        incompatible_ids.sort_unstable();
1288
1289        anyhow::ensure!(
1290            incompatible_ids.is_empty(),
1291            "incompatible cached {position_side:?} position IDs for {instrument_id}: {}; expected {venue_position_id}",
1292            incompatible_ids.join(", "),
1293        );
1294        Ok(())
1295    }
1296
1297    async fn generate_open_order_status_reports(
1298        &self,
1299        instrument_id: Option<InstrumentId>,
1300        ts_init: UnixNanos,
1301    ) -> anyhow::Result<Vec<OpenOrderStatusReport>> {
1302        if let Some(instrument_id) = instrument_id
1303            && self
1304                .http_client
1305                .instrument_reconciliation(&instrument_id)
1306                .is_none()
1307        {
1308            if self.is_instrument_out_of_scope(instrument_id) {
1309                log::debug!(
1310                    "Dropping out-of-scope Binance Futures order request for instrument {instrument_id}"
1311                );
1312                return Ok(Vec::new());
1313            }
1314
1315            anyhow::bail!(
1316                "Binance Futures open order request has unresolved instrument {instrument_id}"
1317            );
1318        }
1319
1320        let symbol = instrument_id.map(|id| format_binance_symbol(&id));
1321        let mut builder = BinanceOpenOrdersParamsBuilder::default();
1322
1323        if let Some(symbol) = symbol {
1324            builder.symbol(symbol);
1325        }
1326        let params = builder.build().map_err(|e| anyhow::anyhow!("{e}"))?;
1327
1328        let (orders, algo_orders) = tokio::try_join!(
1329            self.http_client.query_open_orders(&params),
1330            self.http_client.query_open_algo_orders(instrument_id),
1331        )?;
1332        let mut reports = Vec::with_capacity(orders.len() + algo_orders.len());
1333
1334        for order in orders {
1335            let instrument_id = instrument_id
1336                .unwrap_or_else(|| format_instrument_id(&order.symbol, self.product_type));
1337            let Some(instrument) = self.http_client.instrument_reconciliation(&instrument_id)
1338            else {
1339                if self.is_instrument_out_of_scope(instrument_id) {
1340                    log::debug!(
1341                        "Dropping out-of-scope Binance Futures open order for instrument {instrument_id}"
1342                    );
1343                    continue;
1344                }
1345                anyhow::bail!(
1346                    "Binance Futures open order has unresolved instrument {instrument_id}"
1347                );
1348            };
1349
1350            let report = order.to_order_status_report(
1351                self.core.account_id,
1352                instrument.id(),
1353                instrument.price_precision(),
1354                instrument.size_precision(),
1355                self.config.treat_expired_as_canceled,
1356                ts_init,
1357            )?;
1358            let venue_position_id = make_venue_position_id(
1359                self.config.use_position_ids,
1360                instrument.id(),
1361                order.position_side,
1362            )?;
1363            reports.push(OpenOrderStatusReport {
1364                report: with_venue_position_id(report, venue_position_id),
1365                quantity_free_close_position_side: None,
1366            });
1367        }
1368
1369        for algo_order in algo_orders {
1370            let instrument_id = instrument_id
1371                .unwrap_or_else(|| format_instrument_id(&algo_order.symbol, self.product_type));
1372            let Some(instrument) = self.http_client.instrument_reconciliation(&instrument_id)
1373            else {
1374                if self.is_instrument_out_of_scope(instrument_id) {
1375                    log::debug!(
1376                        "Dropping out-of-scope Binance Futures open algo order for instrument {instrument_id}"
1377                    );
1378                    continue;
1379                }
1380                anyhow::bail!(
1381                    "Binance Futures open algo order has unresolved instrument {instrument_id}"
1382                );
1383            };
1384
1385            let report = algo_order.to_order_status_report(
1386                self.core.account_id,
1387                instrument.id(),
1388                instrument.price_precision(),
1389                instrument.size_precision(),
1390                ts_init,
1391            )?;
1392            let venue_position_id = make_venue_position_id(
1393                self.config.use_position_ids,
1394                instrument.id(),
1395                algo_order.position_side,
1396            )?;
1397            reports.push(OpenOrderStatusReport {
1398                report: with_venue_position_id(report, venue_position_id),
1399                quantity_free_close_position_side: quantity_free_close_position_side(&algo_order),
1400            });
1401        }
1402
1403        Ok(reports)
1404    }
1405
1406    async fn generate_order_history(
1407        &self,
1408        instrument_id: InstrumentId,
1409        start: UnixNanos,
1410        end: UnixNanos,
1411    ) -> anyhow::Result<Vec<OrderStatusReport>> {
1412        let instrument = self
1413            .http_client
1414            .instrument_reconciliation(&instrument_id)
1415            .context("unresolved Binance Futures history instrument")?;
1416        let (orders, algo_orders) = self
1417            .http_client
1418            .query_order_history(instrument_id, start, end)
1419            .await?;
1420
1421        let mut reports = IndexMap::new();
1422
1423        for order in orders.values() {
1424            let report = order.to_order_status_report(
1425                self.core.account_id,
1426                instrument_id,
1427                instrument.price_precision(),
1428                instrument.size_precision(),
1429                self.config.treat_expired_as_canceled,
1430                end,
1431            )?;
1432            let venue_position_id = make_venue_position_id(
1433                self.config.use_position_ids,
1434                instrument_id,
1435                order.position_side,
1436            )?;
1437            reports.insert(
1438                report.venue_order_id,
1439                with_venue_position_id(report, venue_position_id),
1440            );
1441        }
1442
1443        for algo in algo_orders.into_values() {
1444            let actual =
1445                if let Some(id) = algo.actual_order_id.as_deref().filter(|id| !id.is_empty()) {
1446                    let id = id.parse::<i64>().context("invalid algo actual order ID")?;
1447                    if let Some(order) = orders.get(&id) {
1448                        Some(order.clone())
1449                    } else {
1450                        self.http_client
1451                            .query_algo_order_actual(instrument_id, id)
1452                            .await?
1453                    }
1454                } else {
1455                    None
1456                };
1457
1458            let result = BinanceFuturesAlgoOrderQueryResult { algo, actual };
1459            let report = create_algo_order_status_report(
1460                &result,
1461                self.core.account_id,
1462                instrument_id,
1463                instrument.price_precision(),
1464                instrument.size_precision(),
1465                self.config.treat_expired_as_canceled,
1466                self.config.use_position_ids,
1467                end,
1468            )?;
1469            reports.insert(report.venue_order_id, report);
1470        }
1471
1472        Ok(reports.into_values().collect())
1473    }
1474
1475    async fn apply_futures_config(&self) -> anyhow::Result<()> {
1476        if let Some(ref leverages) = self.config.futures_leverages {
1477            for (symbol, leverage) in leverages {
1478                let params = BinanceSetLeverageParams {
1479                    symbol: symbol.clone(),
1480                    leverage: *leverage,
1481                    recv_window: None,
1482                };
1483                // Best-effort: a venue reject is non-fatal, but transport errors
1484                // propagate so an unhealthy connection still surfaces.
1485                match self.http_client.set_leverage(&params).await {
1486                    Ok(response) => {
1487                        log::info!("Set leverage {} {}X", response.symbol, response.leverage);
1488                    }
1489                    Err(BinanceFuturesHttpError::BinanceError { code, message, .. }) => {
1490                        log::warn!(
1491                            "Unable to set leverage for {symbol} to {leverage}x: [{code}] {message}; skipping (leverage init is best-effort)"
1492                        );
1493                    }
1494                    Err(e) => {
1495                        return Err(e).context(format!("failed to set leverage for {symbol}"));
1496                    }
1497                }
1498            }
1499        }
1500
1501        if let Some(ref margin_types) = self.config.futures_margin_types {
1502            for (symbol, margin_type) in margin_types {
1503                let params = BinanceSetMarginTypeParams {
1504                    symbol: symbol.clone(),
1505                    margin_type: *margin_type,
1506                    recv_window: None,
1507                };
1508
1509                match self.http_client.set_margin_type(&params).await {
1510                    Ok(_) => {
1511                        log::info!("Set {symbol} margin type to {margin_type:?}");
1512                    }
1513                    Err(BinanceFuturesHttpError::BinanceError { code: -4046, .. }) => {
1514                        log::debug!("{symbol} margin type already {margin_type:?}");
1515                    }
1516                    Err(e) => {
1517                        return Err(e).context(format!("failed to set margin type for {symbol}"));
1518                    }
1519                }
1520            }
1521        }
1522
1523        Ok(())
1524    }
1525}
1526
1527fn quantity_free_close_position_side(order: &BinanceFuturesAlgoOrder) -> Option<PositionSide> {
1528    let quantity_free = match order.quantity.as_deref() {
1529        None => true,
1530        Some(quantity) => quantity
1531            .parse::<Decimal>()
1532            .is_ok_and(|quantity| quantity.is_zero()),
1533    };
1534
1535    if order.close_position != Some(true) || !quantity_free {
1536        return None;
1537    }
1538
1539    match (order.side, order.position_side) {
1540        (BinanceSide::Sell, Some(BinancePositionSide::Long | BinancePositionSide::Both) | None) => {
1541            Some(PositionSide::Long)
1542        }
1543        (BinanceSide::Buy, Some(BinancePositionSide::Short | BinancePositionSide::Both) | None) => {
1544            Some(PositionSide::Short)
1545        }
1546        _ => None,
1547    }
1548}
1549
1550fn restore_close_position_quantities(
1551    order_reports: &mut [OpenOrderStatusReport],
1552    position_reports: &[PositionStatusReport],
1553) {
1554    // Binance accepts close-all orders without quantity and reports the omitted value as either
1555    // absent or zero. Core reconciliation needs a positive quantity to materialize the order, so
1556    // the current position leg is the narrowest valid source.
1557    for order_report in order_reports {
1558        let Some(position_side) = order_report.quantity_free_close_position_side else {
1559            continue;
1560        };
1561
1562        if order_report.report.quantity.is_positive() {
1563            continue;
1564        }
1565
1566        let mut matching_positions = position_reports.iter().filter(|position| {
1567            position.account_id == order_report.report.account_id
1568                && position.instrument_id == order_report.report.instrument_id
1569                && position.position_side == position_side
1570        });
1571        let Some(position) = matching_positions.next() else {
1572            continue;
1573        };
1574
1575        if matching_positions.next().is_some() {
1576            log::warn!(
1577                "Cannot restore close-position quantity for order {}: multiple {:?} position reports for {}",
1578                order_report.report.venue_order_id,
1579                position_side,
1580                order_report.report.instrument_id,
1581            );
1582            continue;
1583        }
1584
1585        order_report.report.quantity = position.quantity;
1586    }
1587}
1588
1589fn resolve_order_position_identity(
1590    is_hedge_mode: bool,
1591    use_position_ids: bool,
1592    order: &OrderAny,
1593) -> Result<(Option<BinancePositionSide>, Option<PositionId>), OrderDeniedReason> {
1594    let position_side =
1595        determine_position_side(is_hedge_mode, order.order_side(), order.is_reduce_only());
1596    let venue_position_id = make_venue_position_id(
1597        use_position_ids,
1598        order.instrument_id(),
1599        Some(position_side.unwrap_or(BinancePositionSide::Both)),
1600    )
1601    .map_err(|e| OrderDeniedReason::ValidationFailed {
1602        detail: e.to_string(),
1603    })?;
1604    Ok((position_side, venue_position_id))
1605}
1606
1607fn validate_submit_position_id(
1608    submitted_position_id: Option<PositionId>,
1609    venue_position_id: Option<PositionId>,
1610) -> Result<(), OrderDeniedReason> {
1611    if let (Some(submitted_position_id), Some(venue_position_id)) =
1612        (submitted_position_id, venue_position_id)
1613        && submitted_position_id != venue_position_id
1614    {
1615        return Err(OrderDeniedReason::InvalidPositionId {
1616            position_id: submitted_position_id,
1617            detail: format!(
1618                "conflicts with canonical Binance Futures venue position ID {venue_position_id}; omit position_id while use_position_ids=true, or set use_position_ids=false for virtual hedging"
1619            ),
1620        });
1621    }
1622    Ok(())
1623}
1624
1625fn build_futures_order_list_batch(
1626    orders: &[OrderAny],
1627    is_hedge_mode: bool,
1628    close_position: bool,
1629    price_match: Option<BinancePriceMatch>,
1630    product_type: BinanceProductType,
1631    use_gtd: bool,
1632    ts_now: UnixNanos,
1633) -> Result<Vec<BatchOrderItem>, String> {
1634    if orders.len() > 5 {
1635        return Err(format!(
1636            "Binance Futures batch order submission supports at most 5 orders, was {}",
1637            orders.len()
1638        ));
1639    }
1640
1641    if close_position {
1642        return Err(
1643            "`close_position` is not supported for Binance Futures batch order submission"
1644                .to_string(),
1645        );
1646    }
1647
1648    if orders.iter().any(is_grouped_order) {
1649        return Err(
1650            "Binance Futures linked order-list contingencies require adapter-level OCO-on-fill state"
1651                .to_string(),
1652        );
1653    }
1654
1655    if let Some(order) = orders
1656        .iter()
1657        .find(|order| is_algo_order_type(order.order_type()))
1658    {
1659        return Err(format!(
1660            "Binance Futures batch order submission does not support conditional order type {:?}",
1661            order.order_type()
1662        ));
1663    }
1664
1665    let mut batch_items = Vec::with_capacity(orders.len());
1666    for order in orders {
1667        if price_match.is_some() && order.is_post_only() {
1668            return Err(OrderDeniedReason::unsupported_post_only().to_string());
1669        }
1670
1671        if price_match.is_some() && order.order_type() != OrderType::Limit {
1672            return Err(format!(
1673                "price_match is not supported for order type {:?}",
1674                order.order_type()
1675            ));
1676        }
1677
1678        let binance_side = BinanceSide::try_from(order.order_side()).map_err(|e| e.to_string())?;
1679        let binance_order_type =
1680            order_type_to_binance_futures(order.order_type()).map_err(|e| e.to_string())?;
1681        let lifetime = determine_futures_order_lifetime(
1682            product_type,
1683            order.order_type(),
1684            order.time_in_force(),
1685            order.expire_time(),
1686            order.is_post_only(),
1687            use_gtd,
1688            ts_now,
1689        )
1690        .map_err(|e| e.to_string())?;
1691        let binance_tif = if order.is_post_only() {
1692            BinanceTimeInForce::Gtx
1693        } else {
1694            BinanceTimeInForce::try_from(lifetime.time_in_force).map_err(|e| e.to_string())?
1695        };
1696        let position_side =
1697            determine_position_side(is_hedge_mode, order.order_side(), order.is_reduce_only());
1698        let requires_time_in_force = matches!(order.order_type(), OrderType::Limit);
1699
1700        batch_items.push(BatchOrderItem {
1701            symbol: format_binance_symbol(&order.instrument_id()),
1702            side: binance_side_wire(binance_side).to_string(),
1703            order_type: binance_futures_order_type_wire(binance_order_type).to_string(),
1704            time_in_force: if requires_time_in_force {
1705                Some(binance_time_in_force_wire(binance_tif).to_string())
1706            } else {
1707                None
1708            },
1709            quantity: Some(order.quantity().to_string()),
1710            price: if price_match.is_some() {
1711                None
1712            } else {
1713                order.price().map(|price| price.to_string())
1714            },
1715            reduce_only: reduce_only_param(order.is_reduce_only(), position_side),
1716            new_client_order_id: Some(encode_broker_id(
1717                &order.client_order_id(),
1718                BINANCE_NAUTILUS_FUTURES_BROKER_ID,
1719            )),
1720            stop_price: None,
1721            position_side: position_side.map(|side| binance_position_side_wire(side).to_string()),
1722            activation_price: None,
1723            callback_rate: None,
1724            working_type: None,
1725            price_protect: None,
1726            close_position: None,
1727            good_till_date: lifetime.good_till_date,
1728            price_match: price_match
1729                .and_then(binance_price_match_wire)
1730                .map(str::to_string),
1731            self_trade_prevention_mode: None,
1732        });
1733    }
1734
1735    Ok(batch_items)
1736}
1737
1738fn determine_futures_order_lifetime(
1739    product_type: BinanceProductType,
1740    order_type: OrderType,
1741    time_in_force: TimeInForce,
1742    expire_time: Option<UnixNanos>,
1743    post_only: bool,
1744    use_gtd: bool,
1745    ts_now: UnixNanos,
1746) -> Result<FuturesOrderLifetime, OrderDeniedReason> {
1747    if time_in_force != TimeInForce::Gtd {
1748        return Ok(FuturesOrderLifetime {
1749            time_in_force,
1750            good_till_date: None,
1751        });
1752    }
1753
1754    if !use_gtd {
1755        log::warn!(
1756            "Binance Futures GTD submitted as GTC because use_gtd=false. Enable manage_gtd_expiry on the submitting strategy"
1757        );
1758        return Ok(FuturesOrderLifetime {
1759            time_in_force: TimeInForce::Gtc,
1760            good_till_date: None,
1761        });
1762    }
1763
1764    if !matches!(
1765        order_type,
1766        OrderType::Limit | OrderType::StopLimit | OrderType::LimitIfTouched
1767    ) {
1768        return Err(OrderDeniedReason::ValidationFailed {
1769            detail: format!("Binance Futures does not support GTD for order type {order_type:?}"),
1770        });
1771    }
1772
1773    if post_only {
1774        return Err(OrderDeniedReason::unsupported_post_only());
1775    }
1776
1777    if product_type != BinanceProductType::UsdM {
1778        return Err(OrderDeniedReason::ValidationFailed {
1779            detail: format!("Binance {product_type:?} Futures does not support native GTD"),
1780        });
1781    }
1782
1783    let expire_time = expire_time.ok_or(OrderDeniedReason::MissingExpireTime)?;
1784    let expire_ns = expire_time.as_u64();
1785    if !expire_ns.is_multiple_of(NANOSECONDS_IN_SECOND) {
1786        return Err(OrderDeniedReason::ValidationFailed {
1787            detail: "Binance Futures goodTillDate requires whole-second precision".to_string(),
1788        });
1789    }
1790
1791    let minimum_ns = ts_now
1792        .as_u64()
1793        .checked_add(BINANCE_GTD_MIN_LEAD_SECS * NANOSECONDS_IN_SECOND)
1794        .ok_or_else(|| OrderDeniedReason::ValidationFailed {
1795            detail: "Binance Futures GTD minimum timestamp overflow".to_string(),
1796        })?;
1797
1798    if expire_ns <= minimum_ns {
1799        return Err(OrderDeniedReason::ValidationFailed {
1800            detail: format!(
1801                "Binance Futures goodTillDate must be strictly greater than current time plus {BINANCE_GTD_MIN_LEAD_SECS} seconds"
1802            ),
1803        });
1804    }
1805
1806    let good_till_date = expire_ns / NANOSECONDS_IN_MILLISECOND;
1807    if good_till_date >= BINANCE_GTD_MAX_MILLIS {
1808        return Err(OrderDeniedReason::ValidationFailed {
1809            detail: format!(
1810                "Binance Futures goodTillDate must be smaller than {BINANCE_GTD_MAX_MILLIS}"
1811            ),
1812        });
1813    }
1814
1815    Ok(FuturesOrderLifetime {
1816        time_in_force,
1817        good_till_date: Some(i64::try_from(good_till_date).map_err(|e| {
1818            OrderDeniedReason::ValidationFailed {
1819                detail: e.to_string(),
1820            }
1821        })?),
1822    })
1823}
1824
1825fn is_grouped_order(order: &OrderAny) -> bool {
1826    order.contingency_type().is_some()
1827        || order
1828            .linked_order_ids()
1829            .is_some_and(|linked_order_ids| !linked_order_ids.is_empty())
1830}
1831
1832fn binance_side_wire(side: BinanceSide) -> &'static str {
1833    match side {
1834        BinanceSide::Buy => "BUY",
1835        BinanceSide::Sell => "SELL",
1836    }
1837}
1838
1839fn binance_futures_order_type_wire(order_type: BinanceFuturesOrderType) -> &'static str {
1840    match order_type {
1841        BinanceFuturesOrderType::Limit => "LIMIT",
1842        BinanceFuturesOrderType::Market => "MARKET",
1843        BinanceFuturesOrderType::Stop => "STOP",
1844        BinanceFuturesOrderType::StopMarket => "STOP_MARKET",
1845        BinanceFuturesOrderType::TakeProfit => "TAKE_PROFIT",
1846        BinanceFuturesOrderType::TakeProfitMarket => "TAKE_PROFIT_MARKET",
1847        BinanceFuturesOrderType::TrailingStopMarket => "TRAILING_STOP_MARKET",
1848        BinanceFuturesOrderType::Liquidation => "LIQUIDATION",
1849        BinanceFuturesOrderType::Adl => "ADL",
1850        BinanceFuturesOrderType::Unknown => "UNKNOWN",
1851    }
1852}
1853
1854fn binance_time_in_force_wire(time_in_force: BinanceTimeInForce) -> &'static str {
1855    match time_in_force {
1856        BinanceTimeInForce::Gtc => "GTC",
1857        BinanceTimeInForce::GteGtc => "GTE_GTC",
1858        BinanceTimeInForce::Ioc => "IOC",
1859        BinanceTimeInForce::Fok => "FOK",
1860        BinanceTimeInForce::Gtx => "GTX",
1861        BinanceTimeInForce::Gtd => "GTD",
1862        BinanceTimeInForce::Rpi => "RPI",
1863        BinanceTimeInForce::Unknown => "UNKNOWN",
1864    }
1865}
1866
1867fn binance_position_side_wire(position_side: BinancePositionSide) -> &'static str {
1868    match position_side {
1869        BinancePositionSide::Both => "BOTH",
1870        BinancePositionSide::Long => "LONG",
1871        BinancePositionSide::Short => "SHORT",
1872        BinancePositionSide::Unknown => "UNKNOWN",
1873    }
1874}
1875
1876fn binance_price_match_wire(price_match: BinancePriceMatch) -> Option<&'static str> {
1877    match price_match {
1878        BinancePriceMatch::None | BinancePriceMatch::Unknown => None,
1879        BinancePriceMatch::Opponent => Some("OPPONENT"),
1880        BinancePriceMatch::Opponent5 => Some("OPPONENT_5"),
1881        BinancePriceMatch::Opponent10 => Some("OPPONENT_10"),
1882        BinancePriceMatch::Opponent20 => Some("OPPONENT_20"),
1883        BinancePriceMatch::Queue => Some("QUEUE"),
1884        BinancePriceMatch::Queue5 => Some("QUEUE_5"),
1885        BinancePriceMatch::Queue10 => Some("QUEUE_10"),
1886        BinancePriceMatch::Queue20 => Some("QUEUE_20"),
1887    }
1888}
1889
1890/// Classifies a submit-order error for the rejection event.
1891///
1892/// Returns `true` when the venue indicated a post-only (GTX) rejection. Logs
1893/// a hint when the error matches the UM/CM `dualSidePosition` sync rejection
1894/// (`-4531`), which is an account/setup mismatch rather than a routing fault.
1895pub(crate) fn classify_submit_order_error(err: &anyhow::Error) -> bool {
1896    let venue_code = err
1897        .downcast_ref::<BinanceFuturesHttpError>()
1898        .and_then(|be| match be {
1899            BinanceFuturesHttpError::BinanceError { code, .. } => Some(*code),
1900            _ => None,
1901        });
1902
1903    if venue_code == Some(BINANCE_FUTURES_DUAL_SIDE_SYNC_REJECT_CODE) {
1904        log::warn!(
1905            "Order rejected by Binance Futures with code -4531 \
1906             (UM/CM dualSidePosition sync); confirm Portfolio Margin hedge mode \
1907             matches the order positionSide before resubmitting"
1908        );
1909    }
1910    venue_code == Some(BINANCE_GTX_ORDER_REJECT_CODE)
1911}
1912
1913#[async_trait(?Send)]
1914impl ExecutionClient for BinanceFuturesExecutionClient {
1915    fn is_connected(&self) -> bool {
1916        self.core.is_connected()
1917    }
1918
1919    fn client_id(&self) -> ClientId {
1920        self.core.client_id
1921    }
1922
1923    fn account_id(&self) -> AccountId {
1924        self.core.account_id
1925    }
1926
1927    fn venue(&self) -> Venue {
1928        *BINANCE_VENUE
1929    }
1930
1931    fn oms_type(&self) -> OmsType {
1932        self.core.oms_type
1933    }
1934
1935    fn get_account(&self) -> Option<AccountAny> {
1936        self.core.cache().account_owned(&self.core.account_id)
1937    }
1938
1939    async fn connect(&mut self) -> anyhow::Result<()> {
1940        if self.core.is_connected() && self.session_tasks.is_open() && self.pending_tasks.is_open()
1941        {
1942            return Ok(());
1943        }
1944
1945        if !self.pending_tasks.is_open() || !self.session_tasks.is_open() {
1946            self.disconnect().await?;
1947        }
1948
1949        if !self.pending_tasks.is_open() {
1950            self.await_pending_tasks().await?;
1951            self.pending_tasks.start_generation().map_err(|e| {
1952                anyhow::anyhow!("Failed to start Binance Futures task generation: {e}")
1953            })?;
1954        }
1955
1956        if !self.session_tasks.is_open() {
1957            self.await_session_tasks().await?;
1958            self.await_dispatch_task().await?;
1959            self.session_tasks.start_generation().map_err(|e| {
1960                anyhow::anyhow!("Failed to start Binance Futures session generation: {e}")
1961            })?;
1962        }
1963
1964        self.cancellation_token = CancellationToken::new();
1965        let cancellation_token = self.cancellation_token.clone();
1966        let ws_client = Arc::clone(&self.ws_client);
1967        let ws_trading_client = self.ws_trading_client.clone();
1968        let setup_guard =
1969            TaskGroupGuard::new(&[&self.session_tasks, &self.pending_tasks], move || {
1970                cancellation_token.cancel();
1971
1972                if let Some(client) = ws_client.lock().as_ref() {
1973                    client.begin_shutdown();
1974                }
1975
1976                if let Some(client) = ws_trading_client {
1977                    client.begin_shutdown();
1978                }
1979            });
1980
1981        let connect_result: anyhow::Result<()> = async {
1982        // Check hedge mode
1983        let is_hedge_mode = self
1984            .init_hedge_mode()
1985            .await
1986            .context("failed to query hedge mode")?;
1987        self.is_hedge_mode.store(is_hedge_mode, Ordering::Release);
1988        log::info!("Hedge mode (dual side position): {is_hedge_mode}");
1989        if is_hedge_mode != (self.core.oms_type == OmsType::Hedging) {
1990            log::warn!(
1991                "Binance Futures account position mode does not match the configured OMS type: \
1992                 dual_side_position={is_hedge_mode}, oms_type={:?}; set oms_type to match the account position mode",
1993                self.core.oms_type,
1994            );
1995        }
1996
1997        let instruments = self
1998            .http_client
1999            .request_instruments_with_config(&self.config.instrument_provider)
2000            .await
2001            .context("failed to request Binance Futures instruments")?;
2002
2003        if instruments.is_empty() {
2004            log::warn!("No instruments returned for Binance Futures");
2005        } else {
2006            log::debug!("Loaded {} Futures instruments", instruments.len());
2007        }
2008        self.core.set_instruments_initialized();
2009
2010        self.restore_active_orders()?;
2011
2012        // Apply configured leverage and margin types
2013        self.apply_futures_config()
2014            .await
2015            .context("failed to apply futures config")?;
2016
2017        // Create listen key for user data stream
2018        log::debug!("Creating listen key for user data stream...");
2019        let listen_key_response = self
2020            .http_client
2021            .create_listen_key()
2022            .await
2023            .context("failed to create listen key")?;
2024        let listen_key = listen_key_response.into_listen_key();
2025        log::debug!("Listen key created successfully");
2026
2027        {
2028            let mut key_guard = self.listen_key.write();
2029            *key_guard = Some(listen_key.clone());
2030        }
2031
2032        let (api_key, api_secret) = resolve_credentials(
2033            self.config
2034                .api_key
2035                .as_ref()
2036                .map(|value| value.expose_secret().to_owned()),
2037            self.config
2038                .api_secret
2039                .as_ref()
2040                .map(|value| value.expose_secret().to_owned()),
2041            self.config.environment,
2042            self.product_type,
2043        )?;
2044
2045        let private_base_url = self.config.base_url_ws.clone().map_or_else(
2046            || get_ws_private_base_url(self.product_type, self.config.environment).to_string(),
2047            |url| {
2048                if self.product_type == BinanceProductType::UsdM
2049                    && self.config.environment == BinanceEnvironment::Live
2050                {
2051                    get_usdm_ws_route_base_url(&url, "private")
2052                } else {
2053                    url
2054                }
2055            },
2056        );
2057
2058        let (recovery_tx, recovery_rx) = tokio::sync::mpsc::unbounded_channel::<()>();
2059        self.recovery_tx = Some(recovery_tx.clone());
2060
2061        let seen_trade_ids = self.dispatch_state.seen_trade_ids();
2062
2063        let dispatch_ctx = Arc::new(DispatchCtx {
2064            emitter: self.emitter.clone(),
2065            http_client: self.http_client.clone(),
2066            account_id: self.core.account_id,
2067            product_type: self.product_type,
2068            clock: self.clock,
2069            dispatch_state: self.dispatch_state.clone(),
2070            triggered_algo_ids: self.triggered_algo_order_ids.clone(),
2071            use_position_ids: self.config.use_position_ids,
2072            default_taker_fee: self.config.default_taker_fee,
2073            bnfcr_currency: self.config.bnfcr_currency,
2074            treat_expired_as_canceled: self.config.treat_expired_as_canceled,
2075            use_trade_lite: self.config.use_trade_lite,
2076            seen_trade_ids,
2077            cancellation_token: self.cancellation_token.clone(),
2078        });
2079
2080        let ws_build_params = WsBuildParams {
2081            product_type: self.product_type,
2082            environment: self.config.environment,
2083            api_key: SecretString::from(api_key.clone()),
2084            api_secret: SecretString::from(api_secret.clone()),
2085            private_base_url: private_base_url.clone(),
2086            transport_backend: self.config.transport_backend,
2087            proxy_url: self.config.proxy_url.clone(),
2088            socket_factory: self.socket_factory.clone(),
2089        };
2090
2091        let ws_client =
2092            build_and_connect_user_stream(&ws_build_params, listen_key.expose_secret()).await?;
2093        let stream = ws_client.stream();
2094        *self.ws_client.lock() = Some(ws_client);
2095
2096        self.ws_task
2097            .lock()
2098            .await
2099            .spawn(run_user_stream_dispatch(
2100                stream,
2101                dispatch_ctx.clone(),
2102                recovery_tx.clone(),
2103                dispatch_user_stream_message,
2104            ))
2105            .map_err(|e| anyhow::anyhow!("failed to start user stream dispatch task: {e}"))?;
2106
2107        // Start listen key keepalive task
2108        {
2109            let http_client = self.http_client.clone();
2110            let listen_key_ref = self.listen_key.clone();
2111            let cancel = self.cancellation_token.clone();
2112            let recovery_tx = recovery_tx.clone();
2113
2114            self.session_tasks.spawn(async move {
2115                let mut interval =
2116                    tokio::time::interval(Duration::from_secs(LISTEN_KEY_KEEPALIVE_SECS));
2117                let mut consecutive_failures: u32 = 0;
2118
2119                loop {
2120                    tokio::select! {
2121                        _ = interval.tick() => {
2122                            let key = {
2123                                let guard = listen_key_ref.read();
2124                                guard.clone()
2125                            };
2126
2127                            if let Some(ref key) = key {
2128                                match http_client.keepalive_listen_key(key.expose_secret()).await {
2129                                    Ok(()) => {
2130                                        log::debug!("Listen key keepalive sent successfully");
2131                                        consecutive_failures = 0;
2132                                    }
2133                                    Err(e) => {
2134                                        consecutive_failures += 1;
2135                                        log::warn!(
2136                                            "Listen key keepalive failed ({consecutive_failures}/{MAX_KEEPALIVE_FAILURES}): {e}",
2137                                        );
2138
2139                                        if consecutive_failures >= MAX_KEEPALIVE_FAILURES
2140                                            && recovery_tx.send(()).is_err()
2141                                        {
2142                                            log::warn!(
2143                                                "Recovery channel closed, keepalive exiting",
2144                                            );
2145                                            break;
2146                                        }
2147                                    }
2148                                }
2149                            }
2150                        }
2151                        () = cancel.cancelled() => {
2152                            log::debug!("Listen key keepalive task cancelled");
2153                            break;
2154                        }
2155                    }
2156                }
2157            })?;
2158        }
2159
2160        // Start listen key recovery driver task
2161        {
2162            let recovery_ctx = RecoveryCtx {
2163                http_client: self.http_client.clone(),
2164                listen_key: self.listen_key.clone(),
2165                recovery_listen_key: self.recovery_listen_key.clone(),
2166                ws_client: self.ws_client.clone(),
2167                ws_task: self.ws_task.clone(),
2168                recovery_lock: self.recovery_lock.clone(),
2169                ws_build_params,
2170                dispatch_ctx,
2171                recovery_tx: recovery_tx.clone(),
2172            };
2173            let cancel = self.cancellation_token.clone();
2174
2175            self.session_tasks.spawn(async move {
2176                run_recovery_driver(
2177                    recovery_ctx,
2178                    recovery_rx,
2179                    cancel,
2180                    dispatch_user_stream_message,
2181                )
2182                .await;
2183            })?;
2184        }
2185
2186        // Request initial account state
2187        let account_state = self
2188            .refresh_account_state()
2189            .await
2190            .context("failed to request Binance Futures account state")?;
2191
2192        if !account_state.balances.is_empty() {
2193            log::debug!(
2194                "Received account state with {} balance(s) and {} margin(s)",
2195                account_state.balances.len(),
2196                account_state.margins.len()
2197            );
2198        }
2199
2200        self.emitter.send_account_state(account_state);
2201
2202        crate::common::execution::await_account_registered(&self.core, self.core.account_id, 30.0)
2203            .await?;
2204
2205        // Connect WS trading client (primary order transport for USD-M)
2206        if let Some(ref mut ws_trading) = self.ws_trading_client {
2207            match ws_trading.connect().await {
2208                Ok(()) => {
2209                    log::debug!("Connected to Binance Futures WS trading API");
2210
2211                    let ws_trading_clone = ws_trading.clone();
2212                    let emitter = self.emitter.clone();
2213                    let account_id = self.core.account_id;
2214                    let clock = self.clock;
2215                    let dispatch_state = self.dispatch_state.clone();
2216
2217                    self.session_tasks.spawn(async move {
2218                        while let Some(msg) = ws_trading_clone.recv().await {
2219                            dispatch_ws_trading_message(
2220                                msg,
2221                                &emitter,
2222                                account_id,
2223                                clock,
2224                                &dispatch_state,
2225                            );
2226                        }
2227                    })?;
2228                }
2229                Err(e) => {
2230                    log::warn!(
2231                        "Failed to connect WS trading API: {e}. \
2232                         Order operations will use HTTP fallback"
2233                    );
2234                }
2235            }
2236        }
2237
2238        let refresh_secs = self.config.instrument_refresh_interval_secs;
2239        if refresh_secs > 0 {
2240            let http_client = self.http_client.clone();
2241            let provider = self.config.instrument_provider.clone();
2242
2243            self.session_tasks.spawn(async move {
2244                let mut interval = tokio::time::interval(Duration::from_secs(refresh_secs));
2245                interval.tick().await;
2246
2247                loop {
2248                    interval.tick().await;
2249
2250                    match http_client.request_instruments_with_config(&provider).await {
2251                        Ok(instruments) => log::debug!(
2252                            "Refreshed Binance Futures execution instruments: count={}",
2253                            instruments.len()
2254                        ),
2255                        Err(e) => {
2256                            log::warn!("Binance Futures execution instrument refresh failed: {e}");
2257                        }
2258                    }
2259                }
2260            })?;
2261        }
2262
2263            Ok(())
2264        }
2265        .await;
2266
2267        if let Err(e) = connect_result {
2268            self.recovery_tx.take();
2269            self.cancellation_token.cancel();
2270            self.abort_session_tasks();
2271            self.abort_pending_tasks();
2272
2273            if let Some(client) = self.ws_client.lock().as_ref() {
2274                client.begin_shutdown();
2275            }
2276
2277            if let Some(client) = self.ws_trading_client.as_ref() {
2278                client.begin_shutdown();
2279            }
2280
2281            if let Some(ref mut ws_trading) = self.ws_trading_client
2282                && let Err(e) = ws_trading.disconnect().await
2283            {
2284                self.shutdown_errors.push(format!(
2285                    "Binance Futures trading WebSocket shutdown failed: {e}"
2286                ));
2287            }
2288
2289            let session_drained = match self.finish_session_tasks().await {
2290                Ok(()) => true,
2291                Err(e) => {
2292                    let drained = matches!(e, TaskShutdownError::Join(_));
2293                    self.shutdown_errors.push(format!(
2294                        "Failed to terminate Binance Futures session tasks: {e}"
2295                    ));
2296                    drained
2297                }
2298            };
2299
2300            if session_drained && let Err(e) = self.await_dispatch_task().await {
2301                self.shutdown_errors.push(e.to_string());
2302            }
2303
2304            let ws_client = self.ws_client.lock().clone();
2305            if let Some(mut ws_client) = ws_client {
2306                match ws_client.close().await {
2307                    Ok(()) => *self.ws_client.lock() = None,
2308                    Err(e) => self.shutdown_errors.push(format!(
2309                        "Binance Futures stream close after failed startup failed: {e}"
2310                    )),
2311                }
2312            }
2313
2314            if let Err(e) = self
2315                .close_listen_key_slot(
2316                    &self.listen_key,
2317                    "failed to close listen key after failed startup",
2318                )
2319                .await
2320            {
2321                self.shutdown_errors.push(e.to_string());
2322            }
2323
2324            if let Err(e) = self
2325                .close_listen_key_slot(
2326                    &self.recovery_listen_key,
2327                    "failed to close recovery listen key after failed startup",
2328                )
2329                .await
2330            {
2331                self.shutdown_errors.push(e.to_string());
2332            }
2333
2334            if let Err(e) = self.await_pending_tasks().await {
2335                self.shutdown_errors.push(e.to_string());
2336            }
2337
2338            if self.shutdown_errors.is_empty() {
2339                return Err(e);
2340            }
2341            let shutdown_errors = std::mem::take(&mut self.shutdown_errors);
2342            return Err(e.context(format!(
2343                "Binance Futures startup teardown failed: {}",
2344                shutdown_errors.join("; ")
2345            )));
2346        }
2347
2348        setup_guard.disarm();
2349        self.core.set_connected();
2350        log::info!("Connected: client_id={}", self.core.client_id);
2351        Ok(())
2352    }
2353
2354    async fn disconnect(&mut self) -> anyhow::Result<()> {
2355        // Drop the recovery tx so the driver exits its recv loop
2356        self.recovery_tx.take();
2357
2358        // Cancel all background tasks
2359        self.cancellation_token.cancel();
2360        self.abort_session_tasks();
2361        self.abort_pending_tasks();
2362
2363        if let Some(client) = self.ws_client.lock().as_ref() {
2364            client.begin_shutdown();
2365        }
2366
2367        if let Some(client) = self.ws_trading_client.as_ref() {
2368            client.begin_shutdown();
2369        }
2370
2371        if let Some(ref mut ws_trading) = self.ws_trading_client
2372            && let Err(e) = ws_trading.disconnect().await
2373        {
2374            self.shutdown_errors.push(format!(
2375                "Binance Futures trading WebSocket shutdown failed: {e}"
2376            ));
2377        }
2378
2379        let session_drained = match self.finish_session_tasks().await {
2380            Ok(()) => true,
2381            Err(e) => {
2382                let drained = matches!(e, TaskShutdownError::Join(_));
2383                self.shutdown_errors.push(format!(
2384                    "Failed to terminate Binance Futures session tasks: {e}"
2385                ));
2386                drained
2387            }
2388        };
2389
2390        if session_drained && let Err(e) = self.await_dispatch_task().await {
2391            self.shutdown_errors.push(e.to_string());
2392        }
2393
2394        // Close WebSocket
2395        let ws_client = self.ws_client.lock().clone();
2396        if let Some(mut ws_client) = ws_client {
2397            match ws_client.close().await {
2398                Ok(()) => *self.ws_client.lock() = None,
2399                Err(e) => {
2400                    self.shutdown_errors
2401                        .push(format!("Binance Futures stream close failed: {e}"));
2402                }
2403            }
2404        }
2405
2406        // Close listen key
2407        if let Err(e) = self
2408            .close_listen_key_slot(&self.listen_key, "failed to close listen key")
2409            .await
2410        {
2411            self.shutdown_errors.push(e.to_string());
2412        }
2413
2414        if let Err(e) = self
2415            .close_listen_key_slot(
2416                &self.recovery_listen_key,
2417                "failed to close recovery listen key",
2418            )
2419            .await
2420        {
2421            self.shutdown_errors.push(e.to_string());
2422        }
2423
2424        if let Err(e) = self.await_pending_tasks().await {
2425            self.shutdown_errors.push(e.to_string());
2426        }
2427
2428        let unresolved = self.unresolved_cancellations().await;
2429        self.dispatch_state
2430            .cancels_unresolved
2431            .store(unresolved.iter().copied().collect());
2432
2433        if !unresolved.is_empty() {
2434            let error = format!(
2435                "Unresolved cancellations at shutdown: client order IDs {unresolved:?}; venue orders may remain open"
2436            );
2437            log::error!("{error}");
2438            self.shutdown_errors.push(error);
2439        }
2440
2441        self.core.set_disconnected();
2442
2443        if !self.shutdown_errors.is_empty() {
2444            let shutdown_errors = std::mem::take(&mut self.shutdown_errors);
2445            anyhow::bail!(
2446                "Binance Futures shutdown failed: {}",
2447                shutdown_errors.join("; ")
2448            );
2449        }
2450        log::info!("Disconnected: client_id={}", self.core.client_id);
2451        Ok(())
2452    }
2453
2454    async fn generate_order_status_report(
2455        &self,
2456        cmd: &GenerateOrderStatusReport,
2457    ) -> anyhow::Result<Option<OrderStatusReport>> {
2458        let Some(instrument_id) = cmd.instrument_id else {
2459            log::warn!("generate_order_status_report requires instrument_id: {cmd}");
2460            return Ok(None);
2461        };
2462        let Some(instrument) = self.http_client.instrument_reconciliation(&instrument_id) else {
2463            if self.is_instrument_out_of_scope(instrument_id) {
2464                log::debug!(
2465                    "Dropping out-of-scope historical Binance Futures order for instrument {instrument_id}"
2466                );
2467                return Ok(None);
2468            }
2469
2470            anyhow::bail!(
2471                "Binance Futures order request has unresolved instrument {instrument_id}"
2472            );
2473        };
2474
2475        let symbol = format_binance_symbol(&instrument_id);
2476        let order_id = cmd
2477            .venue_order_id
2478            .as_ref()
2479            .map(|id| {
2480                id.inner()
2481                    .parse::<i64>()
2482                    .context("failed to parse venue_order_id as numeric")
2483            })
2484            .transpose()?;
2485        let orig_client_order_id = cmd
2486            .client_order_id
2487            .map(|id| encode_broker_id(&id, BINANCE_NAUTILUS_FUTURES_BROKER_ID));
2488
2489        let mut builder = BinanceOrderQueryParamsBuilder::default();
2490        builder.symbol(symbol);
2491
2492        if let Some(oid) = order_id {
2493            builder.order_id(oid);
2494        }
2495
2496        if let Some(ref coid) = orig_client_order_id {
2497            builder.orig_client_order_id(coid.clone());
2498        }
2499        let params = builder.build().map_err(|e| anyhow::anyhow!("{e}"))?;
2500
2501        let price_precision = instrument.price_precision();
2502        let size_precision = instrument.size_precision();
2503        let ts_init = self.clock.get_time_ns();
2504        let algo_lookup = self.resolve_algo_lookup(cmd.client_order_id, cmd.params.as_ref());
2505
2506        if algo_lookup == BinanceFuturesAlgoLookup::AlgoId {
2507            let algo_order = self
2508                .http_client
2509                .query_algo_order_with_history(
2510                    instrument_id,
2511                    cmd.client_order_id,
2512                    cmd.venue_order_id,
2513                )
2514                .await?;
2515
2516            return match algo_order {
2517                Some(result) => Ok(Some(create_algo_order_status_report(
2518                    &result,
2519                    self.core.account_id,
2520                    instrument_id,
2521                    price_precision,
2522                    size_precision,
2523                    self.config.treat_expired_as_canceled,
2524                    self.config.use_position_ids,
2525                    ts_init,
2526                )?)),
2527                None => {
2528                    log::debug!("Algo order query returned no matching order");
2529                    Ok(None)
2530                }
2531            };
2532        }
2533
2534        match self.http_client.query_order(&params).await {
2535            Ok(order) => {
2536                let report = order.to_order_status_report(
2537                    self.core.account_id,
2538                    instrument_id,
2539                    price_precision,
2540                    size_precision,
2541                    self.config.treat_expired_as_canceled,
2542                    ts_init,
2543                )?;
2544                let venue_position_id = make_venue_position_id(
2545                    self.config.use_position_ids,
2546                    instrument_id,
2547                    order.position_side,
2548                )?;
2549                Ok(Some(with_venue_position_id(report, venue_position_id)))
2550            }
2551            Err(BinanceFuturesHttpError::BinanceError { code: -2013, .. }) => {
2552                if algo_lookup == BinanceFuturesAlgoLookup::Skip {
2553                    log::debug!("Skipping Algo Service fallback for known regular order");
2554                    return Ok(None);
2555                }
2556
2557                // A conditional order may expose its Algo Service `algoId` before triggering and
2558                // its matching-engine `actualOrderId` afterwards. Only an explicit ID-kind hint
2559                // makes a venue ID safe for Algo Service lookup; cached conditional orders retain
2560                // their existing clientAlgoId fallback.
2561                let algo_venue_order_id = if algo_lookup == BinanceFuturesAlgoLookup::AlgoId {
2562                    cmd.venue_order_id
2563                } else {
2564                    None
2565                };
2566                let algo_order = self
2567                    .http_client
2568                    .query_algo_order_with_history(
2569                        instrument_id,
2570                        cmd.client_order_id,
2571                        algo_venue_order_id,
2572                    )
2573                    .await?;
2574
2575                match algo_order {
2576                    Some(result) => Ok(Some(create_algo_order_status_report(
2577                        &result,
2578                        self.core.account_id,
2579                        instrument_id,
2580                        price_precision,
2581                        size_precision,
2582                        self.config.treat_expired_as_canceled,
2583                        self.config.use_position_ids,
2584                        ts_init,
2585                    )?)),
2586                    None => {
2587                        log::debug!("Algo order query returned no matching order");
2588                        Ok(None)
2589                    }
2590                }
2591            }
2592            Err(e) => Err(e.into()),
2593        }
2594    }
2595
2596    async fn generate_order_status_reports(
2597        &self,
2598        cmd: &GenerateOrderStatusReports,
2599    ) -> anyhow::Result<Vec<OrderStatusReport>> {
2600        let ts_init = self.clock.get_time_ns();
2601
2602        if cmd.open_only {
2603            let mut reports = self
2604                .generate_open_order_status_reports(cmd.instrument_id, ts_init)
2605                .await?;
2606
2607            if reports.iter().any(|report| {
2608                report.quantity_free_close_position_side.is_some()
2609                    && !report.report.quantity.is_positive()
2610            }) {
2611                let position_cmd = GeneratePositionStatusReportsBuilder::default()
2612                    .log_receipt_level(cmd.log_receipt_level)
2613                    .ts_init(ts_init)
2614                    .instrument_id(cmd.instrument_id)
2615                    .build()
2616                    .map_err(|e| anyhow::anyhow!("{e}"))?;
2617                let position_reports = self.generate_position_status_reports(&position_cmd).await?;
2618                restore_close_position_quantities(&mut reports, &position_reports);
2619            }
2620
2621            crate::common::execution::log_report_receipt(
2622                reports.len(),
2623                "OrderStatusReport",
2624                cmd.log_receipt_level,
2625            );
2626            return Ok(reports.into_iter().map(|report| report.report).collect());
2627        }
2628
2629        let mut reports = Vec::new();
2630
2631        if let Some(instrument_id) = cmd.instrument_id
2632            && self
2633                .http_client
2634                .instrument_reconciliation(&instrument_id)
2635                .is_none()
2636        {
2637            if self.is_instrument_out_of_scope(instrument_id) {
2638                log::debug!(
2639                    "Dropping out-of-scope Binance Futures order request for instrument {instrument_id}"
2640                );
2641                return Ok(reports);
2642            }
2643
2644            log::warn!(
2645                "Dropping historical Binance Futures orders for unresolved instrument {instrument_id}"
2646            );
2647            return Ok(reports);
2648        }
2649
2650        if let Some(instrument_id) = cmd.instrument_id {
2651            let Some(instrument) = self.http_client.instrument_reconciliation(&instrument_id)
2652            else {
2653                if self.is_instrument_out_of_scope(instrument_id) {
2654                    log::debug!(
2655                        "Dropping out-of-scope historical Binance Futures orders for instrument {instrument_id}"
2656                    );
2657                } else {
2658                    log::warn!(
2659                        "Dropping historical Binance Futures orders for unresolved instrument {instrument_id}"
2660                    );
2661                }
2662                return Ok(reports);
2663            };
2664            let symbol = format_binance_symbol(&instrument_id);
2665            let start_time = cmd
2666                .start
2667                .map(|t| t.as_i64() / NANOSECONDS_IN_MILLISECOND as i64);
2668            let end_time = cmd
2669                .end
2670                .map(|t| t.as_i64() / NANOSECONDS_IN_MILLISECOND as i64);
2671
2672            let mut builder = BinanceAllOrdersParamsBuilder::default();
2673            builder.symbol(symbol);
2674
2675            if let Some(st) = start_time {
2676                builder.start_time(st);
2677            }
2678
2679            if let Some(et) = end_time {
2680                builder.end_time(et);
2681            }
2682            let params = builder.build().map_err(|e| anyhow::anyhow!("{e}"))?;
2683
2684            let orders = self.http_client.query_all_orders(&params).await?;
2685
2686            for order in orders {
2687                let report = order.to_order_status_report(
2688                    self.core.account_id,
2689                    instrument.id(),
2690                    instrument.price_precision(),
2691                    instrument.size_precision(),
2692                    self.config.treat_expired_as_canceled,
2693                    ts_init,
2694                )?;
2695                let venue_position_id = make_venue_position_id(
2696                    self.config.use_position_ids,
2697                    instrument.id(),
2698                    order.position_side,
2699                )?;
2700                reports.push(with_venue_position_id(report, venue_position_id));
2701            }
2702        }
2703
2704        crate::common::execution::log_report_receipt(
2705            reports.len(),
2706            "OrderStatusReport",
2707            cmd.log_receipt_level,
2708        );
2709        Ok(reports)
2710    }
2711
2712    async fn generate_fill_reports(
2713        &self,
2714        cmd: GenerateFillReports,
2715    ) -> anyhow::Result<Vec<FillReport>> {
2716        let Some(instrument_id) = cmd.instrument_id else {
2717            log::warn!("generate_fill_reports requires instrument_id for Binance Futures");
2718            return Ok(Vec::new());
2719        };
2720        let Some(instrument) = self.http_client.instrument_reconciliation(&instrument_id) else {
2721            if self.is_instrument_out_of_scope(instrument_id) {
2722                log::debug!(
2723                    "Dropping out-of-scope historical Binance Futures fills for instrument {instrument_id}"
2724                );
2725            } else {
2726                log::warn!(
2727                    "Dropping historical Binance Futures fills for unresolved instrument {instrument_id}"
2728                );
2729            }
2730            return Ok(Vec::new());
2731        };
2732
2733        let symbol = format_binance_symbol(&instrument_id);
2734        let mut trades = Vec::new();
2735        let mut seen_trade_ids = AHashSet::new();
2736        let order_id = cmd
2737            .venue_order_id
2738            .map(|id| {
2739                id.inner()
2740                    .parse::<i64>()
2741                    .context("invalid fill report venue order ID")
2742            })
2743            .transpose()?;
2744        let requested_end_time = cmd
2745            .end
2746            .map(|end| end.as_i64() / NANOSECONDS_IN_MILLISECOND as i64);
2747
2748        if let Some(start) = cmd.start {
2749            let query_start_time = start.as_i64() / NANOSECONDS_IN_MILLISECOND as i64;
2750            let query_end_time = requested_end_time.unwrap_or_else(|| {
2751                self.clock.get_time_ns().as_i64() / NANOSECONDS_IN_MILLISECOND as i64
2752            });
2753            anyhow::ensure!(
2754                query_start_time <= query_end_time,
2755                "fill report start time must not exceed end time"
2756            );
2757            let complete_start = user_trades_complete_start(cmd.ts_init, self.clock.get_time_ns());
2758            anyhow::ensure!(
2759                start >= complete_start,
2760                "Binance Futures fill report range is incomplete: start {start} precedes complete-history boundary {complete_start}"
2761            );
2762            let mut window_start = query_start_time;
2763
2764            loop {
2765                let window_end = window_start
2766                    .saturating_add(USER_TRADES_MAX_INTERVAL_MS)
2767                    .min(query_end_time);
2768                let mut from_id = None;
2769
2770                loop {
2771                    let mut builder = BinanceUserTradesParamsBuilder::default();
2772                    builder.symbol(symbol.clone());
2773                    builder.limit(USER_TRADES_PAGE_LIMIT);
2774                    if let Some(order_id) = order_id {
2775                        builder.order_id(order_id);
2776                    }
2777
2778                    if let Some(cursor) = from_id {
2779                        builder.from_id(cursor);
2780                    } else {
2781                        builder.start_time(window_start);
2782                        builder.end_time(window_end);
2783                    }
2784                    let params = builder.build().map_err(|e| anyhow::anyhow!("{e}"))?;
2785                    let page = self.http_client.query_user_trades(&params).await?;
2786
2787                    if page.is_empty() {
2788                        break;
2789                    }
2790
2791                    let page_len = page.len();
2792                    let max_trade_id = page.iter().map(|trade| trade.id).max().unwrap();
2793                    let passed_window_end = page.iter().any(|trade| trade.time > window_end);
2794
2795                    trades.extend(page.into_iter().filter(|trade| {
2796                        trade.time >= window_start
2797                            && trade.time <= window_end
2798                            && seen_trade_ids.insert(trade.id)
2799                    }));
2800
2801                    if page_len < USER_TRADES_PAGE_LIMIT as usize || passed_window_end {
2802                        break;
2803                    }
2804
2805                    let next_from_id = max_trade_id
2806                        .checked_add(1)
2807                        .context("Binance user trade ID overflow during pagination")?;
2808                    anyhow::ensure!(
2809                        from_id.is_none_or(|cursor| next_from_id > cursor),
2810                        "Binance user-trades pagination made no progress"
2811                    );
2812                    from_id = Some(next_from_id);
2813                }
2814
2815                if window_end >= query_end_time {
2816                    break;
2817                }
2818                window_start = window_end.saturating_add(1);
2819            }
2820        } else {
2821            anyhow::ensure!(
2822                cmd.end.is_none(),
2823                "Binance Futures fill report end time requires start time for a complete range"
2824            );
2825            let mut from_id = 0;
2826
2827            loop {
2828                let mut builder = BinanceUserTradesParamsBuilder::default();
2829                builder.symbol(symbol.clone());
2830                builder.from_id(from_id);
2831                builder.limit(USER_TRADES_PAGE_LIMIT);
2832                if let Some(order_id) = order_id {
2833                    builder.order_id(order_id);
2834                }
2835                let params = builder.build().map_err(|e| anyhow::anyhow!("{e}"))?;
2836                let page = self.http_client.query_user_trades(&params).await?;
2837
2838                if page.is_empty() {
2839                    break;
2840                }
2841
2842                let page_len = page.len();
2843                let max_trade_id = page.iter().map(|trade| trade.id).max().unwrap();
2844                let passed_end = requested_end_time
2845                    .is_some_and(|end_time| page.iter().any(|trade| trade.time > end_time));
2846
2847                trades.extend(page.into_iter().filter(|trade| {
2848                    requested_end_time.is_none_or(|end_time| trade.time <= end_time)
2849                        && seen_trade_ids.insert(trade.id)
2850                }));
2851
2852                if page_len < USER_TRADES_PAGE_LIMIT as usize || passed_end {
2853                    break;
2854                }
2855
2856                let next_from_id = max_trade_id
2857                    .checked_add(1)
2858                    .context("Binance user trade ID overflow during pagination")?;
2859                anyhow::ensure!(
2860                    next_from_id > from_id,
2861                    "Binance user-trades pagination made no progress"
2862                );
2863                from_id = next_from_id;
2864            }
2865        }
2866
2867        trades.sort_unstable_by_key(|trade| (trade.time, trade.id));
2868        let ts_init = self.clock.get_time_ns();
2869
2870        let mut reports = Vec::new();
2871
2872        for trade in trades {
2873            if order_id.is_some_and(|order_id| trade.order_id != order_id) {
2874                continue;
2875            }
2876            let venue_position_id = make_venue_position_id(
2877                self.config.use_position_ids,
2878                instrument.id(),
2879                trade.position_side,
2880            )?;
2881            let mut report = trade.to_fill_report(
2882                self.core.account_id,
2883                instrument.id(),
2884                instrument.price_precision(),
2885                instrument.size_precision(),
2886                self.config.bnfcr_currency,
2887                ts_init,
2888            )?;
2889            report.venue_position_id = venue_position_id;
2890            reports.push(report);
2891        }
2892
2893        crate::common::execution::log_report_receipt(
2894            reports.len(),
2895            "FillReport",
2896            cmd.log_receipt_level,
2897        );
2898        Ok(reports)
2899    }
2900
2901    async fn generate_position_status_reports(
2902        &self,
2903        cmd: &GeneratePositionStatusReports,
2904    ) -> anyhow::Result<Vec<PositionStatusReport>> {
2905        if let Some(instrument_id) = cmd.instrument_id
2906            && self
2907                .http_client
2908                .instrument_reconciliation(&instrument_id)
2909                .is_none()
2910        {
2911            if self.is_instrument_out_of_scope(instrument_id) {
2912                log::debug!(
2913                    "Dropping out-of-scope Binance Futures position request for instrument {instrument_id}"
2914                );
2915                return Ok(Vec::new());
2916            }
2917            anyhow::bail!(
2918                "Binance Futures position request has unresolved instrument {instrument_id}"
2919            );
2920        }
2921        let symbol = cmd.instrument_id.map(|id| format_binance_symbol(&id));
2922
2923        let mut builder = BinancePositionRiskParamsBuilder::default();
2924
2925        if let Some(s) = symbol {
2926            builder.symbol(s);
2927        }
2928        let params = builder.build().map_err(|e| anyhow::anyhow!("{e}"))?;
2929
2930        let positions = self.http_client.query_positions(&params).await?;
2931
2932        let mut reports = Vec::new();
2933        let mut position_reports_failed = 0usize;
2934
2935        for position in positions {
2936            let instrument_id = format_instrument_id(&position.symbol, self.product_type);
2937
2938            if self.is_instrument_out_of_scope(instrument_id) {
2939                log::debug!(
2940                    "Dropping out-of-scope Binance Futures position for instrument {instrument_id}"
2941                );
2942                continue;
2943            }
2944
2945            let position_amt = match position.position_amt.parse::<Decimal>() {
2946                Ok(value) => value,
2947                Err(e) => {
2948                    log::warn!(
2949                        "Failed to parse Futures position_amt for symbol={}: {e}",
2950                        position.symbol
2951                    );
2952                    position_reports_failed += 1;
2953                    continue;
2954                }
2955            };
2956
2957            if position_amt.is_zero() {
2958                if self.config.use_position_ids {
2959                    let position_side = match position.position_side {
2960                        Some(BinancePositionSide::Long) => PositionSide::Long,
2961                        Some(BinancePositionSide::Short) => PositionSide::Short,
2962                        _ => continue,
2963                    };
2964
2965                    let venue_position_id =
2966                        make_venue_position_id(true, instrument_id, position.position_side)?
2967                            .expect("hedge position sides always produce an ID");
2968
2969                    if let Err(e) = self.ensure_cached_position_id_compatible(
2970                        instrument_id,
2971                        position_side,
2972                        venue_position_id,
2973                    ) {
2974                        log::warn!(
2975                            "Failed to create Futures position report for symbol={}: {e}",
2976                            position.symbol
2977                        );
2978                        position_reports_failed += 1;
2979                    }
2980                }
2981                continue;
2982            }
2983
2984            let Some(instrument) = self.http_client.instrument_reconciliation(&instrument_id)
2985            else {
2986                log::warn!(
2987                    "Failed to create Futures position report for symbol={}: instrument {instrument_id} is unresolved",
2988                    position.symbol
2989                );
2990                position_reports_failed += 1;
2991                continue;
2992            };
2993
2994            match self.create_position_report(
2995                &position,
2996                instrument.id(),
2997                instrument.size_precision(),
2998            ) {
2999                Ok(report) => reports.push(report),
3000                Err(e) => {
3001                    log::warn!(
3002                        "Failed to create Futures position report for symbol={}: {e}",
3003                        position.symbol
3004                    );
3005                    position_reports_failed += 1;
3006                }
3007            }
3008        }
3009
3010        anyhow::ensure!(
3011            position_reports_failed == 0,
3012            "Failed to process {position_reports_failed} Binance Futures position reports",
3013        );
3014
3015        crate::common::execution::log_report_receipt(
3016            reports.len(),
3017            "PositionStatusReport",
3018            cmd.log_receipt_level,
3019        );
3020        Ok(reports)
3021    }
3022
3023    async fn generate_mass_status(
3024        &self,
3025        lookback_mins: Option<u64>,
3026    ) -> anyhow::Result<Option<ExecutionMassStatus>> {
3027        log::info!("Generating ExecutionMassStatus (lookback_mins={lookback_mins:?})");
3028
3029        let ts_now = self.clock.get_time_ns();
3030
3031        let requested_start = lookback_mins
3032            .map(DurationNanos::try_from_mins)
3033            .transpose()?
3034            .map(|lookback| ts_now.saturating_sub(lookback));
3035        let complete_start = user_trades_complete_start(ts_now, ts_now);
3036        let (report_start, fill_start, mut reports_complete) = match requested_start {
3037            Some(start) if start < complete_start => (complete_start, Some(complete_start), false),
3038            Some(start) => (start, Some(start), true),
3039            None => (complete_start, None, false),
3040        };
3041
3042        let position_cmd = GeneratePositionStatusReportsBuilder::default()
3043            .log_receipt_level(LogLevel::Off)
3044            .ts_init(ts_now)
3045            .start(Some(report_start))
3046            .build()
3047            .map_err(|e| anyhow::anyhow!("{e}"))?;
3048
3049        let (mut open_order_reports, position_reports) = tokio::try_join!(
3050            self.generate_open_order_status_reports(None, ts_now),
3051            self.generate_position_status_reports(&position_cmd),
3052        )?;
3053        restore_close_position_quantities(&mut open_order_reports, &position_reports);
3054        let order_reports: Vec<_> = open_order_reports
3055            .into_iter()
3056            .map(|report| report.report)
3057            .collect();
3058
3059        let mut instrument_ids: Vec<_> = order_reports
3060            .iter()
3061            .map(|report| report.instrument_id)
3062            .chain(position_reports.iter().map(|report| report.instrument_id))
3063            .collect();
3064        {
3065            let cache = self.core.cache();
3066            instrument_ids.extend(cache.external_order_claim_instrument_ids(None));
3067            instrument_ids.extend(
3068                cache
3069                    .orders_open(
3070                        Some(&BINANCE_VENUE),
3071                        None,
3072                        None,
3073                        Some(&self.core.account_id),
3074                        None,
3075                    )
3076                    .into_iter()
3077                    .map(|order| order.instrument_id()),
3078            );
3079            instrument_ids.extend(
3080                cache
3081                    .orders_inflight(
3082                        Some(&BINANCE_VENUE),
3083                        None,
3084                        None,
3085                        Some(&self.core.account_id),
3086                        None,
3087                    )
3088                    .into_iter()
3089                    .map(|order| order.instrument_id()),
3090            );
3091            instrument_ids.extend(
3092                cache
3093                    .positions_open(
3094                        Some(&BINANCE_VENUE),
3095                        None,
3096                        None,
3097                        Some(&self.core.account_id),
3098                        None,
3099                    )
3100                    .into_iter()
3101                    .map(|position| position.instrument_id),
3102            );
3103            instrument_ids.retain(|instrument_id| {
3104                cache.instrument(instrument_id).is_none_or(|instrument| {
3105                    is_instrument_for_product(instrument, self.product_type)
3106                })
3107            });
3108        }
3109
3110        let selector =
3111            BinanceInstrumentSelector::new(&self.config.instrument_provider, self.product_type)?;
3112        instrument_ids.extend(
3113            self.http_client
3114                .instrument_ids_reconciliation()
3115                .into_iter()
3116                .filter(|id| selector.is_explicit(*id, &format_binance_symbol(id))),
3117        );
3118
3119        instrument_ids.retain(|id| {
3120            id.venue == *BINANCE_VENUE && !self.config.instrument_provider.excludes(*id)
3121        });
3122
3123        instrument_ids.sort_unstable();
3124        instrument_ids.dedup();
3125
3126        let mut order_reports: IndexMap<_, _> = order_reports
3127            .into_iter()
3128            .map(|report| (report.venue_order_id, report))
3129            .collect();
3130        let mut fill_reports = Vec::new();
3131
3132        for instrument_id in instrument_ids {
3133            if self
3134                .http_client
3135                .instrument_reconciliation(&instrument_id)
3136                .is_none()
3137            {
3138                if self.is_instrument_out_of_scope(instrument_id) {
3139                    log::debug!(
3140                        "Dropping out-of-scope historical Binance Futures fills for instrument {instrument_id}"
3141                    );
3142                } else {
3143                    log::warn!(
3144                        "Dropping historical Binance Futures fills for unresolved instrument {instrument_id}"
3145                    );
3146                    reports_complete = false;
3147                }
3148                continue;
3149            }
3150
3151            match self
3152                .generate_order_history(instrument_id, report_start, ts_now)
3153                .await
3154            {
3155                Ok(history) => crate::common::execution::merge_order_history(
3156                    &mut order_reports,
3157                    history,
3158                    Some(report_start),
3159                    ts_now,
3160                ),
3161
3162                Err(e) => {
3163                    log::warn!(
3164                        "Failed to recover Binance Futures history for {instrument_id}: {e}"
3165                    );
3166                    reports_complete = false;
3167                }
3168            }
3169
3170            let fill_cmd = GenerateFillReportsBuilder::default()
3171                .log_receipt_level(LogLevel::Off)
3172                .ts_init(ts_now)
3173                .instrument_id(Some(instrument_id))
3174                .start(fill_start)
3175                .end(fill_start.map(|_| ts_now))
3176                .build()
3177                .map_err(|e| anyhow::anyhow!("{e}"))?;
3178            fill_reports.extend(
3179                self.generate_fill_reports(fill_cmd)
3180                    .await?
3181                    .into_iter()
3182                    .filter(|report| report.ts_event >= report_start && report.ts_event <= ts_now),
3183            );
3184        }
3185
3186        log::info!("Received {} OrderStatusReports", order_reports.len());
3187        log::info!("Received {} FillReports", fill_reports.len());
3188        log::info!("Received {} PositionReports", position_reports.len());
3189
3190        let mut mass_status = ExecutionMassStatus::new(
3191            self.core.client_id,
3192            self.core.account_id,
3193            *BINANCE_VENUE,
3194            ts_now,
3195            None,
3196        );
3197
3198        self.dispatch_state
3199            .restore_terminal_fills(&order_reports, &fill_reports);
3200        mass_status.add_order_reports(order_reports.into_values().collect());
3201        mass_status.add_fill_reports(fill_reports);
3202        mass_status.add_position_reports(position_reports);
3203        mass_status.set_report_window(Some(report_start), reports_complete);
3204
3205        Ok(Some(mass_status))
3206    }
3207
3208    fn query_account(&self, _cmd: QueryAccount) -> anyhow::Result<()> {
3209        self.update_account_state();
3210        Ok(())
3211    }
3212
3213    fn query_order(&self, cmd: QueryOrder) -> anyhow::Result<()> {
3214        log::debug!("query_order: client_order_id={}", cmd.client_order_id);
3215
3216        let algo_lookup = self.resolve_algo_lookup(Some(cmd.client_order_id), cmd.params.as_ref());
3217        let http_client = self.http_client.clone();
3218        let command = cmd;
3219        let emitter = self.emitter.clone();
3220        let account_id = self.core.account_id;
3221        let clock = self.clock;
3222
3223        let symbol = format_binance_symbol(&command.instrument_id);
3224        let order_id = command
3225            .venue_order_id
3226            .map(|id| {
3227                id.inner()
3228                    .parse::<i64>()
3229                    .map_err(|e| anyhow::anyhow!("failed to parse venue_order_id: {e}"))
3230            })
3231            .transpose()?;
3232        let orig_client_order_id = Some(encode_broker_id(
3233            &command.client_order_id,
3234            BINANCE_NAUTILUS_FUTURES_BROKER_ID,
3235        ));
3236        let (price_precision, size_precision) =
3237            self.get_instrument_precision(command.instrument_id)?;
3238        let treat_expired_as_canceled = self.config.treat_expired_as_canceled;
3239        let use_position_ids = self.config.use_position_ids;
3240
3241        self.spawn_task("query_order", async move {
3242            if algo_lookup == BinanceFuturesAlgoLookup::AlgoId {
3243                match http_client
3244                    .query_algo_order_with_history(
3245                        command.instrument_id,
3246                        Some(command.client_order_id),
3247                        command.venue_order_id,
3248                    )
3249                    .await
3250                {
3251                    Ok(Some(result)) => {
3252                        let report = create_algo_order_status_report(
3253                            &result,
3254                            account_id,
3255                            command.instrument_id,
3256                            price_precision,
3257                            size_precision,
3258                            treat_expired_as_canceled,
3259                            use_position_ids,
3260                            clock.get_time_ns(),
3261                        )?;
3262                        emitter.send_order_status_report(report);
3263                    }
3264                    Ok(None) => log::warn!("Algo order query returned no matching order"),
3265                    Err(e) => log::warn!("Failed to query algo order status: {e}"),
3266                }
3267
3268                return Ok(());
3269            }
3270
3271            let mut builder = BinanceOrderQueryParamsBuilder::default();
3272            builder.symbol(symbol.clone());
3273
3274            if let Some(oid) = order_id {
3275                builder.order_id(oid);
3276            }
3277
3278            if let Some(coid) = orig_client_order_id {
3279                builder.orig_client_order_id(coid);
3280            }
3281            let params = builder
3282                .build()
3283                .map_err(|e| anyhow::anyhow!("failed to build order query params: {e}"))?;
3284
3285            let result = http_client.query_order(&params).await;
3286
3287            match result {
3288                Ok(order) => {
3289                    let ts_init = clock.get_time_ns();
3290                    let report = order.to_order_status_report(
3291                        account_id,
3292                        command.instrument_id,
3293                        price_precision,
3294                        size_precision,
3295                        treat_expired_as_canceled,
3296                        ts_init,
3297                    )?;
3298                    let venue_position_id = make_venue_position_id(
3299                        use_position_ids,
3300                        command.instrument_id,
3301                        order.position_side,
3302                    )?;
3303
3304                    emitter.send_order_status_report(with_venue_position_id(
3305                        report,
3306                        venue_position_id,
3307                    ));
3308                }
3309                Err(BinanceFuturesHttpError::BinanceError { code: -2013, .. }) => {
3310                    if algo_lookup == BinanceFuturesAlgoLookup::Skip {
3311                        log::debug!("Skipping Algo Service fallback for known regular order");
3312                        return Ok(());
3313                    }
3314
3315                    // Untriggered algo orders (STOP_MARKET, STOP_LIMIT, MIT, LIT,
3316                    // TRAILING_STOP_MARKET) live in the Binance Futures Algo Service
3317                    // and return -2013 on the regular order endpoint. Mirror the
3318                    // reconciliation path (`generate_order_status_report`) so live
3319                    // inflight checks resolve them instead of exhausting retries into
3320                    // `OrderRejected(reason='INFLIGHT_TIMEOUT')`.
3321                    let algo_venue_order_id = if algo_lookup == BinanceFuturesAlgoLookup::AlgoId {
3322                        command.venue_order_id
3323                    } else {
3324                        None
3325                    };
3326
3327                    match http_client
3328                        .query_algo_order_with_history(
3329                            command.instrument_id,
3330                            Some(command.client_order_id),
3331                            algo_venue_order_id,
3332                        )
3333                        .await
3334                    {
3335                        Ok(Some(result)) => {
3336                            let report = create_algo_order_status_report(
3337                                &result,
3338                                account_id,
3339                                command.instrument_id,
3340                                price_precision,
3341                                size_precision,
3342                                treat_expired_as_canceled,
3343                                use_position_ids,
3344                                clock.get_time_ns(),
3345                            )?;
3346                            emitter.send_order_status_report(report);
3347                        }
3348                        Ok(None) => log::warn!("Algo order query returned no matching order"),
3349                        Err(e) => log::warn!("Algo order query also failed: {e}"),
3350                    }
3351                }
3352                Err(e) => log::warn!("Failed to query order status: {e}"),
3353            }
3354
3355            Ok(())
3356        });
3357
3358        Ok(())
3359    }
3360
3361    fn generate_account_state(
3362        &self,
3363        balances: Vec<AccountBalance>,
3364        margins: Vec<MarginBalance>,
3365        reported: bool,
3366        ts_event: UnixNanos,
3367        info: Option<Params>,
3368    ) -> anyhow::Result<()> {
3369        self.emitter
3370            .emit_account_state(balances, margins, reported, ts_event, info);
3371        Ok(())
3372    }
3373
3374    fn start(&mut self) -> anyhow::Result<()> {
3375        if self.core.is_started() {
3376            return Ok(());
3377        }
3378
3379        self.emitter.set_sender(get_exec_event_sender());
3380        self.core.set_started();
3381
3382        log::info!(
3383            "Started: client_id={}, account_id={}, account_type={:?}, environment={:?}",
3384            self.core.client_id,
3385            self.core.account_id,
3386            self.core.account_type,
3387            self.config.environment,
3388        );
3389        Ok(())
3390    }
3391
3392    fn stop(&mut self) -> anyhow::Result<()> {
3393        let was_started = self.core.is_started();
3394        self.core.set_stopped();
3395        self.begin_generation_shutdown();
3396
3397        if was_started {
3398            log::info!("Stopped: client_id={}", self.core.client_id);
3399        }
3400        Ok(())
3401    }
3402
3403    fn reset(&mut self) -> anyhow::Result<()> {
3404        self.begin_generation_shutdown();
3405        Ok(())
3406    }
3407
3408    fn dispose(&mut self) -> anyhow::Result<()> {
3409        self.begin_generation_shutdown();
3410        Ok(())
3411    }
3412
3413    fn submit_order(&self, cmd: SubmitOrder) -> anyhow::Result<()> {
3414        let order = self.core.cache().try_order_owned(&cmd.client_order_id)?;
3415
3416        if order.is_closed() {
3417            let client_order_id = order.client_order_id();
3418            log::warn!("Cannot submit closed order {client_order_id}");
3419            return Ok(());
3420        }
3421
3422        let validated = match validate_order(self, &cmd, &order) {
3423            Ok(validated) => validated,
3424            Err(reason) => {
3425                self.emitter.emit_order_denied(&order, &reason.to_string());
3426                return Ok(());
3427            }
3428        };
3429
3430        self.submit_order_internal(
3431            &cmd,
3432            validated.lifetime,
3433            validated.position_side,
3434            validated.venue_position_id,
3435        )
3436    }
3437
3438    fn submit_order_list(&self, cmd: SubmitOrderList) -> anyhow::Result<()> {
3439        if cmd.order_list.client_order_ids.is_empty() {
3440            log::debug!("submit_order_list called with empty order list");
3441            return Ok(());
3442        }
3443
3444        let orders = self.core.get_orders_for_list(&cmd.order_list)?;
3445
3446        let (batch_items, venue_position_ids) = match self.prepare_order_list(&cmd, &orders) {
3447            Ok(prepared) => prepared,
3448            Err(reason) => {
3449                for order in &orders {
3450                    self.emitter.emit_order_denied(order, &reason);
3451                }
3452                return Ok(());
3453            }
3454        };
3455
3456        for (order, venue_position_id) in orders.iter().zip(venue_position_ids) {
3457            self.dispatch_state.order_identities.insert(
3458                order.client_order_id(),
3459                OrderIdentity {
3460                    instrument_id: order.instrument_id(),
3461                    strategy_id: order.strategy_id(),
3462                    order_side: order.order_side(),
3463                    order_type: order.order_type(),
3464                    price: order.price(),
3465                    quantity: order.quantity(),
3466                    is_quote_quantity: false,
3467                    venue_position_id,
3468                },
3469            );
3470            self.emitter.emit_order_submitted(order);
3471        }
3472
3473        let http_client = self.http_client.clone();
3474        let emitter = self.emitter.clone();
3475        let trader_id = self.core.trader_id;
3476        let account_id = self.core.account_id;
3477        let clock = self.clock;
3478        let dispatch_state = self.dispatch_state.clone();
3479
3480        self.spawn_task("submit_order_list", async move {
3481            match http_client.submit_order_list(&batch_items).await {
3482                Ok(results) => {
3483                    for (order, result) in orders.iter().zip(results.iter()) {
3484                        dispatch_order_list_result(&emitter, &dispatch_state, order, result, clock);
3485                    }
3486                }
3487                Err(e) => {
3488                    let e = anyhow::Error::new(e);
3489                    let failure = e.downcast_ref::<BinanceFuturesHttpError>().map_or_else(
3490                        || CommandFailure::Ambiguous(e.to_string()),
3491                        classify_futures_http_failure,
3492                    );
3493
3494                    match failure {
3495                        CommandFailure::Ambiguous(reason) => {
3496                            log::warn!(
3497                                "Ambiguous order-list submit failure, awaiting reconciliation: {reason}"
3498                            );
3499                        }
3500                        CommandFailure::NotSent(reason) | CommandFailure::VenueRejected(reason) => {
3501                            let ts_now = clock.get_time_ns();
3502                            let due_post_only = classify_submit_order_error(&e);
3503                            let reason = sanitize_reason(&reason);
3504
3505                            for order in &orders {
3506                                let client_order_id = order.client_order_id();
3507                                let rejected = OrderRejected::new(
3508                                    trader_id,
3509                                    order.strategy_id(),
3510                                    order.instrument_id(),
3511                                    client_order_id,
3512                                    account_id,
3513                                    format!("submit-order-list-error: {reason}").into(),
3514                                    UUID4::new(),
3515                                    ts_now,
3516                                    ts_now,
3517                                    false,
3518                                    due_post_only,
3519                                );
3520                                dispatch_state.cleanup_terminal(client_order_id);
3521                                emitter.send_order_event(OrderEventAny::Rejected(rejected));
3522                            }
3523                        }
3524                    }
3525
3526                    return Err(e);
3527                }
3528            }
3529            Ok(())
3530        });
3531
3532        Ok(())
3533    }
3534
3535    fn modify_order(&self, cmd: ModifyOrder) -> anyhow::Result<()> {
3536        let order = {
3537            let cache = self.core.cache();
3538            cache.order(&cmd.client_order_id).map(|o| o.clone())
3539        };
3540
3541        let Some(order) = order else {
3542            log::warn!(
3543                "Cannot modify order {}: not found in cache",
3544                cmd.client_order_id
3545            );
3546            let ts_init = self.clock.get_time_ns();
3547
3548            let mut rejected = OrderModifyDenied::new(
3549                self.core.trader_id,
3550                cmd.strategy_id,
3551                cmd.instrument_id,
3552                cmd.client_order_id,
3553                "Order not found in cache for modify".into(),
3554                UUID4::new(),
3555                ts_init, // no venue timestamp, rejected locally
3556                ts_init,
3557                cmd.venue_order_id,
3558                Some(self.core.account_id),
3559            );
3560            rejected.causation_id = Some(cmd.command_id);
3561
3562            self.emitter
3563                .send_order_event(OrderEventAny::ModifyDenied(rejected));
3564            return Ok(());
3565        };
3566
3567        let http_client = self.http_client.clone();
3568        let emitter = self.emitter.clone();
3569        let trader_id = self.core.trader_id;
3570        let account_id = self.core.account_id;
3571        let instrument_id = cmd.instrument_id;
3572        let venue_order_id = cmd.venue_order_id;
3573        let client_order_id = Some(cmd.client_order_id);
3574        let order_side = order.order_side();
3575        let quantity = cmd.quantity.unwrap_or_else(|| order.quantity());
3576        let price = cmd.price.or_else(|| order.price());
3577
3578        let Some(price) = price else {
3579            log::warn!(
3580                "Cannot modify order {}: price required",
3581                cmd.client_order_id
3582            );
3583            let ts_init = self.clock.get_time_ns();
3584
3585            let mut rejected = OrderModifyDenied::new(
3586                self.core.trader_id,
3587                cmd.strategy_id,
3588                cmd.instrument_id,
3589                cmd.client_order_id,
3590                "Price required for order modification".into(),
3591                UUID4::new(),
3592                ts_init, // no venue timestamp, rejected locally
3593                ts_init,
3594                cmd.venue_order_id,
3595                Some(self.core.account_id),
3596            );
3597            rejected.causation_id = Some(cmd.command_id);
3598
3599            self.emitter
3600                .send_order_event(OrderEventAny::ModifyDenied(rejected));
3601            return Ok(());
3602        };
3603        let command = cmd;
3604        let clock = self.clock;
3605
3606        if self.ws_trading_active() {
3607            let ws_client = self.ws_trading_client.as_ref().unwrap().clone();
3608            let dispatch_state = self.dispatch_state.clone();
3609
3610            let binance_side = BinanceSide::try_from(order_side)?;
3611            let orig_client_order_id =
3612                client_order_id.map(|id| encode_broker_id(&id, BINANCE_NAUTILUS_FUTURES_BROKER_ID));
3613
3614            let mut modify_builder = BinanceModifyOrderParamsBuilder::default();
3615            modify_builder
3616                .symbol(format_binance_symbol(&instrument_id))
3617                .side(binance_side)
3618                .quantity(quantity.to_string())
3619                .price(price.to_string());
3620
3621            if let Some(venue_id) = venue_order_id {
3622                let order_id: i64 = venue_id
3623                    .inner()
3624                    .parse()
3625                    .context("failed to parse venue_order_id as numeric")?;
3626                modify_builder.order_id(order_id);
3627            }
3628
3629            if let Some(client_id) = orig_client_order_id {
3630                modify_builder.orig_client_order_id(client_id);
3631            }
3632
3633            let params = modify_builder
3634                .build()
3635                .context("failed to build modify params")?;
3636
3637            // Pre-register before sending to avoid response racing the insert
3638            let request_id = ws_client.next_request_id();
3639            dispatch_state.pending_requests.insert(
3640                request_id.clone(),
3641                PendingRequest {
3642                    command_id: Some(command.command_id),
3643                    client_order_id: command.client_order_id,
3644                    venue_order_id,
3645                    operation: PendingOperation::Modify,
3646                },
3647            );
3648
3649            let http_client = self.http_client.clone();
3650            self.spawn_task("modify_order_ws", async move {
3651                let mut params = params;
3652                http_client
3653                    .inner()
3654                    .resolve_order_identity(
3655                        &params.symbol,
3656                        &mut params.order_id,
3657                        &mut params.orig_client_order_id,
3658                        true,
3659                    )
3660                    .await
3661                    .inspect_err(|e| {
3662                        dispatch_state.pending_requests.remove(&request_id);
3663                        let ts_now = clock.get_time_ns();
3664
3665                        let mut rejected = OrderModifyDenied::new(
3666                            trader_id,
3667                            command.strategy_id,
3668                            command.instrument_id,
3669                            command.client_order_id,
3670                            format!(
3671                                "modify identity lookup failed before submission: {}",
3672                                sanitize_reason(&e.to_string())
3673                            )
3674                            .into(),
3675                            UUID4::new(),
3676                            ts_now,
3677                            ts_now,
3678                            command.venue_order_id,
3679                            Some(account_id),
3680                        );
3681                        rejected.causation_id = Some(command.command_id);
3682                        emitter.send_order_event(OrderEventAny::ModifyDenied(rejected));
3683                    })?;
3684
3685                let result = ws_client
3686                    .modify_order_with_id(request_id.clone(), params)
3687                    .await;
3688
3689                if let Err(e) = result {
3690                    dispatch_state.pending_requests.remove(&request_id);
3691                    log::warn!(
3692                        "WS modify request failed for {}: {e}",
3693                        command.client_order_id
3694                    );
3695                    anyhow::bail!("WS modify order failed: {e}");
3696                }
3697                Ok(())
3698            });
3699
3700            return Ok(());
3701        }
3702
3703        let dispatch_state = self.dispatch_state.clone();
3704        self.spawn_task("modify_order", async move {
3705            let result = http_client
3706                .modify_order(
3707                    account_id,
3708                    instrument_id,
3709                    venue_order_id,
3710                    client_order_id,
3711                    order_side,
3712                    quantity,
3713                    price,
3714                )
3715                .await;
3716
3717            match result {
3718                Ok(report) => {
3719                    if dispatch_state.record_order_update(command.client_order_id, report.venue_order_id, quantity, price, None) != Some(true) {
3720                        return Ok(());
3721                    }
3722                    let ts_now = clock.get_time_ns();
3723                    let updated_event = OrderUpdated::new(
3724                        trader_id,
3725                        command.strategy_id,
3726                        command.instrument_id,
3727                        command.client_order_id,
3728                        quantity,
3729                        UUID4::new(),
3730                        ts_now,
3731                        ts_now,
3732                        false,
3733                        Some(report.venue_order_id),
3734                        Some(account_id),
3735                        Some(price),
3736                        None,
3737                        None,
3738                        false, // is_quote_quantity
3739                    );
3740
3741                    emitter.send_order_event(OrderEventAny::Updated(updated_event));
3742                }
3743                Err(e) => {
3744                    let failure = e.downcast_ref::<BinanceFuturesHttpError>().map_or_else(
3745                        || CommandFailure::Ambiguous(e.to_string()),
3746                        classify_futures_http_failure,
3747                    );
3748
3749                    match failure {
3750                        CommandFailure::Ambiguous(reason) => {
3751                            log::warn!(
3752                                "Ambiguous modify failure for {}, awaiting reconciliation: {reason}",
3753                                command.client_order_id
3754                            );
3755                        }
3756                        CommandFailure::NotSent(reason) => {
3757                            let ts_now = clock.get_time_ns();
3758
3759                            let mut rejected = OrderModifyDenied::new(
3760                                trader_id,
3761                                command.strategy_id,
3762                                command.instrument_id,
3763                                command.client_order_id,
3764                                format!("modify-order-error: {}", sanitize_reason(&reason)).into(),
3765                                UUID4::new(),
3766                                ts_now,
3767                                ts_now,
3768                                command.venue_order_id,
3769                                Some(account_id),
3770                            );
3771                            rejected.causation_id = Some(command.command_id);
3772
3773                            emitter.send_order_event(OrderEventAny::ModifyDenied(rejected));
3774                        }
3775                        CommandFailure::VenueRejected(reason) => {
3776                            let ts_now = clock.get_time_ns();
3777
3778                            let mut rejected = OrderModifyRejected::new(
3779                                trader_id,
3780                                command.strategy_id,
3781                                command.instrument_id,
3782                                command.client_order_id,
3783                                format!("modify-order-error: {}", sanitize_reason(&reason)).into(),
3784                                UUID4::new(),
3785                                ts_now,
3786                                ts_now,
3787                                false,
3788                                command.venue_order_id,
3789                                Some(account_id),
3790                            );
3791                            rejected.causation_id = Some(command.command_id);
3792
3793                            emitter.send_order_event(OrderEventAny::ModifyRejected(rejected));
3794                        }
3795                    }
3796
3797                    anyhow::bail!("Modify order failed: {e}");
3798                }
3799            }
3800
3801            Ok(())
3802        });
3803
3804        Ok(())
3805    }
3806
3807    fn cancel_order(&self, cmd: CancelOrder) -> anyhow::Result<()> {
3808        self.cancel_order_internal(&cmd);
3809        Ok(())
3810    }
3811
3812    fn cancel_all_orders(&self, cmd: CancelAllOrders) -> anyhow::Result<()> {
3813        if cmd.order_side.is_some() {
3814            return self.cancel_all_orders_for_side(&cmd);
3815        }
3816
3817        let http_client = self.http_client.clone();
3818        let instrument_id = cmd.instrument_id;
3819        let cancels_unresolved = self.dispatch_state.cancels_unresolved.clone();
3820
3821        let orders: Vec<_> = self
3822            .core
3823            .cache()
3824            .orders_refs(
3825                Some(&self.core.venue),
3826                Some(&instrument_id),
3827                None,
3828                Some(&self.core.account_id),
3829                None,
3830            )
3831            .into_iter()
3832            .filter(|order| self.owns_order(order) && (order.is_open() || order.is_inflight()))
3833            .map(|order| order.client_order_id())
3834            .collect();
3835
3836        cancels_unresolved.rcu(|ids| ids.extend(orders.iter().copied()));
3837
3838        // USD-M Futures WS Trading API does not expose an openOrders.cancelAll
3839        // method, so regular and algo cancel-all both go through HTTP.
3840        self.spawn_task("cancel_all_orders", async move {
3841            match http_client.cancel_all_orders(instrument_id).await {
3842                Ok(_) => {
3843                    log::debug!("Cancel all regular orders request accepted for {instrument_id}");
3844                }
3845                Err(e) => {
3846                    log::error!("Failed to cancel all regular orders for {instrument_id}: {e}");
3847                }
3848            }
3849
3850            match http_client.cancel_all_algo_orders(instrument_id).await {
3851                Ok(()) => {
3852                    log::debug!("Cancel all algo orders request accepted for {instrument_id}");
3853                }
3854                Err(e) => {
3855                    log::error!("Failed to cancel all algo orders for {instrument_id}: {e}");
3856                }
3857            }
3858
3859            Ok(())
3860        });
3861
3862        Ok(())
3863    }
3864
3865    fn batch_cancel_orders(&self, cmd: BatchCancelOrders) -> anyhow::Result<()> {
3866        const BATCH_SIZE: usize = 10;
3867
3868        if cmd.cancels.is_empty() {
3869            return Ok(());
3870        }
3871
3872        let http_client = self.http_client.clone();
3873        let command = cmd;
3874
3875        let emitter = self.emitter.clone();
3876        let trader_id = self.core.trader_id;
3877        let account_id = self.core.account_id;
3878        let clock = self.clock;
3879        let cancels_unresolved = self.dispatch_state.cancels_unresolved.clone();
3880
3881        cancels_unresolved.rcu(|ids| {
3882            ids.extend(command.cancels.iter().map(|cancel| cancel.client_order_id));
3883        });
3884
3885        self.spawn_task("batch_cancel_orders", async move {
3886            let symbol = format_binance_symbol(&command.instrument_id);
3887
3888            for chunk in command.cancels.chunks(BATCH_SIZE) {
3889                let mut order_id_batch = Vec::new();
3890                let mut client_order_id_batch = Vec::new();
3891
3892                for cancel in chunk {
3893                    if let Some(venue_order_id) = cancel.venue_order_id {
3894                        let order_id = venue_order_id.inner().parse::<i64>().unwrap_or(0);
3895                        if order_id != 0 {
3896                            order_id_batch.push((
3897                                BatchCancelItem::by_order_id(symbol.clone(), order_id),
3898                                cancel.clone(),
3899                            ));
3900                            continue;
3901                        }
3902                    }
3903
3904                    client_order_id_batch.push((
3905                        BatchCancelItem::by_client_order_id(
3906                            symbol.clone(),
3907                            encode_broker_id(
3908                                &cancel.client_order_id,
3909                                BINANCE_NAUTILUS_FUTURES_BROKER_ID,
3910                            ),
3911                        ),
3912                        cancel.clone(),
3913                    ));
3914                }
3915
3916                for batch in [order_id_batch, client_order_id_batch] {
3917                    if batch.is_empty() {
3918                        continue;
3919                    }
3920
3921                    let batch_len = batch.len();
3922                    let (batch_items, batch_cancels): (Vec<_>, Vec<_>) =
3923                        batch.into_iter().unzip();
3924
3925                    match http_client.batch_cancel_orders(&batch_items).await {
3926                        Ok(results) => {
3927                            for (cancel, result) in batch_cancels.iter().zip(results.iter()) {
3928                                match result {
3929                                    BatchOrderResult::Success(response) => {
3930                                        cancels_unresolved.remove(&cancel.client_order_id);
3931                                        let venue_order_id =
3932                                            VenueOrderId::new(response.order_id.to_string());
3933                                        let canceled_event = OrderCanceled::new(
3934                                            trader_id,
3935                                            cancel.strategy_id,
3936                                            cancel.instrument_id,
3937                                            cancel.client_order_id,
3938                                            UUID4::new(),
3939                                            cancel.ts_init,
3940                                            clock.get_time_ns(),
3941                                            false,
3942                                            Some(venue_order_id),
3943                                            Some(account_id),
3944                                            None,
3945                                        );
3946
3947                                        emitter.send_order_event(OrderEventAny::Canceled(
3948                                            canceled_event,
3949                                        ));
3950                                    }
3951                                    BatchOrderResult::Error(error) => {
3952                                        let reason = format!("batch-cancel-error: code={}, msg={}", error.code, error.msg);
3953
3954                                        let reason = match classify_futures_batch_failure(error, reason) {
3955                                            CommandFailure::Ambiguous(reason) => {
3956                                                log::warn!("Ambiguous batch cancel for {}: {reason}", cancel.client_order_id);
3957                                                continue;
3958                                            }
3959                                            CommandFailure::NotSent(reason) => {
3960
3961                                                let mut denied = OrderCancelDenied::new(
3962                                                    trader_id,
3963                                                    cancel.strategy_id,
3964                                                    cancel.instrument_id,
3965                                                    cancel.client_order_id,
3966                                                    reason.into(),
3967                                                    UUID4::new(),
3968                                                    clock.get_time_ns(),
3969                                                    cancel.ts_init,
3970                                                    cancel.venue_order_id,
3971                                                    Some(account_id),
3972                                                );
3973                                                denied.causation_id = Some(cancel.command_id);
3974                                                emitter.send_order_event(OrderEventAny::CancelDenied(denied));
3975                                                continue;
3976                                            }
3977                                            CommandFailure::VenueRejected(reason) => reason,
3978                                        };
3979
3980
3981                                        let mut rejected = OrderCancelRejected::new(
3982                                            trader_id,
3983                                            cancel.strategy_id,
3984                                            cancel.instrument_id,
3985                                            cancel.client_order_id,
3986                                            reason.into(),
3987                                            UUID4::new(),
3988                                            clock.get_time_ns(),
3989                                            cancel.ts_init,
3990                                            false,
3991                                            cancel.venue_order_id,
3992                                            Some(account_id),
3993                                        );
3994                                        rejected.causation_id = Some(cancel.command_id);
3995
3996                                        emitter.send_order_event(OrderEventAny::CancelRejected(
3997                                            rejected,
3998                                        ));
3999                                    }
4000                                }
4001                            }
4002                        }
4003                        Err(e) => {
4004                            match classify_futures_http_failure(&e) {
4005                                CommandFailure::NotSent(reason) => {
4006                                    for cancel in &batch_cancels {
4007                                        let ts_now = clock.get_time_ns();
4008
4009                                        let mut rejected = OrderCancelDenied::new(
4010                                            trader_id,
4011                                            cancel.strategy_id,
4012                                            cancel.instrument_id,
4013                                            cancel.client_order_id,
4014                                            format!("batch-cancel-error: {}", sanitize_reason(&reason)).into(),
4015                                            UUID4::new(),
4016                                            ts_now,
4017                                            ts_now,
4018                                            cancel.venue_order_id,
4019                                            Some(account_id),
4020                                        );
4021                                        rejected.causation_id = Some(cancel.command_id);
4022                                        emitter.send_order_event(OrderEventAny::CancelDenied(
4023                                            rejected,
4024                                        ));
4025                                    }
4026                                }
4027                                CommandFailure::VenueRejected(reason)
4028                                | CommandFailure::Ambiguous(reason) => {
4029                                    log::warn!(
4030                                        "Batch cancel request failure for {batch_len} orders, awaiting reconciliation: {reason}",
4031                                    );
4032                                }
4033                            }
4034                        }
4035                    }
4036                }
4037            }
4038
4039            Ok(())
4040        });
4041
4042        Ok(())
4043    }
4044}
4045
4046impl BinanceFuturesExecutionClient {
4047    fn prepare_order_list(
4048        &self,
4049        cmd: &SubmitOrderList,
4050        orders: &[OrderAny],
4051    ) -> Result<(Vec<BatchOrderItem>, Vec<Option<PositionId>>), String> {
4052        if let Some(order) = orders.iter().find(|order| order.is_closed()) {
4053            return Err(format!(
4054                "Cannot submit closed order {}",
4055                order.client_order_id()
4056            ));
4057        }
4058
4059        if cmd
4060            .params
4061            .as_ref()
4062            .and_then(|params| params.get_bool("rpi"))
4063            .unwrap_or(false)
4064        {
4065            return Err(
4066                "rpi is only supported for individual Binance Futures order submission".to_string(),
4067            );
4068        }
4069
4070        let close_position = cmd
4071            .params
4072            .as_ref()
4073            .and_then(|params| params.get_bool(PARAMS_CLOSE_POSITION))
4074            .unwrap_or(false);
4075        let price_match = cmd
4076            .params
4077            .as_ref()
4078            .and_then(|params| params.get_str("price_match"))
4079            .map(BinancePriceMatch::from_param)
4080            .transpose()
4081            .map_err(|e| e.to_string())?;
4082        let batch_items = build_futures_order_list_batch(
4083            orders,
4084            self.is_hedge_mode(),
4085            close_position,
4086            price_match,
4087            self.product_type,
4088            self.config.use_gtd,
4089            self.clock.get_time_ns(),
4090        )?;
4091
4092        let venue_position_ids = orders
4093            .iter()
4094            .map(|order| {
4095                resolve_order_position_identity(
4096                    self.is_hedge_mode(),
4097                    self.config.use_position_ids,
4098                    order,
4099                )
4100                .map(|(_, venue_position_id)| venue_position_id)
4101            })
4102            .collect::<Result<Vec<_>, _>>()
4103            .map_err(|reason| reason.to_string())?;
4104
4105        for id in &venue_position_ids {
4106            validate_submit_position_id(cmd.position_id, *id)
4107                .map_err(|reason| reason.to_string())?;
4108        }
4109
4110        Ok((batch_items, venue_position_ids))
4111    }
4112
4113    async fn unresolved_cancellations(&self) -> Vec<ClientOrderId> {
4114        let (orders, mut unresolved) = {
4115            let cache = self.core.cache();
4116            let cancels = self.dispatch_state.cancels_unresolved.load();
4117            let mut orders: Vec<_> = cancels
4118                .iter()
4119                .filter_map(|id| cache.order_owned(id))
4120                .collect();
4121            orders.extend(
4122                cache
4123                    .orders_refs(
4124                        Some(&self.core.venue),
4125                        None,
4126                        None,
4127                        Some(&self.core.account_id),
4128                        None,
4129                    )
4130                    .into_iter()
4131                    .filter(|order| {
4132                        self.owns_order(order)
4133                            && order.is_pending_cancel()
4134                            && !cancels.contains(&order.client_order_id())
4135                    })
4136                    .map(|order| order.cloned()),
4137            );
4138
4139            let unresolved: Vec<_> = cancels
4140                .iter()
4141                .filter(|id| !cache.order_exists(id))
4142                .copied()
4143                .collect();
4144            (orders, unresolved)
4145        };
4146
4147        // Shutdown permits bounded status reads to distinguish terminal orders from unknown outcomes
4148        let deadline = tokio::time::Instant::now() + Duration::from_secs(2);
4149
4150        for order in orders {
4151            let client_order_id = order.client_order_id();
4152            if order.is_closed() {
4153                // Reconciliation can infer a terminal state without a terminal venue report
4154                let terminal_reconciliation =
4155                    order.events().iter().rev().find_map(|event| match event {
4156                        OrderEventAny::Canceled(event) => Some(event.reconciliation),
4157                        OrderEventAny::Rejected(event) => Some(event.reconciliation),
4158                        _ => None,
4159                    });
4160
4161                if !matches!(
4162                    order.status(),
4163                    OrderStatus::Canceled | OrderStatus::Rejected
4164                ) || terminal_reconciliation != Some(true)
4165                {
4166                    continue;
4167                }
4168            }
4169
4170            let command = GenerateOrderStatusReport::new(
4171                UUID4::new(),
4172                self.clock.get_time_ns(),
4173                Some(order.instrument_id()),
4174                Some(client_order_id),
4175                order.venue_order_id(),
4176                None,
4177                None,
4178            );
4179            let confirmed = matches!(
4180                tokio::time::timeout_at(deadline, self.generate_order_status_report(&command)).await,
4181                Ok(Ok(Some(report))) if report.order_status.is_closed()
4182                    && report.client_order_id == Some(client_order_id)
4183            );
4184
4185            if !confirmed {
4186                unresolved.push(client_order_id);
4187            }
4188        }
4189
4190        unresolved.sort();
4191        unresolved
4192    }
4193
4194    fn owns_order(&self, order: &OrderAny) -> bool {
4195        !order.strategy_id().is_external()
4196            && self.core.cache().client_id(&order.client_order_id()) == Some(&self.core.client_id)
4197    }
4198}
4199
4200fn dispatch_order_list_result(
4201    emitter: &ExecutionEventEmitter,
4202    dispatch_state: &WsDispatchState,
4203    order: &OrderAny,
4204    result: &BatchOrderResult,
4205    clock: &'static AtomicTime,
4206) {
4207    match result {
4208        BatchOrderResult::Success(response) => {
4209            log::debug!(
4210                "Order-list leg submit accepted: client_order_id={}, venue_order_id={}",
4211                order.client_order_id(),
4212                response.order_id,
4213            );
4214        }
4215        BatchOrderResult::Error(error) => {
4216            let reason = format!(
4217                "submit-order-list-error: code={}, msg={}",
4218                error.code, error.msg
4219            );
4220
4221            let reason = match classify_futures_batch_failure(error, reason) {
4222                CommandFailure::Ambiguous(reason) => {
4223                    log::warn!(
4224                        "Ambiguous order-list leg submit for {}, awaiting reconciliation: {reason}",
4225                        order.client_order_id(),
4226                    );
4227                    return;
4228                }
4229                CommandFailure::NotSent(reason) | CommandFailure::VenueRejected(reason) => reason,
4230            };
4231
4232            let ts_now = clock.get_time_ns();
4233            let client_order_id = order.client_order_id();
4234
4235            let rejected = OrderRejected::new(
4236                emitter.trader_id(),
4237                order.strategy_id(),
4238                order.instrument_id(),
4239                client_order_id,
4240                emitter.account_id(),
4241                reason.into(),
4242                UUID4::new(),
4243                ts_now,
4244                ts_now,
4245                false,
4246                false,
4247            );
4248            dispatch_state.cleanup_terminal(client_order_id);
4249            emitter.send_order_event(OrderEventAny::Rejected(rejected));
4250        }
4251    }
4252}
4253
4254fn validate_order(
4255    client: &BinanceFuturesExecutionClient,
4256    cmd: &SubmitOrder,
4257    order: &OrderAny,
4258) -> Result<ValidatedOrder, OrderDeniedReason> {
4259    order_type_to_binance_futures(order.order_type()).map_err(|_| {
4260        OrderDeniedReason::UnsupportedOrderType {
4261            order_type: order.order_type(),
4262        }
4263    })?;
4264
4265    if let Some(offset_type) = order.trailing_offset_type() {
4266        if offset_type != TrailingOffsetType::BasisPoints {
4267            return Err(OrderDeniedReason::UnsupportedTrailingOffsetType { offset_type });
4268        }
4269
4270        if let Some(offset) = order.trailing_offset() {
4271            trailing_offset_to_callback_rate(offset).map_err(|e| {
4272                OrderDeniedReason::ValidationFailed {
4273                    detail: format!("invalid trailing offset {offset}: {e}"),
4274                }
4275            })?;
4276        }
4277    }
4278
4279    let close_position = cmd
4280        .params
4281        .as_ref()
4282        .and_then(|params| params.get_bool(PARAMS_CLOSE_POSITION))
4283        .unwrap_or(false);
4284
4285    let rpi = cmd
4286        .params
4287        .as_ref()
4288        .and_then(|params| params.get_bool("rpi"))
4289        .unwrap_or(false);
4290
4291    if rpi {
4292        if client.product_type != BinanceProductType::UsdM {
4293            return Err(OrderDeniedReason::ValidationFailed {
4294                detail: "rpi is only supported for Binance USD-M Futures".to_string(),
4295            });
4296        }
4297
4298        if order.order_type() != OrderType::Limit {
4299            return Err(OrderDeniedReason::ValidationFailed {
4300                detail: "rpi is only supported for LIMIT orders".to_string(),
4301            });
4302        }
4303
4304        if !order.is_post_only() {
4305            return Err(OrderDeniedReason::ValidationFailed {
4306                detail: "rpi requires post_only=true".to_string(),
4307            });
4308        }
4309    }
4310
4311    if close_position {
4312        let order_type = order.order_type();
4313
4314        if !order.is_reduce_only() {
4315            return Err(OrderDeniedReason::ValidationFailed {
4316                detail: "`close_position` requires `reduce_only=true` on the Nautilus order"
4317                    .to_string(),
4318            });
4319        }
4320
4321        if !matches!(
4322            order_type,
4323            OrderType::StopMarket | OrderType::MarketIfTouched
4324        ) {
4325            return Err(OrderDeniedReason::ValidationFailed {
4326                detail: format!(
4327                    "`close_position` is not supported for order type {order_type:?} on Binance"
4328                ),
4329            });
4330        }
4331    }
4332
4333    if let Some(price_match) = cmd
4334        .params
4335        .as_ref()
4336        .and_then(|params| params.get_str("price_match"))
4337    {
4338        BinancePriceMatch::from_param(price_match).map_err(|e| {
4339            OrderDeniedReason::ValidationFailed {
4340                detail: format!("invalid price_match '{price_match}': {e}"),
4341            }
4342        })?;
4343        let order_type = order.order_type();
4344
4345        if order.is_post_only() {
4346            return Err(OrderDeniedReason::unsupported_post_only());
4347        }
4348
4349        if order_type != OrderType::Limit {
4350            return Err(OrderDeniedReason::ValidationFailed {
4351                detail: format!("price_match is not supported for order type {order_type:?}"),
4352            });
4353        }
4354    }
4355
4356    let lifetime = determine_futures_order_lifetime(
4357        client.product_type,
4358        order.order_type(),
4359        order.time_in_force(),
4360        order.expire_time(),
4361        order.is_post_only(),
4362        client.config.use_gtd,
4363        client.clock.get_time_ns(),
4364    )?;
4365
4366    if !order.is_post_only() || is_algo_order_type(order.order_type()) {
4367        BinanceTimeInForce::try_from(lifetime.time_in_force)
4368            .map_err(|_| OrderDeniedReason::UnsupportedTimeInForce(order.time_in_force()))?;
4369    }
4370    let (position_side, venue_position_id) = resolve_order_position_identity(
4371        client.is_hedge_mode(),
4372        client.config.use_position_ids,
4373        order,
4374    )?;
4375    validate_submit_position_id(cmd.position_id, venue_position_id)?;
4376
4377    Ok(ValidatedOrder {
4378        lifetime,
4379        position_side,
4380        venue_position_id,
4381    })
4382}
4383
4384struct ValidatedOrder {
4385    lifetime: FuturesOrderLifetime,
4386    position_side: Option<BinancePositionSide>,
4387    venue_position_id: Option<PositionId>,
4388}
4389
4390#[derive(Clone, Copy, Debug, Eq, PartialEq)]
4391enum BinanceFuturesAlgoLookup {
4392    Skip,
4393    AlgoId,
4394    ClientAlgoId,
4395}
4396
4397#[derive(Clone, Copy, Debug, Eq, PartialEq)]
4398struct FuturesOrderLifetime {
4399    time_in_force: TimeInForce,
4400    good_till_date: Option<i64>,
4401}
4402
4403struct OpenOrderStatusReport {
4404    report: OrderStatusReport,
4405    quantity_free_close_position_side: Option<PositionSide>,
4406}
4407
4408#[allow(
4409    clippy::too_many_arguments,
4410    reason = "the converter receives one cohesive set of report conversion inputs"
4411)]
4412fn create_algo_order_status_report(
4413    result: &BinanceFuturesAlgoOrderQueryResult,
4414    account_id: AccountId,
4415    instrument_id: InstrumentId,
4416    price_precision: u8,
4417    size_precision: u8,
4418    treat_expired_as_canceled: bool,
4419    use_position_ids: bool,
4420    ts_init: UnixNanos,
4421) -> anyhow::Result<OrderStatusReport> {
4422    let position_side = result
4423        .actual
4424        .as_ref()
4425        .and_then(|actual| actual.position_side)
4426        .or(result.algo.position_side);
4427    let venue_position_id = make_venue_position_id(use_position_ids, instrument_id, position_side)?;
4428
4429    if let Some(actual) = result.actual.as_ref() {
4430        match result.algo.to_order_status_report_with_actual(
4431            actual,
4432            account_id,
4433            instrument_id,
4434            price_precision,
4435            size_precision,
4436            treat_expired_as_canceled,
4437            ts_init,
4438        ) {
4439            Ok(report) => return Ok(with_venue_position_id(report, venue_position_id)),
4440            Err(e) => {
4441                log::warn!(
4442                    "Failed to convert matching-engine enrichment for algo order {}: {e}; falling back to Algo Service report",
4443                    result.algo.algo_id
4444                );
4445            }
4446        }
4447    }
4448
4449    let report = result.algo.to_order_status_report(
4450        account_id,
4451        instrument_id,
4452        price_precision,
4453        size_precision,
4454        ts_init,
4455    )?;
4456    Ok(with_venue_position_id(report, venue_position_id))
4457}
4458
4459fn user_trades_complete_start(ts_init: UnixNanos, ts_now: UnixNanos) -> UnixNanos {
4460    let oldest_reference = ts_now.saturating_sub(USER_TRADES_MAX_TS_INIT_AGE);
4461    ts_init
4462        .max(oldest_reference)
4463        .saturating_sub(USER_TRADES_COMPLETE_INTERVAL)
4464}
4465
4466async fn cancel_order_http(
4467    http_client: &BinanceFuturesHttpClient,
4468    instrument_id: InstrumentId,
4469    venue_order_id: Option<VenueOrderId>,
4470    client_order_id: ClientOrderId,
4471    use_algo_cancel: bool,
4472) -> anyhow::Result<()> {
4473    if !use_algo_cancel {
4474        return http_client
4475            .cancel_order(instrument_id, venue_order_id, Some(client_order_id))
4476            .await
4477            .map(|_| ());
4478    }
4479
4480    // The algo may have triggered before this session, so a regular cancel can still be needed
4481    let algo_err = match http_client.cancel_algo_order(client_order_id).await {
4482        Ok(()) => return Ok(()),
4483        Err(e) => e,
4484    };
4485
4486    if !should_retry_regular_cancel(client_order_id, &algo_err) {
4487        return Err(algo_err);
4488    }
4489
4490    log::debug!("Algo cancel failed, trying regular cancel: {algo_err}");
4491
4492    match http_client
4493        .cancel_order(instrument_id, venue_order_id, Some(client_order_id))
4494        .await
4495        .map(|_| ())
4496    {
4497        Err(e)
4498            if algo_err
4499                .downcast_ref::<BinanceFuturesHttpError>()
4500                .is_none_or(|e| {
4501                    matches!(
4502                        classify_futures_http_failure(e),
4503                        CommandFailure::Ambiguous(_)
4504                    )
4505                })
4506                || e.downcast_ref::<BinanceFuturesHttpError>()
4507                    .is_some_and(|e| {
4508                        matches!(classify_futures_http_failure(e), CommandFailure::NotSent(_))
4509                    }) =>
4510        {
4511            Err(algo_err)
4512        }
4513        result => result,
4514    }
4515}
4516
4517fn should_retry_regular_cancel(client_order_id: ClientOrderId, error: &anyhow::Error) -> bool {
4518    let encoded = encode_broker_id(&client_order_id, BINANCE_NAUTILUS_FUTURES_BROKER_ID);
4519
4520    let error = error
4521        .downcast_ref::<BinanceFuturesHttpError>()
4522        .map(|e| match e {
4523            BinanceFuturesHttpError::IdentityLookup(source) => source.as_ref(),
4524            e => e,
4525        });
4526
4527    legacy_client_order_id(&encoded, BINANCE_NAUTILUS_FUTURES_BROKER_ID).is_none()
4528        || matches!(
4529            error,
4530            Some(BinanceFuturesHttpError::BinanceError {
4531                code: -2011 | -2013,
4532                ..
4533            })
4534        )
4535}
4536
4537fn should_use_algo_cancel(is_algo: bool, is_triggered: bool, has_promoted_id: bool) -> bool {
4538    is_algo && !is_triggered && !has_promoted_id
4539}
4540
4541fn cancel_venue_order_id(
4542    is_algo: bool,
4543    venue_order_id: Option<VenueOrderId>,
4544    promoted_algo_order_id: Option<VenueOrderId>,
4545) -> Option<VenueOrderId> {
4546    if is_algo {
4547        promoted_algo_order_id
4548    } else {
4549        venue_order_id
4550    }
4551}
4552
4553fn is_instrument_for_product(instrument: &InstrumentAny, product_type: BinanceProductType) -> bool {
4554    match product_type {
4555        BinanceProductType::UsdM => {
4556            matches!(
4557                instrument,
4558                InstrumentAny::CryptoFuture(_)
4559                    | InstrumentAny::CryptoPerpetual(_)
4560                    | InstrumentAny::PerpetualContract(_)
4561            ) && !instrument.is_inverse()
4562        }
4563        BinanceProductType::CoinM => {
4564            matches!(
4565                instrument,
4566                InstrumentAny::CryptoFuture(_) | InstrumentAny::CryptoPerpetual(_)
4567            ) && instrument.is_inverse()
4568        }
4569        _ => false,
4570    }
4571}
4572
4573#[cfg(test)]
4574mod tests {
4575    use std::{
4576        cell::RefCell,
4577        collections::HashMap,
4578        rc::Rc,
4579        sync::{
4580            Arc,
4581            atomic::{AtomicUsize, Ordering},
4582        },
4583    };
4584
4585    use nautilus_common::{cache::Cache, clients::ExecutionClient, messages::ExecutionEvent};
4586    use nautilus_live::ExecutionClientCore;
4587    use nautilus_model::{
4588        enums::{AccountType, OmsType, OrderSide, OrderType},
4589        events::OrderEventAny,
4590        identifiers::{AccountId, ClientOrderId, InstrumentId, StrategyId, TraderId, VenueOrderId},
4591        instruments::stubs::{
4592            btcusd_bybit, crypto_future_btcusdt, crypto_perpetual_ethusdt, currency_pair_btcusdt,
4593            perpetual_contract_eurusd,
4594        },
4595        orders::{OrderTestBuilder, stubs::TestOrderEventStubs},
4596        types::{Price, Quantity},
4597    };
4598    use rstest::rstest;
4599
4600    use super::*;
4601    use crate::{
4602        common::{
4603            consts::{
4604                BINANCE_CLIENT_ID, BINANCE_STATUS_UNKNOWN_CODE, BINANCE_UNEXPECTED_RESPONSE_CODE,
4605                BINANCE_VENUE,
4606            },
4607            enums::BinanceProductType,
4608            testing::load_fixture_string,
4609        },
4610        config::BinanceExecutionClientConfig,
4611    };
4612
4613    fn http_error(code: i64) -> anyhow::Error {
4614        anyhow::Error::new(BinanceFuturesHttpError::BinanceError {
4615            code,
4616            message: format!("test error {code}"),
4617            status: 400,
4618            retry_after: None,
4619        })
4620    }
4621
4622    #[rstest]
4623    #[case(None, Some("BTCUSDT-PERP.BINANCE-LONG"))]
4624    #[case(Some("BTCUSDT-PERP.BINANCE-LONG"), Some("BTCUSDT-PERP.BINANCE-LONG"))]
4625    #[case(Some("P-VIRTUAL-LONG"), None)]
4626    fn test_validate_submit_position_id_accepts_compatible_identity(
4627        #[case] submitted_position_id: Option<&str>,
4628        #[case] venue_position_id: Option<&str>,
4629    ) {
4630        validate_submit_position_id(
4631            submitted_position_id.map(PositionId::from),
4632            venue_position_id.map(PositionId::from),
4633        )
4634        .unwrap();
4635    }
4636
4637    #[rstest]
4638    fn test_validate_submit_position_id_rejects_custom_venue_identity() {
4639        let error = validate_submit_position_id(
4640            Some(PositionId::from("P-VIRTUAL-LONG")),
4641            Some(PositionId::from("BTCUSDT-PERP.BINANCE-LONG")),
4642        )
4643        .unwrap_err();
4644
4645        assert_eq!(
4646            error.to_string(),
4647            "INVALID_POSITION_ID: P-VIRTUAL-LONG; conflicts with canonical Binance Futures venue position ID BTCUSDT-PERP.BINANCE-LONG; omit position_id while use_position_ids=true, or set use_position_ids=false for virtual hedging",
4648        );
4649    }
4650
4651    #[rstest]
4652    fn test_create_account_state_preserves_info_decimal_values() {
4653        let json = load_fixture_string("futures/http_json/account_info_v2.json");
4654        let mut account_info: BinanceFuturesAccountInfo = serde_json::from_str(&json).unwrap();
4655        account_info.total_wallet_balance = Some("1.0000000000000001".parse().unwrap());
4656        account_info.total_margin_balance = Some("2.0000000000000002".parse().unwrap());
4657        account_info.total_initial_margin = Some("3.0000000000000003".parse().unwrap());
4658        account_info.total_maint_margin = Some("4.0000000000000004".parse().unwrap());
4659        account_info.total_unrealized_profit = Some("5.0000000000000005".parse().unwrap());
4660        account_info.total_cross_wallet_balance = Some("6.0000000000000006".parse().unwrap());
4661        account_info.total_cross_un_pnl = Some("7.0000000000000007".parse().unwrap());
4662        account_info.available_balance = Some("8.0000000000000008".parse().unwrap());
4663        account_info.max_withdraw_amount = Some("9.0000000000000009".parse().unwrap());
4664
4665        let state = BinanceFuturesExecutionClient::create_account_state_from(
4666            &account_info,
4667            AccountId::from("BINANCE-001"),
4668            AccountType::Margin,
4669            Currency::USDT(),
4670            get_atomic_clock_realtime(),
4671        );
4672
4673        let info = state.info.as_ref().unwrap();
4674        assert_eq!(info.len(), 9);
4675        assert_eq!(
4676            info.get_str("total_wallet_balance"),
4677            Some("1.0000000000000001")
4678        );
4679        assert_eq!(
4680            info.get_str("total_margin_balance"),
4681            Some("2.0000000000000002")
4682        );
4683        assert_eq!(
4684            info.get_str("total_initial_margin"),
4685            Some("3.0000000000000003")
4686        );
4687        assert_eq!(
4688            info.get_str("total_maint_margin"),
4689            Some("4.0000000000000004")
4690        );
4691        assert_eq!(
4692            info.get_str("total_unrealized_profit"),
4693            Some("5.0000000000000005")
4694        );
4695        assert_eq!(
4696            info.get_str("total_cross_wallet_balance"),
4697            Some("6.0000000000000006")
4698        );
4699        assert_eq!(
4700            info.get_str("total_cross_unpnl"),
4701            Some("7.0000000000000007")
4702        );
4703        assert_eq!(
4704            info.get_str("available_balance"),
4705            Some("8.0000000000000008")
4706        );
4707        assert_eq!(
4708            info.get_str("max_withdraw_amount"),
4709            Some("9.0000000000000009")
4710        );
4711    }
4712
4713    #[rstest]
4714    #[case(-2011, true)]
4715    #[case(-2013, true)]
4716    #[case(-2015, false)]
4717    #[case(-1007, false)]
4718    fn test_tagged_algo_cancel_fallback_requires_missing_order(
4719        #[case] code: i64,
4720        #[case] expected: bool,
4721        #[values(false, true)] lookup: bool,
4722    ) {
4723        let id = ClientOrderId::new("O-20260922-160119-V2-000-8");
4724
4725        let error = BinanceFuturesHttpError::BinanceError {
4726            code,
4727            message: "test".to_string(),
4728            status: 400,
4729            retry_after: None,
4730        };
4731
4732        let error = if lookup {
4733            BinanceFuturesHttpError::IdentityLookup(Box::new(error))
4734        } else {
4735            error
4736        };
4737
4738        let error = anyhow::Error::new(error);
4739
4740        assert_eq!(should_retry_regular_cancel(id, &error), expected);
4741        assert!(!should_retry_regular_cancel(
4742            id,
4743            &anyhow::anyhow!(BinanceFuturesHttpError::Timeout("lookup".into()))
4744        ));
4745        assert!(!should_retry_regular_cancel(
4746            id,
4747            &anyhow::anyhow!(BinanceFuturesHttpError::ValidationError(
4748                "ambiguous identity".into()
4749            ))
4750        ));
4751        assert!(should_retry_regular_cancel(
4752            ClientOrderId::new("legacy-order"),
4753            &error
4754        ));
4755    }
4756
4757    #[rstest]
4758    #[case::regular(false, false, false, false)]
4759    #[case::untriggered_algo(true, false, false, true)]
4760    #[case::triggered_algo(true, true, false, false)]
4761    #[case::promoted_algo(true, false, true, false)]
4762    fn test_should_use_algo_cancel(
4763        #[case] is_algo: bool,
4764        #[case] is_triggered: bool,
4765        #[case] has_promoted_id: bool,
4766        #[case] expected: bool,
4767    ) {
4768        assert_eq!(
4769            should_use_algo_cancel(is_algo, is_triggered, has_promoted_id),
4770            expected
4771        );
4772    }
4773
4774    #[rstest]
4775    #[case::not_close(BinanceSide::Sell, Some(BinancePositionSide::Long), false, None, None)]
4776    #[case::positive_quantity(
4777        BinanceSide::Sell,
4778        Some(BinancePositionSide::Long),
4779        true,
4780        Some("0.001"),
4781        None
4782    )]
4783    #[case::hedge_long(
4784        BinanceSide::Sell,
4785        Some(BinancePositionSide::Long),
4786        true,
4787        None,
4788        Some(PositionSide::Long)
4789    )]
4790    #[case::hedge_long_zero(
4791        BinanceSide::Sell,
4792        Some(BinancePositionSide::Long),
4793        true,
4794        Some("0.0000"),
4795        Some(PositionSide::Long)
4796    )]
4797    #[case::hedge_short(
4798        BinanceSide::Buy,
4799        Some(BinancePositionSide::Short),
4800        true,
4801        None,
4802        Some(PositionSide::Short)
4803    )]
4804    #[case::invalid_hedge_long(BinanceSide::Buy, Some(BinancePositionSide::Long), true, None, None)]
4805    #[case::invalid_hedge_short(
4806        BinanceSide::Sell,
4807        Some(BinancePositionSide::Short),
4808        true,
4809        None,
4810        None
4811    )]
4812    #[case::one_way_long(
4813        BinanceSide::Sell,
4814        Some(BinancePositionSide::Both),
4815        true,
4816        None,
4817        Some(PositionSide::Long)
4818    )]
4819    #[case::one_way_short(
4820        BinanceSide::Buy,
4821        Some(BinancePositionSide::Both),
4822        true,
4823        None,
4824        Some(PositionSide::Short)
4825    )]
4826    #[case::missing_side(BinanceSide::Buy, None, true, None, Some(PositionSide::Short))]
4827    #[case::unknown_side(
4828        BinanceSide::Sell,
4829        Some(BinancePositionSide::Unknown),
4830        true,
4831        None,
4832        None
4833    )]
4834    fn test_quantity_free_close_position_side(
4835        #[case] side: BinanceSide,
4836        #[case] position_side: Option<BinancePositionSide>,
4837        #[case] close_position: bool,
4838        #[case] quantity: Option<&str>,
4839        #[case] expected: Option<PositionSide>,
4840    ) {
4841        let json = load_fixture_string("futures/http_json/open_algo_orders.json");
4842        let mut orders: Vec<BinanceFuturesAlgoOrder> = serde_json::from_str(&json).unwrap();
4843        let mut order = orders.remove(0);
4844        order.side = side;
4845        order.position_side = position_side;
4846        order.close_position = Some(close_position);
4847        order.quantity = quantity.map(str::to_string);
4848
4849        assert_eq!(quantity_free_close_position_side(&order), expected);
4850    }
4851
4852    #[rstest]
4853    #[case::regular(
4854        false,
4855        Some(VenueOrderId::from("8886774")),
4856        None,
4857        Some(VenueOrderId::from("8886774"))
4858    )]
4859    #[case::unpromoted_algo(true, Some(VenueOrderId::from("2148719")), None, None)]
4860    #[case::promoted(
4861        true,
4862        Some(VenueOrderId::from("2148719")),
4863        Some(VenueOrderId::from("22542179")),
4864        Some(VenueOrderId::from("22542179"))
4865    )]
4866    fn test_cancel_venue_order_id(
4867        #[case] is_algo: bool,
4868        #[case] venue_order_id: Option<VenueOrderId>,
4869        #[case] promoted_algo_order_id: Option<VenueOrderId>,
4870        #[case] expected: Option<VenueOrderId>,
4871    ) {
4872        assert_eq!(
4873            cancel_venue_order_id(is_algo, venue_order_id, promoted_algo_order_id),
4874            expected
4875        );
4876    }
4877
4878    #[rstest]
4879    fn test_classify_submit_order_error_gtx_is_post_only() {
4880        let err = http_error(BINANCE_GTX_ORDER_REJECT_CODE);
4881        assert!(classify_submit_order_error(&err));
4882    }
4883
4884    #[rstest]
4885    fn test_futures_order_lifetime_encodes_valid_usdm_gtd() {
4886        let ts_now = UnixNanos::from_seconds(1_700_000_000);
4887        let expire_time = UnixNanos::from_seconds(1_700_000_601);
4888
4889        let lifetime = determine_futures_order_lifetime(
4890            BinanceProductType::UsdM,
4891            OrderType::Limit,
4892            TimeInForce::Gtd,
4893            Some(expire_time),
4894            false,
4895            true,
4896            ts_now,
4897        )
4898        .unwrap();
4899
4900        assert_eq!(lifetime.time_in_force, TimeInForce::Gtd);
4901        assert_eq!(lifetime.good_till_date, Some(1_700_000_601_000));
4902    }
4903
4904    #[rstest]
4905    #[case::minimum(
4906        BinanceProductType::UsdM,
4907        OrderType::Limit,
4908        UnixNanos::from_seconds(1_700_000_600),
4909        false,
4910        "strictly greater"
4911    )]
4912    #[case::subsecond(
4913        BinanceProductType::UsdM,
4914        OrderType::Limit,
4915        UnixNanos::from(1_700_000_601_000_000_001),
4916        false,
4917        "whole-second precision"
4918    )]
4919    #[case::coin_m(
4920        BinanceProductType::CoinM,
4921        OrderType::Limit,
4922        UnixNanos::from_seconds(1_700_000_601),
4923        false,
4924        "does not support native GTD"
4925    )]
4926    #[case::market(
4927        BinanceProductType::UsdM,
4928        OrderType::Market,
4929        UnixNanos::from_seconds(1_700_000_601),
4930        false,
4931        "does not support GTD for order type Market"
4932    )]
4933    #[case::post_only(
4934        BinanceProductType::UsdM,
4935        OrderType::Limit,
4936        UnixNanos::from_seconds(1_700_000_601),
4937        true,
4938        "UNSUPPORTED_POST_ONLY"
4939    )]
4940    fn test_futures_order_lifetime_rejects_invalid_gtd(
4941        #[case] product_type: BinanceProductType,
4942        #[case] order_type: OrderType,
4943        #[case] expire_time: UnixNanos,
4944        #[case] post_only: bool,
4945        #[case] expected: &str,
4946    ) {
4947        let error = determine_futures_order_lifetime(
4948            product_type,
4949            order_type,
4950            TimeInForce::Gtd,
4951            Some(expire_time),
4952            post_only,
4953            true,
4954            UnixNanos::from_seconds(1_700_000_000),
4955        )
4956        .unwrap_err();
4957
4958        assert!(error.to_string().contains(expected));
4959    }
4960
4961    #[rstest]
4962    #[case::coin_m_limit(BinanceProductType::CoinM, OrderType::Limit, false)]
4963    #[case::usd_m_market(BinanceProductType::UsdM, OrderType::Market, false)]
4964    #[case::usd_m_post_only(BinanceProductType::UsdM, OrderType::Limit, true)]
4965    fn test_futures_order_lifetime_maps_locally_managed_gtd_to_gtc(
4966        #[case] product_type: BinanceProductType,
4967        #[case] order_type: OrderType,
4968        #[case] post_only: bool,
4969    ) {
4970        let lifetime = determine_futures_order_lifetime(
4971            product_type,
4972            order_type,
4973            TimeInForce::Gtd,
4974            Some(UnixNanos::from_seconds(1_700_000_601)),
4975            post_only,
4976            false,
4977            UnixNanos::from_seconds(1_700_000_000),
4978        )
4979        .unwrap();
4980
4981        assert_eq!(lifetime.time_in_force, TimeInForce::Gtc);
4982        assert_eq!(lifetime.good_till_date, None);
4983    }
4984
4985    #[rstest]
4986    fn test_futures_order_lifetime_requires_expire_time() {
4987        let error = determine_futures_order_lifetime(
4988            BinanceProductType::UsdM,
4989            OrderType::Limit,
4990            TimeInForce::Gtd,
4991            None,
4992            false,
4993            true,
4994            UnixNanos::from_seconds(1_700_000_000),
4995        )
4996        .unwrap_err();
4997
4998        assert_eq!(error, OrderDeniedReason::MissingExpireTime);
4999    }
5000
5001    #[rstest]
5002    fn test_futures_order_lifetime_maximum_exceeds_unix_nanos_range() {
5003        let maximum_unix_nanos_millis = u64::MAX / NANOSECONDS_IN_MILLISECOND;
5004
5005        assert!(maximum_unix_nanos_millis < BINANCE_GTD_MAX_MILLIS);
5006    }
5007
5008    #[rstest]
5009    fn test_classify_submit_order_error_dual_side_sync_is_not_post_only() {
5010        // -4531 is a hedge-mode/account-setup issue, not a post-only rejection.
5011        // Make sure the new classifier branch does not mark it as post-only.
5012        let err = http_error(BINANCE_FUTURES_DUAL_SIDE_SYNC_REJECT_CODE);
5013        assert!(!classify_submit_order_error(&err));
5014    }
5015
5016    #[rstest]
5017    fn test_classify_submit_order_error_other_venue_code_is_not_post_only() {
5018        let err = http_error(-2010);
5019        assert!(!classify_submit_order_error(&err));
5020    }
5021
5022    #[rstest]
5023    fn test_classify_submit_order_error_non_binance_error_is_not_post_only() {
5024        let err = anyhow::anyhow!("network failure");
5025        assert!(!classify_submit_order_error(&err));
5026    }
5027
5028    #[rstest]
5029    #[case(BINANCE_UNEXPECTED_RESPONSE_CODE)]
5030    #[case(BINANCE_STATUS_UNKNOWN_CODE)]
5031    fn test_unknown_status_submit_error_is_ambiguous(#[case] code: i64) {
5032        let err = http_error(code);
5033        assert!(matches!(
5034            classify_futures_http_failure(err.downcast_ref().unwrap()),
5035            CommandFailure::Ambiguous(_)
5036        ));
5037    }
5038
5039    #[rstest]
5040    fn test_other_structured_submit_error_is_not_ambiguous() {
5041        let err = http_error(BINANCE_GTX_ORDER_REJECT_CODE);
5042        assert!(matches!(
5043            classify_futures_http_failure(err.downcast_ref().unwrap()),
5044            CommandFailure::VenueRejected(_)
5045        ));
5046    }
5047
5048    #[rstest]
5049    fn test_instrument_product_matching_distinguishes_futures_products_from_spot() {
5050        let usdm = InstrumentAny::CryptoPerpetual(crypto_perpetual_ethusdt());
5051        let generic_perpetual = InstrumentAny::PerpetualContract(perpetual_contract_eurusd());
5052        let coinm = InstrumentAny::CryptoPerpetual(btcusd_bybit());
5053        let delivery =
5054            || crypto_future_btcusdt(2, 6, Price::from("0.01"), Quantity::from("0.000001"));
5055        let usdm_delivery = InstrumentAny::CryptoFuture(delivery());
5056        let mut coinm_delivery = delivery();
5057        coinm_delivery.is_inverse = true;
5058        let coinm_delivery = InstrumentAny::CryptoFuture(coinm_delivery);
5059        let spot = InstrumentAny::CurrencyPair(currency_pair_btcusdt());
5060
5061        assert!(is_instrument_for_product(&usdm, BinanceProductType::UsdM));
5062        assert!(!is_instrument_for_product(&usdm, BinanceProductType::CoinM));
5063        assert!(is_instrument_for_product(
5064            &generic_perpetual,
5065            BinanceProductType::UsdM
5066        ));
5067        assert!(!is_instrument_for_product(
5068            &generic_perpetual,
5069            BinanceProductType::CoinM
5070        ));
5071        assert!(is_instrument_for_product(&coinm, BinanceProductType::CoinM));
5072        assert!(!is_instrument_for_product(&coinm, BinanceProductType::UsdM));
5073        assert!(is_instrument_for_product(
5074            &usdm_delivery,
5075            BinanceProductType::UsdM
5076        ));
5077        assert!(!is_instrument_for_product(
5078            &usdm_delivery,
5079            BinanceProductType::CoinM
5080        ));
5081        assert!(is_instrument_for_product(
5082            &coinm_delivery,
5083            BinanceProductType::CoinM
5084        ));
5085        assert!(!is_instrument_for_product(
5086            &coinm_delivery,
5087            BinanceProductType::UsdM
5088        ));
5089        assert!(!is_instrument_for_product(&spot, BinanceProductType::UsdM));
5090        assert!(!is_instrument_for_product(&spot, BinanceProductType::CoinM));
5091    }
5092
5093    fn test_execution_client(
5094        base_url_http: String,
5095    ) -> (BinanceFuturesExecutionClient, Rc<RefCell<Cache>>) {
5096        let cache = Rc::new(RefCell::new(Cache::default()));
5097        let core = ExecutionClientCore::new(
5098            TraderId::from("TESTER-001"),
5099            *BINANCE_CLIENT_ID,
5100            *BINANCE_VENUE,
5101            OmsType::Hedging,
5102            AccountId::from("BINANCE-001"),
5103            AccountType::Margin,
5104            None,
5105            cache.clone(),
5106        );
5107        let config = BinanceExecutionClientConfig {
5108            product_type: BinanceProductType::UsdM,
5109            base_url_http: Some(base_url_http),
5110            use_ws_trading: false,
5111            api_key: Some("test_api_key".into()),
5112            api_secret: Some("test_api_secret".into()),
5113            ..Default::default()
5114        };
5115
5116        (
5117            BinanceFuturesExecutionClient::new(core, config).unwrap(),
5118            cache,
5119        )
5120    }
5121
5122    async fn wait_for_spawned_tasks(client: &BinanceFuturesExecutionClient) {
5123        for _ in 0..40 {
5124            if client.pending_tasks.all_finished() {
5125                return;
5126            }
5127
5128            tokio::time::sleep(Duration::from_millis(25)).await;
5129        }
5130
5131        panic!("timed out waiting for spawned Binance Futures execution tasks");
5132    }
5133
5134    struct MockVenueHits {
5135        batch: Arc<AtomicUsize>,
5136        algo_cancel: Arc<AtomicUsize>,
5137        cancel_all: Arc<AtomicUsize>,
5138    }
5139
5140    async fn start_batch_reject_server() -> (String, MockVenueHits) {
5141        let batch_hits = Arc::new(AtomicUsize::new(0));
5142        let batch_hits_clone = batch_hits.clone();
5143        let algo_hits = Arc::new(AtomicUsize::new(0));
5144        let algo_hits_clone = algo_hits.clone();
5145        let cancel_all_hits = Arc::new(AtomicUsize::new(0));
5146        let cancel_all_hits_clone = cancel_all_hits.clone();
5147        let app = axum::Router::new()
5148            .route(
5149                "/fapi/v1/batchOrders",
5150                axum::routing::delete(
5151                    move |axum::extract::Query(params): axum::extract::Query<
5152                        HashMap<String, String>,
5153                    >| {
5154                        let hits = batch_hits_clone.clone();
5155                        async move {
5156                            hits.fetch_add(1, Ordering::Relaxed);
5157                            let count = ["orderIdList", "origClientOrderIdList"]
5158                                .into_iter()
5159                                .filter_map(|key| params.get(key))
5160                                .filter_map(|value| {
5161                                    serde_json::from_str::<Vec<serde_json::Value>>(value).ok()
5162                                })
5163                                .map(|values| values.len())
5164                                .sum::<usize>()
5165                                .max(1);
5166                            let errors = (0..count)
5167                                .map(|_| {
5168                                    serde_json::json!({"code": -2011, "msg": "Unknown order sent"})
5169                                })
5170                                .collect::<Vec<_>>();
5171
5172                            axum::Json(errors)
5173                        }
5174                    },
5175                ),
5176            )
5177            .route(
5178                "/fapi/v1/algoOrder",
5179                axum::routing::delete(move || {
5180                    let hits = algo_hits_clone.clone();
5181                    async move {
5182                        hits.fetch_add(1, Ordering::Relaxed);
5183
5184                        (
5185                            axum::http::StatusCode::BAD_REQUEST,
5186                            axum::Json(
5187                                serde_json::json!({"code": -2011, "msg": "Unknown algo order sent"}),
5188                            ),
5189                        )
5190                    }
5191                }),
5192            )
5193            .route(
5194                "/fapi/v1/order",
5195                axum::routing::delete(|| async {
5196                    (
5197                        axum::http::StatusCode::BAD_REQUEST,
5198                        axum::Json(
5199                            serde_json::json!({"code": -2011, "msg": "Unknown order sent"}),
5200                        ),
5201                    )
5202                }),
5203            )
5204            .route(
5205                "/fapi/v1/allOpenOrders",
5206                axum::routing::delete(move || {
5207                    let hits = cancel_all_hits_clone.clone();
5208                    async move {
5209                        hits.fetch_add(1, Ordering::Relaxed);
5210
5211                        axum::Json(serde_json::json!({"code": 200, "msg": "success"}))
5212                    }
5213                }),
5214            );
5215        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
5216        let addr = listener.local_addr().unwrap();
5217
5218        tokio::spawn(async move {
5219            axum::serve(listener, app.into_make_service())
5220                .await
5221                .unwrap();
5222        });
5223
5224        (
5225            format!("http://{addr}"),
5226            MockVenueHits {
5227                batch: batch_hits,
5228                algo_cancel: algo_hits,
5229                cancel_all: cancel_all_hits,
5230            },
5231        )
5232    }
5233
5234    #[allow(
5235        clippy::too_many_arguments,
5236        reason = "test helper takes one cohesive set of order construction inputs"
5237    )]
5238    fn add_open_order(
5239        cache: &Rc<RefCell<Cache>>,
5240        account_id: AccountId,
5241        index: usize,
5242        instrument_id: InstrumentId,
5243        owner: &str,
5244        side: OrderSide,
5245        order_type: OrderType,
5246        open: bool,
5247    ) -> OrderAny {
5248        let client_order_id = ClientOrderId::from(format!("O-CANCEL-ALL-{index}"));
5249        let mut builder = OrderTestBuilder::new(order_type);
5250        let order = builder
5251            .instrument_id(instrument_id)
5252            .client_order_id(client_order_id)
5253            .strategy_id(StrategyId::from(owner))
5254            .side(side)
5255            .quantity(Quantity::from("1"))
5256            .price(Price::from("10000.00"))
5257            .trigger_price(Price::from("9900.00"))
5258            .build();
5259        let venue_order_id = VenueOrderId::from(format!("{}", 1000 + index));
5260        let accepted = TestOrderEventStubs::accepted(&order, account_id, venue_order_id);
5261        cache
5262            .borrow_mut()
5263            .add_order(order, None, Some(*BINANCE_CLIENT_ID), false)
5264            .unwrap();
5265        let order = cache.borrow_mut().update_order(&accepted).unwrap();
5266
5267        if !open {
5268            let canceled = TestOrderEventStubs::canceled(&order, account_id, Some(venue_order_id));
5269            cache.borrow_mut().update_order(&canceled).unwrap();
5270        }
5271
5272        order
5273    }
5274
5275    #[rstest]
5276    #[case::buy(Some(OrderSide::Buy), vec![0, 2])]
5277    #[case::sell(Some(OrderSide::Sell), vec![1, 3])]
5278    #[tokio::test]
5279    async fn test_cancel_all_orders_filters_by_side_and_preserves_owners(
5280        #[case] order_side: Option<OrderSide>,
5281        #[case] expected_indices: Vec<usize>,
5282    ) {
5283        let (base_url, hits) = start_batch_reject_server().await;
5284        let (mut client, cache) = test_execution_client(base_url);
5285        let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel();
5286        client.emitter.set_sender(tx);
5287
5288        let instrument_id = InstrumentId::from("BTCUSDT-PERP.BINANCE");
5289        let other_instrument_id = InstrumentId::from("ETHUSDT-PERP.BINANCE");
5290        let account_id = client.core.account_id;
5291        let mut orders = Vec::new();
5292
5293        for (index, (instrument, owner, side, open)) in [
5294            (instrument_id, "S-001", OrderSide::Buy, true),
5295            (instrument_id, "S-001", OrderSide::Sell, true),
5296            (instrument_id, "S-002", OrderSide::Buy, true),
5297            (instrument_id, "S-002", OrderSide::Sell, true),
5298            (other_instrument_id, "S-001", OrderSide::Buy, true),
5299            (other_instrument_id, "S-002", OrderSide::Sell, true),
5300            (instrument_id, "S-001", OrderSide::Buy, false),
5301            (instrument_id, "S-002", OrderSide::Sell, false),
5302        ]
5303        .into_iter()
5304        .enumerate()
5305        {
5306            orders.push(add_open_order(
5307                &cache,
5308                account_id,
5309                index,
5310                instrument,
5311                owner,
5312                side,
5313                OrderType::Limit,
5314                open,
5315            ));
5316        }
5317
5318        client
5319            .cancel_all_orders(CancelAllOrders::new(
5320                TraderId::from("TESTER-001"),
5321                Some(*BINANCE_CLIENT_ID),
5322                StrategyId::from("S-001"),
5323                instrument_id,
5324                order_side,
5325                UUID4::new(),
5326                UnixNanos::default(),
5327                None,
5328                None,
5329            ))
5330            .unwrap();
5331        wait_for_spawned_tasks(&client).await;
5332
5333        // Rejections expose per-order ownership in the outcomes
5334        assert_eq!(hits.batch.load(Ordering::Relaxed), 1);
5335        assert_eq!(hits.algo_cancel.load(Ordering::Relaxed), 0);
5336        assert_eq!(hits.cancel_all.load(Ordering::Relaxed), 0);
5337
5338        let mut actual = Vec::new();
5339
5340        for _ in &expected_indices {
5341            let event = rx.try_recv().expect("expected OrderCancelRejected event");
5342            match event {
5343                ExecutionEvent::Order(OrderEventAny::CancelRejected(rejected)) => {
5344                    actual.push((rejected.client_order_id, rejected.strategy_id));
5345                }
5346                event => panic!("expected OrderCancelRejected, was {event:?}"),
5347            }
5348        }
5349
5350        let mut expected: Vec<_> = expected_indices
5351            .iter()
5352            .map(|&index| {
5353                let order = &orders[index];
5354                (order.client_order_id(), order.strategy_id())
5355            })
5356            .collect();
5357
5358        actual.sort();
5359        expected.sort();
5360
5361        assert_eq!(actual, expected);
5362        assert!(rx.try_recv().is_err());
5363    }
5364
5365    #[rstest]
5366    #[tokio::test]
5367    async fn test_cancel_all_orders_routes_algo_orders_individually() {
5368        let (base_url, hits) = start_batch_reject_server().await;
5369        let (mut client, cache) = test_execution_client(base_url);
5370        let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel();
5371        client.emitter.set_sender(tx);
5372
5373        let instrument_id = InstrumentId::from("BTCUSDT-PERP.BINANCE");
5374        let account_id = client.core.account_id;
5375
5376        // Two algo types cover the split; opposite-side algo must be ignored
5377        let algo_buy_owner_a = add_open_order(
5378            &cache,
5379            account_id,
5380            0,
5381            instrument_id,
5382            "S-001",
5383            OrderSide::Buy,
5384            OrderType::StopMarket,
5385            true,
5386        );
5387        let algo_buy_owner_b = add_open_order(
5388            &cache,
5389            account_id,
5390            1,
5391            instrument_id,
5392            "S-002",
5393            OrderSide::Buy,
5394            OrderType::StopLimit,
5395            true,
5396        );
5397        let regular_buy = add_open_order(
5398            &cache,
5399            account_id,
5400            2,
5401            instrument_id,
5402            "S-002",
5403            OrderSide::Buy,
5404            OrderType::Limit,
5405            true,
5406        );
5407        add_open_order(
5408            &cache,
5409            account_id,
5410            3,
5411            instrument_id,
5412            "S-001",
5413            OrderSide::Sell,
5414            OrderType::StopMarket,
5415            true,
5416        );
5417
5418        client
5419            .cancel_all_orders(CancelAllOrders::new(
5420                TraderId::from("TESTER-001"),
5421                Some(*BINANCE_CLIENT_ID),
5422                StrategyId::from("S-001"),
5423                instrument_id,
5424                Some(OrderSide::Buy),
5425                UUID4::new(),
5426                UnixNanos::default(),
5427                None,
5428                None,
5429            ))
5430            .unwrap();
5431        wait_for_spawned_tasks(&client).await;
5432
5433        assert_eq!(hits.batch.load(Ordering::Relaxed), 1);
5434        assert_eq!(hits.algo_cancel.load(Ordering::Relaxed), 2);
5435        assert_eq!(hits.cancel_all.load(Ordering::Relaxed), 0);
5436
5437        let mut actual = Vec::new();
5438
5439        for _ in 0..3 {
5440            let event = rx.try_recv().expect("expected OrderCancelRejected event");
5441            match event {
5442                ExecutionEvent::Order(OrderEventAny::CancelRejected(rejected)) => {
5443                    actual.push((rejected.client_order_id, rejected.strategy_id));
5444                }
5445                event => panic!("expected OrderCancelRejected, was {event:?}"),
5446            }
5447        }
5448
5449        let mut expected = [algo_buy_owner_a, algo_buy_owner_b, regular_buy]
5450            .iter()
5451            .map(|order| (order.client_order_id(), order.strategy_id()))
5452            .collect::<Vec<_>>();
5453
5454        actual.sort();
5455        expected.sort();
5456
5457        assert_eq!(actual, expected);
5458        assert!(rx.try_recv().is_err());
5459    }
5460
5461    #[rstest]
5462    #[tokio::test]
5463    async fn test_cancel_all_orders_with_side_and_empty_cache_sends_nothing() {
5464        let (base_url, hits) = start_batch_reject_server().await;
5465        let (mut client, _cache) = test_execution_client(base_url);
5466        let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel();
5467        client.emitter.set_sender(tx);
5468
5469        client
5470            .cancel_all_orders(CancelAllOrders::new(
5471                TraderId::from("TESTER-001"),
5472                Some(*BINANCE_CLIENT_ID),
5473                StrategyId::from("S-001"),
5474                InstrumentId::from("BTCUSDT-PERP.BINANCE"),
5475                Some(OrderSide::Buy),
5476                UUID4::new(),
5477                UnixNanos::default(),
5478                None,
5479                None,
5480            ))
5481            .unwrap();
5482        wait_for_spawned_tasks(&client).await;
5483
5484        assert_eq!(hits.batch.load(Ordering::Relaxed), 0);
5485        assert_eq!(hits.algo_cancel.load(Ordering::Relaxed), 0);
5486        assert_eq!(hits.cancel_all.load(Ordering::Relaxed), 0);
5487        assert!(rx.try_recv().is_err());
5488        assert!(client.dispatch_state.pending_requests.is_empty());
5489    }
5490}