nautilus_model/accounts/

margin.rs

// -------------------------------------------------------------------------------------------------
//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
//  https://nautechsystems.io
//
//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
//  You may not use this file except in compliance with the License.
//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.
// -------------------------------------------------------------------------------------------------

//! A margin account capable of holding leveraged positions and tracking instrument-specific
//! leverage ratios.
//!
//! # PnL calculation
//!
//! The account calculates PnL differently based on instrument type:
//!
//! - **Premium instruments** (options, option spreads, binary options, warrants): Realize
//!   the notional value as a cash flow on every fill. BUY = negative (premium paid),
//!   SELL = positive (premium received).
//!
//! - **Other instruments**: Only realize PnL on position reduction (fill side opposite to
//!   entry). Use the minimum of fill and position quantity to avoid double-counting.

use std::{
    fmt::Display,
    hash::{Hash, Hasher},
    ops::{Deref, DerefMut},
};

use ahash::AHashMap;
use indexmap::IndexMap;
use nautilus_core::correctness::{CorrectnessResultExt, FAILED, check_positive_decimal};
use rust_decimal::Decimal;
use serde::{Deserialize, Serialize};

use crate::{
    accounts::{
        Account,
        base::BaseAccount,
        margin_model::{MarginModel, MarginModelHandle},
    },
    enums::{AccountType, InstrumentClass, OrderSide},
    events::{AccountState, OrderFilled},
    identifiers::InstrumentId,
    instruments::{Instrument, InstrumentAny},
    position::Position,
    types::{
        AccountBalance, Currency, MarginBalance, Money, Price, Quantity,
        money::{MONEY_RAW_MAX, MONEY_RAW_MIN, MoneyRaw},
    },
};

/// Represents a margin account that can hold leveraged positions.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(
    feature = "python",
    pyo3::pyclass(module = "nautilus_trader.model", from_py_object)
)]
#[cfg_attr(
    feature = "python",
    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.model")
)]
pub struct MarginAccount {
    /// The account state shared by every account type.
    pub base: BaseAccount,
    /// The leverage applied per instrument, overriding `default_leverage`.
    pub leverages: AHashMap<InstrumentId, Decimal>,
    /// Per-instrument margin balances (isolated margin, calculated margin in
    /// backtest mode). Entries here have a concrete `instrument_id`.
    pub margins: IndexMap<InstrumentId, MarginBalance>,
    /// Account-wide (cross margin) margin balances keyed by collateral currency.
    /// Populated from `AccountState.margins` entries where `instrument_id` is
    /// `None`. Most derivatives venues in cross-margin mode report here.
    pub account_margins: IndexMap<Currency, MarginBalance>,
    /// The leverage applied to any instrument absent from `leverages`.
    pub default_leverage: Decimal,
    #[serde(skip, default = "MarginModelHandle::default")]
    margin_model: MarginModelHandle,
}

impl MarginAccount {
    /// Creates a new [`MarginAccount`] instance.
    #[must_use]
    pub fn new(event: AccountState, calculate_account_state: bool) -> Self {
        let (margins, account_margins) = split_event_margins(&event);

        Self {
            base: BaseAccount::new(event, calculate_account_state),
            leverages: AHashMap::new(),
            margins,
            account_margins,
            default_leverage: Decimal::ONE,
            margin_model: MarginModelHandle::default(),
        }
    }

    #[must_use]
    pub(crate) fn clone_without_events(&self) -> Self {
        Self {
            base: self.base.clone_without_events(),
            leverages: self.leverages.clone(),
            margins: self.margins.clone(),
            account_margins: self.account_margins.clone(),
            default_leverage: self.default_leverage,
            margin_model: self.margin_model.clone(),
        }
    }

    pub fn set_margin_model(&mut self, model: MarginModelHandle) {
        self.margin_model = model;
    }

    #[must_use]
    pub const fn margin_model(&self) -> &MarginModelHandle {
        &self.margin_model
    }

    /// Sets the default leverage for the account.
    ///
    /// # Panics
    ///
    /// Panics if `leverage` is not positive.
    pub fn set_default_leverage(&mut self, leverage: Decimal) {
        check_positive_decimal(leverage, "leverage").expect_display(FAILED);
        self.default_leverage = leverage;
    }

    /// Sets the leverage for a specific instrument.
    ///
    /// # Panics
    ///
    /// Panics if `leverage` is not positive.
    pub fn set_leverage(&mut self, instrument_id: InstrumentId, leverage: Decimal) {
        check_positive_decimal(leverage, "leverage").expect_display(FAILED);
        self.leverages.insert(instrument_id, leverage);
    }

    #[must_use]
    pub fn get_leverage(&self, instrument_id: &InstrumentId) -> Decimal {
        *self
            .leverages
            .get(instrument_id)
            .unwrap_or(&self.default_leverage)
    }

    #[must_use]
    pub fn is_unleveraged(&self, instrument_id: InstrumentId) -> bool {
        self.get_leverage(&instrument_id) == Decimal::ONE
    }

    #[must_use]
    pub fn is_cash_account(&self) -> bool {
        self.account_type == AccountType::Cash
    }

    #[must_use]
    pub fn is_margin_account(&self) -> bool {
        self.account_type == AccountType::Margin
    }

    #[must_use]
    pub fn initial_margins(&self) -> IndexMap<InstrumentId, Money> {
        self.margins
            .values()
            .filter_map(|margin| margin.instrument_id.map(|id| (id, margin.initial)))
            .collect()
    }

    #[must_use]
    pub fn maintenance_margins(&self) -> IndexMap<InstrumentId, Money> {
        self.margins
            .values()
            .filter_map(|margin| margin.instrument_id.map(|id| (id, margin.maintenance)))
            .collect()
    }

    /// Returns all account-wide initial margins keyed by currency.
    #[must_use]
    pub fn account_initial_margins(&self) -> IndexMap<Currency, Money> {
        self.account_margins
            .values()
            .map(|margin| (margin.currency, margin.initial))
            .collect()
    }

    /// Returns all account-wide maintenance margins keyed by currency.
    #[must_use]
    pub fn account_maintenance_margins(&self) -> IndexMap<Currency, Money> {
        self.account_margins
            .values()
            .map(|margin| (margin.currency, margin.maintenance))
            .collect()
    }

    /// Updates the initial margin for the specified instrument.
    pub fn update_initial_margin(&mut self, instrument_id: InstrumentId, margin_init: Money) {
        self.update_margin_component(instrument_id, margin_init, MarginComponent::Initial);
    }

    /// Clears the initial margin for the specified instrument.
    pub fn clear_initial_margin(&mut self, instrument_id: InstrumentId) {
        self.clear_margin_component(instrument_id, MarginComponent::Initial);
    }

    /// Returns the initial margin amount for the specified instrument.
    ///
    /// # Panics
    ///
    /// Panics if no margin balance exists for the given `instrument_id`.
    #[must_use]
    pub fn initial_margin(&self, instrument_id: InstrumentId) -> Money {
        let margin_balance = self.margins.get(&instrument_id);
        assert!(
            margin_balance.is_some(),
            "Cannot get margin_init when no margin_balance"
        );
        margin_balance.unwrap().initial
    }

    /// Updates the maintenance margin for the specified instrument.
    pub fn update_maintenance_margin(
        &mut self,
        instrument_id: InstrumentId,
        margin_maintenance: Money,
    ) {
        self.update_margin_component(
            instrument_id,
            margin_maintenance,
            MarginComponent::Maintenance,
        );
    }

    /// Clears the maintenance margin for the specified instrument.
    pub fn clear_maintenance_margin(&mut self, instrument_id: InstrumentId) {
        self.clear_margin_component(instrument_id, MarginComponent::Maintenance);
    }

    fn update_margin_component(
        &mut self,
        instrument_id: InstrumentId,
        amount: Money,
        component: MarginComponent,
    ) {
        let mut margin_balance = self
            .margins
            .get(&instrument_id)
            .copied()
            .unwrap_or_else(|| {
                let zero = Money::zero(amount.currency);
                MarginBalance::new(zero, zero, Some(instrument_id))
            });
        component.set(&mut margin_balance, amount);
        self.margins.insert(instrument_id, margin_balance);

        self.recalculate_balance(amount.currency);
    }

    fn clear_margin_component(&mut self, instrument_id: InstrumentId, component: MarginComponent) {
        let Some(mut margin_balance) = self.margins.get(&instrument_id).copied() else {
            return;
        };

        let currency = margin_balance.currency;
        if component.sibling(&margin_balance).is_zero() {
            self.margins.shift_remove(&instrument_id);
        } else {
            component.set(&mut margin_balance, Money::zero(currency));
            self.margins.insert(instrument_id, margin_balance);
        }

        self.recalculate_balance(currency);
    }

    /// Returns the maintenance margin amount for the specified instrument.
    ///
    /// # Panics
    ///
    /// Panics if no margin balance exists for the given `instrument_id`.
    #[must_use]
    pub fn maintenance_margin(&self, instrument_id: InstrumentId) -> Money {
        let margin_balance = self.margins.get(&instrument_id);
        assert!(
            margin_balance.is_some(),
            "Cannot get maintenance_margin when no margin_balance"
        );
        margin_balance.unwrap().maintenance
    }

    /// Returns the margin balance for the specified instrument.
    #[must_use]
    pub fn margin(&self, instrument_id: &InstrumentId) -> Option<MarginBalance> {
        self.margins.get(instrument_id).copied()
    }

    /// Returns the account-wide margin balance for the specified collateral currency.
    #[must_use]
    pub fn account_margin(&self, currency: &Currency) -> Option<MarginBalance> {
        self.account_margins.get(currency).copied()
    }

    /// Returns the account-wide initial margin for the specified collateral currency.
    #[must_use]
    pub fn account_initial_margin(&self, currency: &Currency) -> Option<Money> {
        self.account_margins.get(currency).map(|m| m.initial)
    }

    /// Returns the account-wide maintenance margin for the specified collateral currency.
    #[must_use]
    pub fn account_maintenance_margin(&self, currency: &Currency) -> Option<Money> {
        self.account_margins.get(currency).map(|m| m.maintenance)
    }

    /// Returns the total initial margin reserved in the specified currency,
    /// summing per-instrument and account-wide entries.
    #[must_use]
    pub fn total_initial_margin(&self, currency: Currency) -> Money {
        self.total_margin_component(currency, MarginComponent::Initial)
    }

    /// Returns the total maintenance margin reserved in the specified currency,
    /// summing per-instrument and account-wide entries.
    #[must_use]
    pub fn total_maintenance_margin(&self, currency: Currency) -> Money {
        self.total_margin_component(currency, MarginComponent::Maintenance)
    }

    fn total_margin_component(&self, currency: Currency, component: MarginComponent) -> Money {
        let raw = self
            .margins_in(currency)
            .fold(0 as MoneyRaw, |raw, margin| {
                raw.saturating_add(component.of(margin).raw())
            });

        Money::from_raw(clamp_money_raw(raw), currency)
    }

    /// Returns every margin balance reserved in `currency`, per-instrument entries first.
    fn margins_in(&self, currency: Currency) -> impl Iterator<Item = &MarginBalance> {
        self.margins
            .values()
            .chain(self.account_margins.values())
            .filter(move |margin| margin.currency == currency)
    }

    /// Updates the margin balance for the specified instrument or collateral.
    ///
    /// When `margin_balance.instrument_id` is `Some`, the entry is stored as a
    /// per-instrument margin. When `None`, the entry is stored as an
    /// account-wide margin keyed by `margin_balance.currency`.
    pub fn update_margin(&mut self, margin_balance: MarginBalance) {
        match margin_balance.instrument_id {
            Some(instrument_id) => {
                self.margins.insert(instrument_id, margin_balance);
            }
            None => {
                self.account_margins
                    .insert(margin_balance.currency, margin_balance);
            }
        }
        self.recalculate_balance(margin_balance.currency);
    }

    /// Clears the margin for the specified instrument.
    pub fn clear_margin(&mut self, instrument_id: InstrumentId) {
        if let Some(margin_balance) = self.margins.shift_remove(&instrument_id) {
            self.recalculate_balance(margin_balance.currency);
        }
    }

    /// Clears the account-wide margin for the specified collateral currency.
    pub fn clear_account_margin(&mut self, currency: Currency) {
        if self.account_margins.shift_remove(&currency).is_some() {
            self.recalculate_balance(currency);
        }
    }

    /// Calculates the initial margin amount for the specified instrument and quantity.
    ///
    /// Delegates to the configured [`MarginModel`].
    ///
    /// # Errors
    ///
    /// Returns an error if leverage is not positive, or if the result cannot be represented
    /// as `Money`.
    pub fn calculate_initial_margin<T: Instrument>(
        &self,
        instrument: &T,
        quantity: Quantity,
        price: Price,
        use_quote_for_inverse: Option<bool>,
    ) -> anyhow::Result<Money> {
        let leverage = self.get_leverage(&instrument.id());
        self.margin_model.calculate_initial_margin(
            instrument,
            quantity,
            price,
            leverage,
            use_quote_for_inverse,
        )
    }

    /// Calculates the maintenance margin amount for the specified instrument and quantity.
    ///
    /// Delegates to the configured [`MarginModel`].
    ///
    /// # Errors
    ///
    /// Returns an error if the result cannot be represented as `Money`.
    pub fn calculate_maintenance_margin<T: Instrument>(
        &self,
        instrument: &T,
        quantity: Quantity,
        price: Price,
        use_quote_for_inverse: Option<bool>,
    ) -> anyhow::Result<Money> {
        let leverage = self.get_leverage(&instrument.id());
        self.margin_model.calculate_maintenance_margin(
            instrument,
            quantity,
            price,
            leverage,
            use_quote_for_inverse,
        )
    }

    /// Recalculates the account balance for the specified currency based on current margins.
    ///
    /// If the margins cannot be totaled, the balance is reserved in full so no further orders
    /// are funded against it.
    pub fn recalculate_balance(&mut self, currency: Currency) {
        let current_balance = if let Some(balance) = self.balances.get(&currency) {
            *balance
        } else {
            // Materializing a balance here would assert the venue holds zero of this currency.
            // On a unified account that collateralizes across assets, absence is not zero, and
            // the fabricated entry reads as a real venue-reported balance downstream.
            log::debug!("Cannot recalculate balance when no current balance for {currency}");
            return;
        };

        // An untotalable margin set is venue-reported data, not a local invariant, so the
        // balance degrades to fully reserved rather than taking the trading node down.
        let total_margin_raw = self
            .margins_in(currency)
            .try_fold(0, |raw: MoneyRaw, margin| {
                raw.checked_add(margin.initial.raw())?
                    .checked_add(margin.maintenance.raw())
            });

        let total_margin = total_margin_raw.map_or_else(
            || {
                log::error!(
                    "Cannot total {currency} margins: the sum exceeded Money bounds; reserving the full balance"
                );
                MONEY_RAW_MAX
            },
            clamp_money_raw,
        );

        // Clamp margin to total balance if it would result in negative free balance.
        // This can occur transiently when venue and client state are out of sync.
        // Locked margin must never be negative (even if total balance is negative).
        let mut total_margin = Money::from_raw(total_margin, currency);
        if total_margin > current_balance.total {
            total_margin = current_balance.total.max(Money::zero(currency));
        }

        let total_free = current_balance.total - total_margin;

        let new_balance = AccountBalance::new(current_balance.total, total_margin, total_free);
        self.balances.insert(currency, new_balance);
    }
}

/// Selects one of the two amounts a [`MarginBalance`] carries.
#[derive(Clone, Copy)]
enum MarginComponent {
    Initial,
    Maintenance,
}

impl MarginComponent {
    const fn of(self, margin: &MarginBalance) -> Money {
        match self {
            Self::Initial => margin.initial,
            Self::Maintenance => margin.maintenance,
        }
    }

    /// Returns the amount this component is paired with on the same balance.
    const fn sibling(self, margin: &MarginBalance) -> Money {
        match self {
            Self::Initial => margin.maintenance,
            Self::Maintenance => margin.initial,
        }
    }

    const fn set(self, margin: &mut MarginBalance, amount: Money) {
        match self {
            Self::Initial => margin.initial = amount,
            Self::Maintenance => margin.maintenance = amount,
        }
    }
}

fn split_event_margins(
    event: &AccountState,
) -> (
    IndexMap<InstrumentId, MarginBalance>,
    IndexMap<Currency, MarginBalance>,
) {
    let mut per_instrument: IndexMap<InstrumentId, MarginBalance> = IndexMap::new();
    let mut per_currency: IndexMap<Currency, MarginBalance> = IndexMap::new();

    for margin in &event.margins {
        match margin.instrument_id {
            Some(instrument_id) => {
                per_instrument.insert(instrument_id, *margin);
            }
            None => {
                per_currency.insert(margin.currency, *margin);
            }
        }
    }

    (per_instrument, per_currency)
}

#[inline]
fn clamp_money_raw(raw: MoneyRaw) -> MoneyRaw {
    raw.clamp(MONEY_RAW_MIN, MONEY_RAW_MAX)
}

impl Deref for MarginAccount {
    type Target = BaseAccount;

    fn deref(&self) -> &Self::Target {
        &self.base
    }
}

impl DerefMut for MarginAccount {
    fn deref_mut(&mut self) -> &mut Self::Target {
        &mut self.base
    }
}

impl Account for MarginAccount {
    impl_account_base_members!();

    fn is_cash_account(&self) -> bool {
        self.account_type == AccountType::Cash
    }

    fn is_margin_account(&self) -> bool {
        self.account_type == AccountType::Margin
    }

    fn apply(&mut self, event: AccountState) -> anyhow::Result<()> {
        self.check_event_account_id(&event)?;

        let skip_margin_routing = event.balances.is_empty() && event.margins.is_empty();
        let (per_instrument, per_currency) = split_event_margins(&event);
        self.base_apply(event);

        if !skip_margin_routing {
            self.margins = per_instrument;
            self.account_margins = per_currency;
        }
        Ok(())
    }

    fn calculate_balance_locked(
        &self,
        instrument: &InstrumentAny,
        side: OrderSide,
        quantity: Quantity,
        price: Price,
        use_quote_for_inverse: Option<bool>,
    ) -> anyhow::Result<Money> {
        self.base_calculate_balance_locked(instrument, side, quantity, price, use_quote_for_inverse)
    }

    fn calculate_pnls(
        &self,
        instrument: &InstrumentAny,
        fill: &OrderFilled,
        position: Option<Position>,
    ) -> anyhow::Result<Vec<Money>> {
        let mut pnls: Vec<Money> = Vec::new();

        // For premium-based instruments, realize the notional value as a cash flow on every fill
        let instrument_class = instrument.instrument_class();

        if matches!(
            instrument_class,
            InstrumentClass::Option
                | InstrumentClass::OptionSpread
                | InstrumentClass::BinaryOption
                | InstrumentClass::Warrant
        ) {
            let notional =
                instrument.try_calculate_notional_value(fill.last_qty, fill.last_px, None)?;
            let pnl = if fill.order_side == OrderSide::Buy {
                -notional
            } else {
                notional
            };
            pnls.push(pnl);
            return Ok(pnls);
        }

        // For other instruments, only realize PnL on position reduction
        if let Some(ref pos) = position
            && pos.quantity.is_positive()
            && pos.entry != fill.order_side
        {
            // Calculate and add PnL using the minimum of fill quantity and position quantity
            // to avoid double-limiting that occurs in position.calculate_pnl()
            let mut pnl_quantity = fill.last_qty.min(pos.quantity);
            pnl_quantity.precision = fill.last_qty.precision;
            let pnl =
                pos.try_calculate_pnl(pos.avg_px_open, fill.last_px.as_f64(), pnl_quantity)?;
            pnls.push(pnl);
        }

        Ok(pnls)
    }
}

impl PartialEq for MarginAccount {
    fn eq(&self, other: &Self) -> bool {
        self.id == other.id
    }
}

impl Eq for MarginAccount {}

impl Display for MarginAccount {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "MarginAccount(id={}, type={}, base={})",
            self.id,
            self.account_type,
            self.base_currency.map_or_else(
                || "None".to_string(),
                |base_currency| format!("{}", base_currency.code)
            ),
        )
    }
}

impl Hash for MarginAccount {
    fn hash<H: Hasher>(&self, state: &mut H) {
        self.id.hash(state);
    }
}

#[cfg(test)]
mod tests {
    use indexmap::IndexMap;
    use nautilus_core::UnixNanos;
    use rstest::rstest;
    use rust_decimal::Decimal;

    use crate::{
        accounts::{
            Account, MarginAccount,
            margin_model::{MarginModel, MarginModelHandle},
            stubs::*,
        },
        enums::{AccountType, OrderSide, OrderType},
        events::{AccountState, account::stubs::*, order::spec::OrderFilledSpec},
        identifiers::{
            AccountId, ClientOrderId, InstrumentId, PositionId, TradeId, VenueOrderId,
            stubs::{uuid4, *},
        },
        instruments::{
            CryptoPerpetual, CurrencyPair, Instrument, InstrumentAny,
            stubs::{binary_option, option_contract_appl, *},
        },
        orders::{OrderTestBuilder, stubs::TestOrderEventStubs},
        position::Position,
        types::{
            AccountBalance, Currency, MarginBalance, Money, Price, Quantity,
            money::{MONEY_RAW_MAX, MONEY_RAW_MIN},
        },
    };

    struct CustomMarginModel;

    impl MarginModel for CustomMarginModel {
        fn name(&self) -> &'static str {
            "custom"
        }

        fn calculate_initial_margin(
            &self,
            _instrument: &dyn Instrument,
            _quantity: Quantity,
            _price: Price,
            _leverage: Decimal,
            _use_quote_for_inverse: Option<bool>,
        ) -> anyhow::Result<Money> {
            Ok(Money::from("12.34 USD"))
        }

        fn calculate_maintenance_margin(
            &self,
            _instrument: &dyn Instrument,
            _quantity: Quantity,
            _price: Price,
            _leverage: Decimal,
            _use_quote_for_inverse: Option<bool>,
        ) -> anyhow::Result<Money> {
            Ok(Money::from("5.67 USD"))
        }
    }

    #[rstest]
    fn test_display(margin_account: MarginAccount) {
        assert_eq!(
            margin_account.to_string(),
            "MarginAccount(id=SIM-001, type=MARGIN, base=USD)"
        );
    }

    #[rstest]
    fn test_calculated_account_state_returns_field_value(margin_account_state: AccountState) {
        assert!(MarginAccount::new(margin_account_state.clone(), true).calculated_account_state());
        assert!(!MarginAccount::new(margin_account_state, false).calculated_account_state());
    }

    #[rstest]
    fn test_base_account_properties(
        margin_account: MarginAccount,
        margin_account_state: AccountState,
    ) {
        assert_eq!(margin_account.base_currency, Some(Currency::from("USD")));
        assert_eq!(
            margin_account.last_event(),
            Some(margin_account_state.clone())
        );
        assert_eq!(margin_account.events(), vec![margin_account_state.clone()]);
        assert_eq!(margin_account.event_count(), 1);
        assert_eq!(
            margin_account.balance_total(None),
            Some(Money::from("1525000 USD"))
        );
        assert_eq!(
            margin_account.balance_free(None),
            Some(Money::from("1500000 USD"))
        );
        assert_eq!(
            margin_account.balance_locked(None),
            Some(Money::from("25000 USD"))
        );
        let mut balances_total_expected = IndexMap::new();
        balances_total_expected.insert(Currency::from("USD"), Money::from("1525000 USD"));
        assert_eq!(margin_account.balances_total(), balances_total_expected);
        let mut balances_free_expected = IndexMap::new();
        balances_free_expected.insert(Currency::from("USD"), Money::from("1500000 USD"));
        assert_eq!(margin_account.balances_free(), balances_free_expected);
        let mut balances_locked_expected = IndexMap::new();
        balances_locked_expected.insert(Currency::from("USD"), Money::from("25000 USD"));
        assert_eq!(margin_account.balances_locked(), balances_locked_expected);
        let margin_balance = margin_account_state.margins[0];
        let instrument_id = margin_balance
            .instrument_id
            .expect("stub margin balance carries a concrete instrument_id");
        let mut initial_margins_expected = IndexMap::new();
        initial_margins_expected.insert(instrument_id, margin_balance.initial);
        assert_eq!(margin_account.initial_margins(), initial_margins_expected);
        let mut maintenance_margins_expected = IndexMap::new();
        maintenance_margins_expected.insert(instrument_id, margin_balance.maintenance);
        assert_eq!(
            margin_account.maintenance_margins(),
            maintenance_margins_expected
        );
    }

    #[rstest]
    fn test_set_default_leverage(mut margin_account: MarginAccount) {
        assert_eq!(margin_account.default_leverage, Decimal::ONE);
        margin_account.set_default_leverage(Decimal::from(10));
        assert_eq!(margin_account.default_leverage, Decimal::from(10));
    }

    #[rstest]
    fn test_get_leverage_default_leverage(
        margin_account: MarginAccount,
        instrument_id_aud_usd_sim: InstrumentId,
    ) {
        assert_eq!(
            margin_account.get_leverage(&instrument_id_aud_usd_sim),
            Decimal::ONE
        );
    }

    #[rstest]
    fn test_set_leverage(
        mut margin_account: MarginAccount,
        instrument_id_aud_usd_sim: InstrumentId,
    ) {
        assert_eq!(margin_account.leverages.len(), 0);
        margin_account.set_leverage(instrument_id_aud_usd_sim, Decimal::from(10));
        assert_eq!(margin_account.leverages.len(), 1);
        assert_eq!(
            margin_account.get_leverage(&instrument_id_aud_usd_sim),
            Decimal::from(10)
        );
    }

    #[rstest]
    fn test_is_unleveraged_with_leverage_returns_false(
        mut margin_account: MarginAccount,
        instrument_id_aud_usd_sim: InstrumentId,
    ) {
        margin_account.set_leverage(instrument_id_aud_usd_sim, Decimal::from(10));
        assert!(!margin_account.is_unleveraged(instrument_id_aud_usd_sim));
    }

    #[rstest]
    fn test_is_unleveraged_with_no_leverage_returns_true(
        mut margin_account: MarginAccount,
        instrument_id_aud_usd_sim: InstrumentId,
    ) {
        margin_account.set_leverage(instrument_id_aud_usd_sim, Decimal::ONE);
        assert!(margin_account.is_unleveraged(instrument_id_aud_usd_sim));
    }

    #[rstest]
    fn test_is_unleveraged_with_default_leverage_of_1_returns_true(
        margin_account: MarginAccount,
        instrument_id_aud_usd_sim: InstrumentId,
    ) {
        assert!(margin_account.is_unleveraged(instrument_id_aud_usd_sim));
    }

    #[rstest]
    fn test_update_margin_init(
        mut margin_account: MarginAccount,
        instrument_id_aud_usd_sim: InstrumentId,
    ) {
        assert_eq!(margin_account.margins.len(), 1);
        let margin = Money::from("10000 USD");
        margin_account.update_initial_margin(instrument_id_aud_usd_sim, margin);
        assert_eq!(
            margin_account.initial_margin(instrument_id_aud_usd_sim),
            margin
        );
        assert_eq!(margin_account.margins.len(), 2);
        assert_eq!(
            margin_account
                .margins
                .get(&instrument_id_aud_usd_sim)
                .expect("AUD/USD margin should exist")
                .initial,
            margin
        );
        assert_eq!(
            margin_account
                .margins
                .get(&instrument_id_aud_usd_sim)
                .expect("AUD/USD margin should exist")
                .maintenance,
            Money::zero(margin.currency)
        );
    }

    #[rstest]
    fn test_update_margin_maintenance(
        mut margin_account: MarginAccount,
        instrument_id_aud_usd_sim: InstrumentId,
    ) {
        let margin = Money::from("10000 USD");
        margin_account.update_maintenance_margin(instrument_id_aud_usd_sim, margin);
        assert_eq!(
            margin_account.maintenance_margin(instrument_id_aud_usd_sim),
            margin
        );
        assert_eq!(margin_account.margins.len(), 2);
        assert_eq!(
            margin_account
                .margins
                .get(&instrument_id_aud_usd_sim)
                .expect("AUD/USD margin should exist")
                .maintenance,
            margin
        );
        assert_eq!(
            margin_account
                .margins
                .get(&instrument_id_aud_usd_sim)
                .expect("AUD/USD margin should exist")
                .initial,
            Money::zero(margin.currency)
        );
        // The stub margin reserves 25000 USD, so the new maintenance adds to the locked balance
        assert_eq!(
            margin_account.balance_locked(Some(Currency::USD())),
            Some(Money::from("35000 USD"))
        );
        assert_eq!(
            margin_account.balance_free(Some(Currency::USD())),
            Some(Money::from("1490000 USD"))
        );
    }

    #[rstest]
    fn test_clear_initial_margin_preserves_maintenance(
        mut margin_account: MarginAccount,
        instrument_id_aud_usd_sim: InstrumentId,
    ) {
        let usd = Currency::USD();
        margin_account.update_margin(MarginBalance::new(
            Money::from("1000 USD"),
            Money::from("500 USD"),
            Some(instrument_id_aud_usd_sim),
        ));

        assert_eq!(
            margin_account.balance_locked(Some(usd)),
            Some(Money::from("26500 USD"))
        );

        margin_account.clear_initial_margin(instrument_id_aud_usd_sim);

        let margin = margin_account
            .margin(&instrument_id_aud_usd_sim)
            .expect("margin should retain non-zero maintenance");
        assert_eq!(margin.initial, Money::from("0 USD"));
        assert_eq!(margin.maintenance, Money::from("500 USD"));
        assert_eq!(
            margin_account.balance_locked(Some(usd)),
            Some(Money::from("25500 USD"))
        );
        assert_eq!(
            margin_account.balance_free(Some(usd)),
            Some(Money::from("1499500 USD"))
        );
        assert_eq!(
            margin_account.balance_total(Some(usd)),
            Some(Money::from("1525000 USD"))
        );
    }

    #[rstest]
    fn test_clear_maintenance_margin_removes_empty_entry(
        mut margin_account: MarginAccount,
        instrument_id_aud_usd_sim: InstrumentId,
    ) {
        let usd = Currency::USD();
        margin_account.update_margin(MarginBalance::new(
            Money::from("0 USD"),
            Money::from("500 USD"),
            Some(instrument_id_aud_usd_sim),
        ));

        assert_eq!(
            margin_account.balance_locked(Some(usd)),
            Some(Money::from("25500 USD"))
        );

        margin_account.clear_maintenance_margin(instrument_id_aud_usd_sim);

        assert!(margin_account.margin(&instrument_id_aud_usd_sim).is_none());
        assert_eq!(
            margin_account.balance_locked(Some(usd)),
            Some(Money::from("25000 USD"))
        );
        assert_eq!(
            margin_account.balance_free(Some(usd)),
            Some(Money::from("1500000 USD"))
        );
    }

    #[rstest]
    fn test_clear_maintenance_margin_preserves_initial(
        mut margin_account: MarginAccount,
        instrument_id_aud_usd_sim: InstrumentId,
    ) {
        let usd = Currency::USD();
        margin_account.update_margin(MarginBalance::new(
            Money::from("1000 USD"),
            Money::from("500 USD"),
            Some(instrument_id_aud_usd_sim),
        ));

        assert_eq!(
            margin_account.balance_locked(Some(usd)),
            Some(Money::from("26500 USD"))
        );

        margin_account.clear_maintenance_margin(instrument_id_aud_usd_sim);

        let margin = margin_account
            .margin(&instrument_id_aud_usd_sim)
            .expect("margin should retain non-zero initial");
        assert_eq!(margin.initial, Money::from("1000 USD"));
        assert_eq!(margin.maintenance, Money::from("0 USD"));
        assert_eq!(
            margin_account.balance_locked(Some(usd)),
            Some(Money::from("26000 USD"))
        );
        assert_eq!(
            margin_account.balance_free(Some(usd)),
            Some(Money::from("1499000 USD"))
        );
    }

    #[rstest]
    fn test_apply_replaces_margin_balances_from_event(
        mut margin_account: MarginAccount,
        margin_account_state: AccountState,
    ) {
        let old_instrument_id = margin_account_state.margins[0]
            .instrument_id
            .expect("stub margin balance carries a concrete instrument_id");
        let new_instrument_id = InstrumentId::from("USDJPY.SIM");
        let event = AccountState::new(
            margin_account_state.account_id,
            AccountType::Margin,
            margin_account_state.balances.clone(),
            vec![MarginBalance::new(
                Money::from("12500 USD"),
                Money::from("25000 USD"),
                Some(new_instrument_id),
            )],
            true,
            uuid4(),
            1.into(),
            1.into(),
            margin_account_state.base_currency,
        );

        margin_account.apply(event).unwrap();

        assert_eq!(
            margin_account.initial_margin(new_instrument_id),
            Money::from("12500 USD")
        );
        assert_eq!(
            margin_account.maintenance_margin(new_instrument_id),
            Money::from("25000 USD")
        );
        assert!(margin_account.margin(&old_instrument_id).is_none());
    }

    #[rstest]
    fn test_account_type_predicates(margin_account: MarginAccount) {
        assert!(!margin_account.is_cash_account());
        assert!(margin_account.is_margin_account());
        assert!(!Account::is_cash_account(&margin_account));
        assert!(Account::is_margin_account(&margin_account));
    }

    #[rstest]
    fn test_equality_compares_account_ids(margin_account_state: AccountState) {
        let account = MarginAccount::new(margin_account_state.clone(), true);
        let same = MarginAccount::new(margin_account_state.clone(), true);
        let mut other_state = margin_account_state;
        other_state.account_id = AccountId::from("OTHER-001");
        let other = MarginAccount::new(other_state, true);

        assert_eq!(account, same);
        assert_ne!(account, other);
    }

    #[rstest]
    fn test_apply_routes_account_margins_when_event_has_no_balances(
        mut margin_account: MarginAccount,
        margin_account_state: AccountState,
    ) {
        let usd = Currency::USD();

        let event = AccountState::new(
            margin_account_state.account_id,
            AccountType::Margin,
            vec![],
            vec![MarginBalance::new(
                Money::from("12500 USD"),
                Money::from("25000 USD"),
                None,
            )],
            true,
            uuid4(),
            1.into(),
            1.into(),
            margin_account_state.base_currency,
        );

        margin_account.apply(event).unwrap();

        assert_eq!(
            margin_account.account_initial_margins(),
            IndexMap::from([(usd, Money::from("12500 USD"))])
        );
        assert_eq!(
            margin_account.account_maintenance_margins(),
            IndexMap::from([(usd, Money::from("25000 USD"))])
        );
    }

    #[rstest]
    fn test_apply_routes_account_margins_by_currency(
        mut margin_account: MarginAccount,
        margin_account_state: AccountState,
    ) {
        let usd = Currency::USD();
        let event = AccountState::new(
            margin_account_state.account_id,
            AccountType::Margin,
            margin_account_state.balances.clone(),
            vec![MarginBalance::new(
                Money::from("12500 USD"),
                Money::from("25000 USD"),
                None,
            )],
            true,
            uuid4(),
            1.into(),
            1.into(),
            margin_account_state.base_currency,
        );

        margin_account.apply(event).unwrap();

        assert!(margin_account.margins.is_empty());
        assert_eq!(margin_account.account_margins.len(), 1);
        assert_eq!(
            margin_account.account_initial_margin(&usd),
            Some(Money::from("12500 USD"))
        );
        assert_eq!(
            margin_account.account_maintenance_margin(&usd),
            Some(Money::from("25000 USD"))
        );
        assert_eq!(
            margin_account.total_initial_margin(usd),
            Money::from("12500 USD")
        );
    }

    #[rstest]
    fn test_apply_empty_event_preserves_margin_balances(
        mut margin_account: MarginAccount,
        margin_account_state: AccountState,
    ) {
        let instrument_id = margin_account_state.margins[0]
            .instrument_id
            .expect("stub margin balance carries a concrete instrument_id");
        let initial_margin = margin_account.initial_margin(instrument_id);
        let maintenance_margin = margin_account.maintenance_margin(instrument_id);

        let empty_event = AccountState::new(
            margin_account_state.account_id,
            AccountType::Margin,
            vec![],
            vec![],
            true,
            uuid4(),
            1.into(),
            1.into(),
            margin_account_state.base_currency,
        );

        margin_account.apply(empty_event).unwrap();

        assert_eq!(margin_account.initial_margin(instrument_id), initial_margin);
        assert_eq!(
            margin_account.maintenance_margin(instrument_id),
            maintenance_margin
        );
        assert_eq!(margin_account.event_count(), 2);
    }

    #[rstest]
    fn test_calculate_margin_init_with_leverage(
        mut margin_account: MarginAccount,
        audusd_sim: CurrencyPair,
    ) {
        margin_account.set_leverage(audusd_sim.id, Decimal::from(50));
        let result = margin_account
            .calculate_initial_margin(
                &audusd_sim,
                Quantity::from(100_000),
                Price::from("0.8000"),
                None,
            )
            .unwrap();
        assert_eq!(result, Money::from("48.00 USD"));
    }

    #[rstest]
    fn test_custom_margin_model_through_account(
        mut margin_account: MarginAccount,
        audusd_sim: CurrencyPair,
    ) {
        margin_account.set_margin_model(MarginModelHandle::new(CustomMarginModel));

        let initial = margin_account
            .calculate_initial_margin(
                &audusd_sim,
                Quantity::from(100_000),
                Price::from("0.8000"),
                None,
            )
            .unwrap();
        let maintenance = margin_account
            .calculate_maintenance_margin(
                &audusd_sim,
                Quantity::from(100_000),
                Price::from("0.8000"),
                None,
            )
            .unwrap();

        assert_eq!(margin_account.margin_model().name(), "custom");
        assert_eq!(initial, Money::from("12.34 USD"));
        assert_eq!(maintenance, Money::from("5.67 USD"));
    }

    #[rstest]
    fn test_calculate_margin_init_with_default_leverage(
        mut margin_account: MarginAccount,
        audusd_sim: CurrencyPair,
    ) {
        margin_account.set_default_leverage(Decimal::from(10));
        let result = margin_account
            .calculate_initial_margin(
                &audusd_sim,
                Quantity::from(100_000),
                Price::from("0.8"),
                None,
            )
            .unwrap();
        assert_eq!(result, Money::from("240.00 USD"));
    }

    #[rstest]
    fn test_calculate_margin_init_with_no_leverage_for_inverse(
        margin_account: MarginAccount,
        xbtusd_bitmex: CryptoPerpetual,
    ) {
        let result_use_quote_inverse_true = margin_account
            .calculate_initial_margin(
                &xbtusd_bitmex,
                Quantity::from(100_000),
                Price::from("11493.60"),
                Some(false),
            )
            .unwrap();
        assert_eq!(result_use_quote_inverse_true, Money::from("0.08700494 BTC"));
        let result_use_quote_inverse_false = margin_account
            .calculate_initial_margin(
                &xbtusd_bitmex,
                Quantity::from(100_000),
                Price::from("11493.60"),
                Some(true),
            )
            .unwrap();
        assert_eq!(result_use_quote_inverse_false, Money::from("1000 USD"));
    }

    #[rstest]
    fn test_calculate_margin_maintenance_with_no_leverage(
        margin_account: MarginAccount,
        xbtusd_bitmex: CryptoPerpetual,
    ) {
        let result = margin_account
            .calculate_maintenance_margin(
                &xbtusd_bitmex,
                Quantity::from(100_000),
                Price::from("11493.60"),
                None,
            )
            .unwrap();
        assert_eq!(result, Money::from("0.03045173 BTC"));
    }

    #[rstest]
    fn test_calculate_margin_maintenance_with_leverage_fx_instrument(
        mut margin_account: MarginAccount,
        audusd_sim: CurrencyPair,
    ) {
        margin_account.set_default_leverage(Decimal::from(50));
        let result = margin_account
            .calculate_maintenance_margin(
                &audusd_sim,
                Quantity::from(1_000_000),
                Price::from("1"),
                None,
            )
            .unwrap();
        assert_eq!(result, Money::from("600.00 USD"));
    }

    #[rstest]
    fn test_calculate_margin_maintenance_with_leverage_inverse_instrument(
        mut margin_account: MarginAccount,
        xbtusd_bitmex: CryptoPerpetual,
    ) {
        margin_account.set_default_leverage(Decimal::from(10));
        let result = margin_account
            .calculate_maintenance_margin(
                &xbtusd_bitmex,
                Quantity::from(100_000),
                Price::from("100000.00"),
                None,
            )
            .unwrap();
        assert_eq!(result, Money::from("0.00035000 BTC"));
    }

    #[rstest]
    fn test_calculate_pnls_github_issue_2657() {
        // Create a margin account
        let account_state = margin_account_state();
        let account = MarginAccount::new(account_state, false);

        // Create BTCUSDT instrument
        let btcusdt = currency_pair_btcusdt();
        let btcusdt_any = InstrumentAny::CurrencyPair(btcusdt);

        // Create initial position with BUY 0.001 BTC at 50000.00
        let fill1 = OrderFilledSpec::builder()
            .instrument_id(btcusdt_any.id())
            .client_order_id(ClientOrderId::from("O-1"))
            .venue_order_id(VenueOrderId::from("V-1"))
            .trade_id(TradeId::from("T-1"))
            .last_qty(Quantity::from("0.001"))
            .last_px(Price::from("50000.00"))
            .currency(btcusdt_any.quote_currency())
            .ts_event(UnixNanos::from(1_000_000_000))
            .position_id(PositionId::from("P-GITHUB-2657"))
            .build();

        let position = Position::new(&btcusdt_any, fill1);

        // Create second fill that sells MORE than position size (0.002 > 0.001)
        let fill2 = OrderFilledSpec::builder()
            .instrument_id(btcusdt_any.id())
            .client_order_id(ClientOrderId::from("O-2"))
            .venue_order_id(VenueOrderId::from("V-2"))
            .trade_id(TradeId::from("T-2"))
            .order_side(OrderSide::Sell)
            .last_qty(Quantity::from("0.002")) // This is larger than position quantity!
            .last_px(Price::from("50075.00"))
            .currency(btcusdt_any.quote_currency())
            .ts_event(UnixNanos::from(2_000_000_000))
            .position_id(PositionId::from("P-GITHUB-2657"))
            .build();

        // Test the fix - should only calculate PnL for position quantity (0.001), not fill quantity (0.002)
        let pnls = account
            .calculate_pnls(&btcusdt_any, &fill2, Some(position))
            .unwrap();

        // Should have exactly one PnL entry
        assert_eq!(pnls.len(), 1);

        // Expected PnL should be for 0.001 BTC, not 0.002 BTC
        // PnL = (50075.00 - 50000.00) * 0.001 = 75.0 * 0.001 = 0.075 USDT
        let expected_pnl = Money::from("0.075 USDT");
        assert_eq!(pnls[0], expected_pnl);
    }

    #[rstest]
    #[should_panic(expected = "not positive")]
    fn test_set_leverage_zero_panics(mut margin_account: MarginAccount, audusd_sim: CurrencyPair) {
        margin_account.set_leverage(audusd_sim.id, Decimal::ZERO);
    }

    #[rstest]
    #[should_panic(expected = "not positive")]
    fn test_set_default_leverage_zero_panics(mut margin_account: MarginAccount) {
        margin_account.set_default_leverage(Decimal::ZERO);
    }

    #[rstest]
    #[should_panic(expected = "not positive")]
    fn test_set_leverage_negative_panics(
        mut margin_account: MarginAccount,
        audusd_sim: CurrencyPair,
    ) {
        margin_account.set_leverage(audusd_sim.id, Decimal::from(-1));
    }

    #[rstest]
    fn test_calculate_pnls_with_same_side_fill_returns_empty() {
        use nautilus_core::UnixNanos;

        use crate::{
            events::order::spec::OrderFilledSpec,
            identifiers::{ClientOrderId, PositionId, TradeId, VenueOrderId},
            instruments::InstrumentAny,
            position::Position,
            types::{Price, Quantity},
        };

        // Create a margin account
        let account_state = margin_account_state();
        let account = MarginAccount::new(account_state, false);

        // Create BTCUSDT instrument
        let btcusdt = currency_pair_btcusdt();
        let btcusdt_any = InstrumentAny::CurrencyPair(btcusdt.clone());

        // Create initial position with BUY 1.0 BTC at 50000.00
        let fill1 = OrderFilledSpec::builder()
            .instrument_id(btcusdt.id)
            .client_order_id(ClientOrderId::from("O-1"))
            .venue_order_id(VenueOrderId::from("V-1"))
            .trade_id(TradeId::from("T-1"))
            .last_qty(Quantity::from("1.0"))
            .last_px(Price::from("50000.00"))
            .currency(btcusdt.quote_currency)
            .ts_event(UnixNanos::from(1_000_000_000))
            .position_id(PositionId::from("P-123456"))
            .build();

        let position = Position::new(&btcusdt_any, fill1);

        // Create second fill that also BUYS (same side as position entry)
        let fill2 = OrderFilledSpec::builder()
            .instrument_id(btcusdt.id)
            .client_order_id(ClientOrderId::from("O-2"))
            .venue_order_id(VenueOrderId::from("V-2"))
            .trade_id(TradeId::from("T-2"))
            .last_qty(Quantity::from("0.5"))
            .last_px(Price::from("51000.00"))
            .currency(btcusdt.quote_currency)
            .ts_event(UnixNanos::from(2_000_000_000))
            .position_id(PositionId::from("P-123456"))
            .build();

        // Test that no PnL is calculated for same-side fills
        let pnls = account
            .calculate_pnls(&btcusdt_any, &fill2, Some(position))
            .unwrap();

        // Should return empty PnL list
        assert_eq!(pnls.len(), 0);
    }

    #[rstest]
    fn test_margin_accessor(
        mut margin_account: MarginAccount,
        instrument_id_aud_usd_sim: InstrumentId,
    ) {
        let margin_balance = MarginBalance::new(
            Money::from("1000 USD"),
            Money::from("500 USD"),
            Some(instrument_id_aud_usd_sim),
        );

        margin_account.update_margin(margin_balance);

        let retrieved = margin_account.margin(&instrument_id_aud_usd_sim);
        assert!(retrieved.is_some());
        let retrieved = retrieved.unwrap();
        assert_eq!(retrieved.initial, Money::from("1000 USD"));
        assert_eq!(retrieved.maintenance, Money::from("500 USD"));
        assert_eq!(retrieved.instrument_id, Some(instrument_id_aud_usd_sim));
    }

    #[rstest]
    fn test_clear_margin(
        mut margin_account: MarginAccount,
        instrument_id_aud_usd_sim: InstrumentId,
    ) {
        let usd = Currency::USD();
        let margin_balance = MarginBalance::new(
            Money::from("1000 USD"),
            Money::from("500 USD"),
            Some(instrument_id_aud_usd_sim),
        );

        margin_account.update_margin(margin_balance);
        assert!(margin_account.margin(&instrument_id_aud_usd_sim).is_some());
        assert_eq!(
            margin_account.balance_locked(Some(usd)),
            Some(Money::from("26500 USD"))
        );
        assert_eq!(
            margin_account.balance_free(Some(usd)),
            Some(Money::from("1498500 USD"))
        );

        margin_account.clear_margin(instrument_id_aud_usd_sim);

        assert!(margin_account.margin(&instrument_id_aud_usd_sim).is_none());
        assert_eq!(
            margin_account.balance_locked(Some(usd)),
            Some(Money::from("25000 USD"))
        );
        assert_eq!(
            margin_account.balance_free(Some(usd)),
            Some(Money::from("1500000 USD"))
        );
        assert_eq!(
            margin_account.balance_total(Some(usd)),
            Some(Money::from("1525000 USD"))
        );
    }

    #[rstest]
    fn test_update_margin_routes_account_wide(mut margin_account: MarginAccount) {
        let usd = Currency::USD();
        let margin_balance =
            MarginBalance::new(Money::from("200 USD"), Money::from("100 USD"), None);

        margin_account.update_margin(margin_balance);

        assert_eq!(margin_account.account_margin(&usd), Some(margin_balance));
        assert_eq!(
            margin_account.account_initial_margin(&usd),
            Some(Money::from("200 USD"))
        );
        assert_eq!(
            margin_account.account_maintenance_margin(&usd),
            Some(Money::from("100 USD"))
        );
        assert_eq!(
            margin_account.balance_locked(Some(usd)),
            Some(Money::from("25300 USD"))
        );
        assert_eq!(
            margin_account.balance_free(Some(usd)),
            Some(Money::from("1499700 USD"))
        );

        margin_account.clear_account_margin(usd);

        assert!(margin_account.account_margin(&usd).is_none());
        assert_eq!(
            margin_account.balance_locked(Some(usd)),
            Some(Money::from("25000 USD"))
        );
        assert_eq!(
            margin_account.balance_free(Some(usd)),
            Some(Money::from("1500000 USD"))
        );
    }

    #[rstest]
    #[should_panic(expected = "Cannot get margin_init when no margin_balance")]
    fn test_initial_margin_panics_when_absent(
        margin_account: MarginAccount,
        instrument_id_aud_usd_sim: InstrumentId,
    ) {
        let _ = margin_account.initial_margin(instrument_id_aud_usd_sim);
    }

    #[rstest]
    #[should_panic(expected = "Cannot get maintenance_margin when no margin_balance")]
    fn test_maintenance_margin_panics_when_absent(
        margin_account: MarginAccount,
        instrument_id_aud_usd_sim: InstrumentId,
    ) {
        let _ = margin_account.maintenance_margin(instrument_id_aud_usd_sim);
    }

    // A multi-currency margin account (no base currency), as unified venues such as Bybit
    // report. Only `reported` carries a venue balance.
    fn multi_currency_margin_account(reported: Money) -> MarginAccount {
        let state = AccountState::new(
            AccountId::from("BYBIT-001"),
            AccountType::Margin,
            vec![AccountBalance::new(
                reported,
                Money::zero(reported.currency),
                reported,
            )],
            Vec::new(),
            true,
            uuid4(),
            0.into(),
            0.into(),
            None,
        );
        MarginAccount::new(state, true)
    }

    #[rstest]
    fn test_margin_update_leaves_unreported_currency_absent() {
        let usdt = Currency::USDT();
        let mut account = multi_currency_margin_account(Money::from("1000000 USD"));
        let instrument_id = InstrumentId::from("ETHUSDT-PERP.BINANCE");

        account.update_initial_margin(instrument_id, Money::from("5000 USDT"));

        assert_eq!(account.balance_total(Some(usdt)), None);
        assert_eq!(account.balance_locked(Some(usdt)), None);
        assert_eq!(account.balance_free(Some(usdt)), None);
        assert_eq!(
            account.balances.keys().copied().collect::<Vec<_>>(),
            vec![Currency::USD()]
        );
        assert_eq!(
            account.initial_margin(instrument_id),
            Money::from("5000 USDT")
        );
        assert_eq!(
            account.balance_free(Some(Currency::USD())),
            Some(Money::from("1000000 USD"))
        );
    }

    #[rstest]
    fn test_margin_update_locks_reported_currency() {
        let usdt = Currency::USDT();
        let mut account = multi_currency_margin_account(Money::from("100000 USDT"));
        let instrument_id = InstrumentId::from("ETHUSDT-PERP.BINANCE");

        account.update_initial_margin(instrument_id, Money::from("5000 USDT"));

        assert_eq!(
            account.balance_total(Some(usdt)),
            Some(Money::from("100000 USDT"))
        );
        assert_eq!(
            account.balance_locked(Some(usdt)),
            Some(Money::from("5000 USDT"))
        );
        assert_eq!(
            account.balance_free(Some(usdt)),
            Some(Money::from("95000 USDT"))
        );
    }

    #[rstest]
    fn test_margin_update_locks_currency_reported_after_the_margin() {
        let usdt = Currency::USDT();
        let mut account = multi_currency_margin_account(Money::from("1000000 USD"));
        let instrument_id = InstrumentId::from("ETHUSDT-PERP.BINANCE");

        account.update_initial_margin(instrument_id, Money::from("5000 USDT"));
        account
            .apply(AccountState::new(
                AccountId::from("BYBIT-001"),
                AccountType::Margin,
                vec![AccountBalance::new(
                    Money::from("100000 USDT"),
                    Money::zero(usdt),
                    Money::from("100000 USDT"),
                )],
                Vec::new(),
                true,
                uuid4(),
                0.into(),
                0.into(),
                None,
            ))
            .unwrap();
        account.update_initial_margin(instrument_id, Money::from("5000 USDT"));

        assert_eq!(
            account.balance_locked(Some(usdt)),
            Some(Money::from("5000 USDT"))
        );
        assert_eq!(
            account.balance_free(Some(usdt)),
            Some(Money::from("95000 USDT"))
        );
    }

    #[rstest]
    fn test_recalculate_balance_clamps_when_margin_exceeds_total() {
        let usdt = Currency::USDT();
        let mut account = multi_currency_margin_account(Money::from("1000 USDT"));

        account.update_initial_margin(
            InstrumentId::from("ETHUSDT-PERP.BINANCE"),
            Money::from("1500 USDT"),
        );

        assert_eq!(
            account.balance_total(Some(usdt)),
            Some(Money::from("1000 USDT"))
        );
        assert_eq!(
            account.balance_locked(Some(usdt)),
            Some(Money::from("1000 USDT"))
        );
        assert_eq!(
            account.balance_free(Some(usdt)),
            Some(Money::from("0 USDT"))
        );
    }

    #[rstest]
    fn test_recalculate_balance_keeps_locked_non_negative_when_total_negative() {
        let usd = Currency::USD();
        let mut account = multi_currency_margin_account(Money::from("-1000 USD"));
        // Seed a stale non-zero reservation so the reset to zero is observable
        account.balances.insert(
            usd,
            AccountBalance::new(
                Money::from("-1000 USD"),
                Money::from("250 USD"),
                Money::from("-1250 USD"),
            ),
        );

        account.update_initial_margin(InstrumentId::from("EURUSD.SIM"), Money::from("500 USD"));

        assert_eq!(
            account.balance_total(Some(usd)),
            Some(Money::from("-1000 USD"))
        );
        assert_eq!(
            account.balance_locked(Some(usd)),
            Some(Money::from("0 USD"))
        );
        assert_eq!(
            account.balance_free(Some(usd)),
            Some(Money::from("-1000 USD"))
        );
    }

    #[rstest]
    fn test_total_margin_sums_per_instrument_and_account_wide(
        mut margin_account: MarginAccount,
        instrument_id_aud_usd_sim: InstrumentId,
    ) {
        let usd = Currency::USD();
        let baseline_initial = margin_account.total_initial_margin(usd);
        let baseline_maintenance = margin_account.total_maintenance_margin(usd);

        margin_account.update_margin(MarginBalance::new(
            Money::from("100 USD"),
            Money::from("50 USD"),
            Some(instrument_id_aud_usd_sim),
        ));
        margin_account.update_margin(MarginBalance::new(
            Money::from("200 USD"),
            Money::from("150 USD"),
            None,
        ));

        assert_eq!(
            margin_account.total_initial_margin(usd),
            baseline_initial + Money::from("300 USD"),
        );
        assert_eq!(
            margin_account.total_maintenance_margin(usd),
            baseline_maintenance + Money::from("200 USD"),
        );
    }

    #[rstest]
    fn test_recalculate_balance_reserves_full_balance_when_margins_cannot_be_totalled() {
        let usdt = Currency::USDT();
        let mut account = multi_currency_margin_account(Money::from("1000 USDT"));
        let max = Money::from_raw(MONEY_RAW_MAX, usdt);

        // Two maximal margins overflow the sum rather than merely exceeding the balance
        for symbol in ["ETHUSDT-PERP.BINANCE", "BTCUSDT-PERP.BINANCE"] {
            let instrument_id = InstrumentId::from(symbol);
            account.margins.insert(
                instrument_id,
                MarginBalance::new(max, max, Some(instrument_id)),
            );
        }

        account.recalculate_balance(usdt);

        assert_eq!(
            account.balance_total(Some(usdt)),
            Some(Money::from("1000 USDT"))
        );
        assert_eq!(
            account.balance_locked(Some(usdt)),
            Some(Money::from("1000 USDT"))
        );
        assert_eq!(
            account.balance_free(Some(usdt)),
            Some(Money::from("0 USDT"))
        );
    }

    #[rstest]
    fn test_total_margin_clamps_domain_overflow(
        mut margin_account: MarginAccount,
        instrument_id_aud_usd_sim: InstrumentId,
    ) {
        let usd = Currency::USD();
        let max = Money::from_raw(MONEY_RAW_MAX, usd);
        let other_instrument = InstrumentId::from("EUR/USD.SIM");

        margin_account.margins.insert(
            instrument_id_aud_usd_sim,
            MarginBalance::new(max, max, Some(instrument_id_aud_usd_sim)),
        );
        margin_account.margins.insert(
            other_instrument,
            MarginBalance::new(max, max, Some(other_instrument)),
        );

        assert_eq!(margin_account.total_initial_margin(usd), max);
        assert_eq!(margin_account.total_maintenance_margin(usd), max);
    }

    #[rstest]
    fn test_total_margin_clamps_negative_domain_overflow(
        mut margin_account: MarginAccount,
        instrument_id_aud_usd_sim: InstrumentId,
    ) {
        let usd = Currency::USD();
        let min = Money::from_raw(MONEY_RAW_MIN, usd);
        let other_instrument = InstrumentId::from("EUR/USD.SIM");

        margin_account.margins.insert(
            instrument_id_aud_usd_sim,
            MarginBalance::new(min, min, Some(instrument_id_aud_usd_sim)),
        );
        margin_account.margins.insert(
            other_instrument,
            MarginBalance::new(min, min, Some(other_instrument)),
        );

        assert_eq!(margin_account.total_initial_margin(usd), min);
        assert_eq!(margin_account.total_maintenance_margin(usd), min);
    }

    #[rstest]
    fn test_calculate_pnls_for_option_buy_realizes_premium(margin_account: MarginAccount) {
        let option = option_contract_appl();
        let option_any = InstrumentAny::OptionContract(option.clone());

        let order = OrderTestBuilder::new(OrderType::Market)
            .instrument_id(option.id)
            .side(OrderSide::Buy)
            .quantity(Quantity::from("10"))
            .build();

        let fill = TestOrderEventStubs::filled(
            &order,
            &option_any,
            None,
            Some(PositionId::new("P-OPT-001")),
            Some(Price::from("5.50")),
            None,
            None,
            None,
            None,
            Some(AccountId::from("SIM-001")),
        );

        let fill_owned: crate::events::OrderFilled = fill.into();
        let pnls = margin_account
            .calculate_pnls(&option_any, &fill_owned, None)
            .unwrap();

        // BUY option = pay premium (negative PnL)
        // 10 contracts * $5.50 = $55.00 premium paid
        assert_eq!(pnls.len(), 1);
        assert_eq!(pnls[0], Money::from("-55 USD"));
    }

    #[rstest]
    fn test_calculate_pnls_for_option_sell_realizes_premium(margin_account: MarginAccount) {
        let option = option_contract_appl();
        let option_any = InstrumentAny::OptionContract(option.clone());

        let order = OrderTestBuilder::new(OrderType::Market)
            .instrument_id(option.id)
            .side(OrderSide::Sell)
            .quantity(Quantity::from("10"))
            .build();

        let fill = TestOrderEventStubs::filled(
            &order,
            &option_any,
            None,
            Some(PositionId::new("P-OPT-002")),
            Some(Price::from("5.50")),
            None,
            None,
            None,
            None,
            Some(AccountId::from("SIM-001")),
        );

        let fill_owned: crate::events::OrderFilled = fill.into();
        let pnls = margin_account
            .calculate_pnls(&option_any, &fill_owned, None)
            .unwrap();

        // SELL option = receive premium (positive PnL)
        // 10 contracts * $5.50 = $55.00 premium received
        assert_eq!(pnls.len(), 1);
        assert_eq!(pnls[0], Money::from("55 USD"));
    }

    #[rstest]
    fn test_calculate_pnls_for_binary_option(margin_account: MarginAccount) {
        let binary = binary_option();
        let binary_any = InstrumentAny::BinaryOption(binary);

        let order = OrderTestBuilder::new(OrderType::Market)
            .instrument_id(binary_any.id())
            .side(OrderSide::Buy)
            .quantity(Quantity::from("100"))
            .build();

        let fill = TestOrderEventStubs::filled(
            &order,
            &binary_any,
            None,
            Some(PositionId::new("P-BIN-001")),
            Some(Price::from("0.65")),
            None,
            None,
            None,
            None,
            Some(AccountId::from("SIM-001")),
        );

        let fill_owned: crate::events::OrderFilled = fill.into();
        let pnls = margin_account
            .calculate_pnls(&binary_any, &fill_owned, None)
            .unwrap();

        assert_eq!(pnls.len(), 1);
        assert!(pnls[0].as_f64() < 0.0);
    }
}