nautilus_deribit/common/

parse.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.
// -------------------------------------------------------------------------------------------------

//! Parsing functions for Deribit API responses into Nautilus domain types.

use std::str::FromStr;

use anyhow::Context;
use nautilus_core::{
    datetime::{NANOSECONDS_IN_MICROSECOND, NANOSECONDS_IN_MILLISECOND},
    nanos::UnixNanos,
    uuid::UUID4,
};
use nautilus_model::{
    data::{Bar, BarType, BookOrder, TradeTick},
    enums::{AccountType, AggressorSide, BookType, InstrumentClass, OptionKind, OrderSide},
    events::AccountState,
    identifiers::{AccountId, InstrumentId, Symbol, TradeId},
    instruments::{
        CryptoFuture, CryptoFuturesSpread, CryptoOption, CryptoOptionSpread, CryptoPerpetual,
        CurrencyPair, Instrument, any::InstrumentAny,
    },
    orderbook::OrderBook,
    types::{AccountBalance, Currency, MarginBalance, Money, Price, Quantity},
};
use rust_decimal::Decimal;
use ustr::Ustr;

use crate::{
    common::{
        consts::DERIBIT_VENUE,
        enums::{DeribitOptionType, DeribitProductType},
    },
    http::models::{
        DeribitAccountSummary, DeribitInstrument, DeribitOrderBook, DeribitPublicTrade,
        DeribitTradingViewChartData,
    },
    websocket::messages::DeribitPortfolioMsg,
};

/// Parses a Deribit instrument ID into kind and currency for WebSocket channel subscription.
///
/// Deribit instrument naming conventions (per Deribit docs):
/// - **Future**: `{CURRENCY}-{DMMMYY}` (e.g., "BTC-25MAR23", "BTC-5AUG23")
/// - **Perpetual**: `{CURRENCY}-PERPETUAL` (e.g., "BTC-PERPETUAL")
/// - **Option**: `{CURRENCY}-{DMMMYY}-{STRIKE}-{C|P}` (e.g., "BTC-25MAR23-420-C", "BTC-5AUG23-580-P")
/// - **Linear Option**: `{BASE}_{QUOTE}-{DMMMYY}-{STRIKE}-{C|P}` (e.g., "XRP_USDC-30JUN23-0d625-C")
///   - Note: `d` is used as decimal point for decimal strikes (0d625 = 0.625)
/// - **Future combo**: `{CURRENCY}-FS-{LEG_A}_{LEG_B}` (e.g., "BTC-FS-19MAY26_PERP")
/// - **Option combo**: `{CURRENCY}-{STRATEGY}-{DMMMYY}-{STRIKES}` (e.g., "BTC-CS-19MAY26-70000_75000",
///   "BTC-STRG-29MAY26-72000_80000", "BTC-STRD-29MAY26-77000", "BTC-BOX-25DEC26-58000_60000")
/// - **Spot**: `{BASE}_{QUOTE}` (e.g., "BTC_USDC")
///
/// Returns `(kind, currency)` tuple for `instrument.state.{kind}.{currency}` channel.
///
/// Valid kinds: `future`, `option`, `spot`, `future_combo`, `option_combo`, `any`
/// Valid currencies: `BTC`, `ETH`, `USDC`, `USDT`, `EURR`, `any`
#[must_use]
pub fn parse_instrument_kind_currency(instrument_id: &InstrumentId) -> (String, String) {
    let symbol = instrument_id.symbol.as_str();

    // Determine kind from instrument name pattern
    // Order matters: check most specific patterns first
    let kind = if symbol.contains("PERPETUAL") {
        "future" // Perpetuals are treated as futures in Deribit API
    } else if symbol.ends_with("-C") || symbol.ends_with("-P") {
        // Options end with -C (call) or -P (put)
        "option"
    } else if symbol.contains('_') && !symbol.contains('-') {
        // Spot pairs have underscore but no dash (e.g., "BTC_USDC")
        "spot"
    } else if is_combo_symbol(symbol) {
        // Combos have an alphabetic strategy code as the second segment.
        // "FS" -> future spread (e.g., BTC-FS-19MAY26_PERP);
        // any other alpha code -> option combo (CS, STRG, STRD, BOX, RR, ...).
        match second_segment(symbol) {
            Some("FS") => "future_combo",
            _ => "option_combo",
        }
    } else {
        // Default to future for expiry dates like "BTC-25MAR23"
        "future"
    };

    // Extract currency (first part before '-' or '_')
    // For most instruments, currency is the first segment
    let currency = if let Some(idx) = symbol.find('-') {
        // Futures, perpetuals, options: "BTC-..." → "BTC"
        // Linear options: "XRP_USDC-..." → extract base currency "XRP"
        let first_part = &symbol[..idx];
        if let Some(underscore_idx) = first_part.find('_') {
            first_part[..underscore_idx].to_string()
        } else {
            first_part.to_string()
        }
    } else if let Some(idx) = symbol.find('_') {
        // Spot: "BTC_USDC" → "BTC"
        symbol[..idx].to_string()
    } else {
        "any".to_string()
    };

    (kind.to_string(), currency)
}

/// Returns the segment of a Deribit symbol immediately after the currency.
///
/// For `BTC-FS-19MAY26_PERP` returns `Some("FS")`. For `BTC-PERPETUAL` returns
/// `Some("PERPETUAL")`. Returns `None` for symbols without two `-`-delimited
/// segments.
fn second_segment(symbol: &str) -> Option<&str> {
    let mut parts = symbol.split('-');
    parts.next()?;
    parts.next()
}

/// Returns `true` when the symbol matches a Deribit option- or future-combo pattern.
///
/// A combo has an alphabetic strategy code in the second segment that is not
/// `PERPETUAL` and does not look like a date (date segments start with a digit,
/// e.g., `25MAR23`).
fn is_combo_symbol(symbol: &str) -> bool {
    let Some(seg) = second_segment(symbol) else {
        return false;
    };

    if seg.is_empty() || seg == "PERPETUAL" {
        return false;
    }
    // Combo strategy codes are alphabetic; date segments start with a digit.
    seg.chars().next().is_some_and(|c| c.is_ascii_alphabetic())
        && seg.chars().all(|c| c.is_ascii_alphabetic())
}

/// Extracts server timestamp from response and converts to UnixNanos.
///
/// # Errors
///
/// Returns an error if the server timestamp (us_out) is missing from the response.
pub fn extract_server_timestamp(us_out: Option<u64>) -> anyhow::Result<UnixNanos> {
    let us_out =
        us_out.ok_or_else(|| anyhow::anyhow!("Missing server timestamp (us_out) in response"))?;
    Ok(UnixNanos::from(us_out * NANOSECONDS_IN_MICROSECOND))
}

/// Parses a Deribit instrument into a Nautilus [`InstrumentAny`].
///
/// Returns `Ok(None)` for unsupported instrument types.
///
/// # Errors
///
/// Returns an error if:
/// - Required fields are missing (e.g., strike price for options)
/// - Timestamp conversion fails
/// - Decimal conversion fails for fees
pub fn parse_deribit_instrument_any(
    instrument: &DeribitInstrument,
    ts_init: UnixNanos,
    ts_event: UnixNanos,
) -> anyhow::Result<Option<InstrumentAny>> {
    match instrument.kind {
        DeribitProductType::Spot => parse_spot_instrument(instrument, ts_init, ts_event).map(Some),
        DeribitProductType::Future => {
            // Check if it's a perpetual
            if instrument.instrument_name.as_str().contains("PERPETUAL") {
                parse_perpetual_instrument(instrument, ts_init, ts_event).map(Some)
            } else {
                parse_future_instrument(instrument, ts_init, ts_event).map(Some)
            }
        }
        DeribitProductType::Option => {
            parse_option_instrument(instrument, ts_init, ts_event).map(Some)
        }
        DeribitProductType::FutureCombo => {
            parse_future_combo_instrument(instrument, ts_init, ts_event).map(Some)
        }
        DeribitProductType::OptionCombo => {
            parse_option_combo_instrument(instrument, ts_init, ts_event).map(Some)
        }
    }
}

/// Parses a spot instrument into a [`CurrencyPair`].
fn parse_spot_instrument(
    instrument: &DeribitInstrument,
    ts_init: UnixNanos,
    ts_event: UnixNanos,
) -> anyhow::Result<InstrumentAny> {
    let instrument_id = InstrumentId::new(Symbol::new(instrument.instrument_name), *DERIBIT_VENUE);

    let base_currency = Currency::get_or_create_crypto(instrument.base_currency);
    let quote_currency = Currency::get_or_create_crypto(instrument.quote_currency);

    let price_increment = Price::from_decimal(instrument.tick_size)?;
    let size_increment = Quantity::from_decimal(instrument.min_trade_amount)?;
    let min_quantity = Quantity::from_decimal(instrument.min_trade_amount)?;

    let maker_fee = Decimal::from_str(&instrument.maker_commission.to_string())
        .context("Failed to parse maker_commission")?;
    let taker_fee = Decimal::from_str(&instrument.taker_commission.to_string())
        .context("Failed to parse taker_commission")?;

    let currency_pair = CurrencyPair::builder()
        .instrument_id(instrument_id)
        .raw_symbol(instrument.instrument_name.into())
        .base_currency(base_currency)
        .quote_currency(quote_currency)
        .price_precision(price_increment.precision)
        .size_precision(size_increment.precision)
        .price_increment(price_increment)
        .size_increment(size_increment)
        .min_quantity(min_quantity)
        .maker_fee(maker_fee)
        .taker_fee(taker_fee)
        .ts_event(ts_event)
        .ts_init(ts_init)
        .build()
        .unwrap();

    Ok(InstrumentAny::CurrencyPair(currency_pair))
}

/// Parses a perpetual swap instrument into a [`CryptoPerpetual`].
fn parse_perpetual_instrument(
    instrument: &DeribitInstrument,
    ts_init: UnixNanos,
    ts_event: UnixNanos,
) -> anyhow::Result<InstrumentAny> {
    let instrument_id = InstrumentId::new(Symbol::new(instrument.instrument_name), *DERIBIT_VENUE);

    let base_currency = Currency::get_or_create_crypto(instrument.base_currency);
    let quote_currency = Currency::get_or_create_crypto(instrument.quote_currency);
    let settlement_currency = instrument
        .settlement_currency
        .map_or(base_currency, Currency::get_or_create_crypto);

    let is_inverse = instrument
        .instrument_type
        .as_ref()
        .is_some_and(|t| t == "reversed");

    let price_increment = Price::from_decimal(instrument.tick_size)?;
    let size_increment = Quantity::from_decimal(instrument.min_trade_amount)?;
    let min_quantity = Quantity::from_decimal(instrument.min_trade_amount)?;

    let multiplier = Some(deribit_amount_quantity_multiplier());
    let lot_size = Some(size_increment);

    let maker_fee = Decimal::from_str(&instrument.maker_commission.to_string())
        .context("Failed to parse maker_commission")?;
    let taker_fee = Decimal::from_str(&instrument.taker_commission.to_string())
        .context("Failed to parse taker_commission")?;

    let perpetual = CryptoPerpetual::builder()
        .instrument_id(instrument_id)
        .raw_symbol(instrument.instrument_name.into())
        .base_currency(base_currency)
        .quote_currency(quote_currency)
        .settlement_currency(settlement_currency)
        .is_inverse(is_inverse)
        .price_precision(price_increment.precision)
        .size_precision(size_increment.precision)
        .price_increment(price_increment)
        .size_increment(size_increment)
        .maybe_multiplier(multiplier)
        .maybe_lot_size(lot_size)
        // max_quantity - Deribit doesn't specify a hard max
        .min_quantity(min_quantity)
        .maker_fee(maker_fee)
        .taker_fee(taker_fee)
        .ts_event(ts_event)
        .ts_init(ts_init)
        .build()
        .unwrap();

    Ok(InstrumentAny::CryptoPerpetual(perpetual))
}

/// Parses a futures instrument into a [`CryptoFuture`].
fn parse_future_instrument(
    instrument: &DeribitInstrument,
    ts_init: UnixNanos,
    ts_event: UnixNanos,
) -> anyhow::Result<InstrumentAny> {
    let instrument_id = InstrumentId::new(Symbol::new(instrument.instrument_name), *DERIBIT_VENUE);

    let underlying = Currency::get_or_create_crypto(instrument.base_currency);
    let quote_currency = Currency::get_or_create_crypto(instrument.quote_currency);
    let settlement_currency = instrument
        .settlement_currency
        .map_or(underlying, Currency::get_or_create_crypto);

    let is_inverse = instrument
        .instrument_type
        .as_ref()
        .is_some_and(|t| t == "reversed");

    // Convert timestamps from milliseconds to nanoseconds
    let activation_ns = (instrument.creation_timestamp as u64) * 1_000_000;
    let expiration_ns = instrument
        .expiration_timestamp
        .context("Missing expiration_timestamp for future")? as u64
        * 1_000_000; // milliseconds to nanoseconds

    let price_increment = Price::from_decimal(instrument.tick_size)?;
    let size_increment = Quantity::from_decimal(instrument.min_trade_amount)?;
    let min_quantity = Quantity::from_decimal(instrument.min_trade_amount)?;

    let multiplier = Some(deribit_amount_quantity_multiplier());
    let lot_size = Some(size_increment); // Use min_trade_amount as lot size

    let maker_fee = Decimal::from_str(&instrument.maker_commission.to_string())
        .context("Failed to parse maker_commission")?;
    let taker_fee = Decimal::from_str(&instrument.taker_commission.to_string())
        .context("Failed to parse taker_commission")?;

    let future = CryptoFuture::builder()
        .instrument_id(instrument_id)
        .raw_symbol(instrument.instrument_name.into())
        .underlying(underlying)
        .quote_currency(quote_currency)
        .settlement_currency(settlement_currency)
        .is_inverse(is_inverse)
        .activation_ns(UnixNanos::from(activation_ns))
        .expiration_ns(UnixNanos::from(expiration_ns))
        .price_precision(price_increment.precision)
        .size_precision(size_increment.precision)
        .price_increment(price_increment)
        .size_increment(size_increment)
        .maybe_multiplier(multiplier)
        .maybe_lot_size(lot_size)
        // max_quantity - Deribit doesn't specify a hard max
        .min_quantity(min_quantity)
        .maker_fee(maker_fee)
        .taker_fee(taker_fee)
        .ts_event(ts_event)
        .ts_init(ts_init)
        .build()
        .unwrap();

    Ok(InstrumentAny::CryptoFuture(future))
}

/// Parses an options instrument into a [`CryptoOption`].
fn parse_option_instrument(
    instrument: &DeribitInstrument,
    ts_init: UnixNanos,
    ts_event: UnixNanos,
) -> anyhow::Result<InstrumentAny> {
    let instrument_id = InstrumentId::new(Symbol::new(instrument.instrument_name), *DERIBIT_VENUE);
    let underlying = Currency::get_or_create_crypto(instrument.base_currency);
    let quote_currency = Currency::get_or_create_crypto(instrument.quote_currency);
    let settlement = instrument
        .settlement_currency
        .unwrap_or(instrument.base_currency);
    let settlement_currency = Currency::get_or_create_crypto(settlement);

    // Determine if inverse (settled in base currency) or linear (settled in quote/USDC)
    let is_inverse = instrument
        .instrument_type
        .as_ref()
        .is_some_and(|t| t == "reversed");

    // Determine option kind
    let option_kind = match instrument.option_type {
        Some(DeribitOptionType::Call) => OptionKind::Call,
        Some(DeribitOptionType::Put) => OptionKind::Put,
        None => anyhow::bail!("Missing option_type for option instrument"),
    };

    // Parse strike price
    let strike = instrument.strike.context("Missing strike for option")?;
    let strike_price = Price::from_decimal(strike)?;

    // Convert timestamps from milliseconds to nanoseconds
    let activation_ns = (instrument.creation_timestamp as u64) * 1_000_000;
    let expiration_ns = instrument
        .expiration_timestamp
        .context("Missing expiration_timestamp for option")? as u64
        * 1_000_000;

    let price_increment = Price::from_decimal(instrument.tick_size)?;

    let multiplier = deribit_amount_quantity_multiplier();
    let lot_size = Quantity::from_decimal(instrument.min_trade_amount)?;
    let min_trade_amount = Quantity::from_decimal(instrument.min_trade_amount)?;

    let maker_fee = Decimal::from_str(&instrument.maker_commission.to_string())
        .context("Failed to parse maker_commission")?;
    let taker_fee = Decimal::from_str(&instrument.taker_commission.to_string())
        .context("Failed to parse taker_commission")?;

    let option = CryptoOption::builder()
        .instrument_id(instrument_id)
        .raw_symbol(instrument.instrument_name.into())
        .underlying(underlying)
        .quote_currency(quote_currency)
        .settlement_currency(settlement_currency)
        .is_inverse(is_inverse)
        .option_kind(option_kind)
        .strike_price(strike_price)
        .activation_ns(UnixNanos::from(activation_ns))
        .expiration_ns(UnixNanos::from(expiration_ns))
        .price_precision(price_increment.precision)
        .size_precision(lot_size.precision)
        .price_increment(price_increment)
        .size_increment(lot_size)
        .multiplier(multiplier)
        .lot_size(lot_size)
        .min_quantity(min_trade_amount)
        .maker_fee(maker_fee)
        .taker_fee(taker_fee)
        .ts_event(ts_event)
        .ts_init(ts_init)
        .build()
        .unwrap();

    Ok(InstrumentAny::CryptoOption(option))
}

/// Parses a Deribit option combo into a [`CryptoOptionSpread`].
fn parse_option_combo_instrument(
    instrument: &DeribitInstrument,
    ts_init: UnixNanos,
    ts_event: UnixNanos,
) -> anyhow::Result<InstrumentAny> {
    let spread = build_spread_common(instrument, ts_init, ts_event)?;
    let option_spread = CryptoOptionSpread::builder()
        .instrument_id(spread.id)
        .raw_symbol(spread.raw_symbol)
        .underlying(spread.underlying)
        .quote_currency(spread.quote_currency)
        .settlement_currency(spread.settlement_currency)
        .is_inverse(spread.is_inverse)
        .strategy_type(spread.strategy_type)
        .activation_ns(spread.activation_ns)
        .expiration_ns(spread.expiration_ns)
        .price_precision(spread.price_precision)
        .size_precision(spread.size_precision)
        .price_increment(spread.price_increment)
        .size_increment(spread.size_increment)
        .multiplier(spread.multiplier)
        .lot_size(spread.lot_size)
        .min_quantity(spread.size_increment)
        .maker_fee(spread.maker_fee)
        .taker_fee(spread.taker_fee)
        .ts_event(ts_event)
        .ts_init(ts_init)
        .build()
        .unwrap();
    Ok(InstrumentAny::CryptoOptionSpread(option_spread))
}

/// Parses a Deribit future combo into a [`CryptoFuturesSpread`].
fn parse_future_combo_instrument(
    instrument: &DeribitInstrument,
    ts_init: UnixNanos,
    ts_event: UnixNanos,
) -> anyhow::Result<InstrumentAny> {
    let spread = build_spread_common(instrument, ts_init, ts_event)?;
    let futures_spread = CryptoFuturesSpread::builder()
        .instrument_id(spread.id)
        .raw_symbol(spread.raw_symbol)
        .underlying(spread.underlying)
        .quote_currency(spread.quote_currency)
        .settlement_currency(spread.settlement_currency)
        .is_inverse(spread.is_inverse)
        .strategy_type(spread.strategy_type)
        .activation_ns(spread.activation_ns)
        .expiration_ns(spread.expiration_ns)
        .price_precision(spread.price_precision)
        .size_precision(spread.size_precision)
        .price_increment(spread.price_increment)
        .size_increment(spread.size_increment)
        .multiplier(spread.multiplier)
        .lot_size(spread.lot_size)
        .min_quantity(spread.size_increment)
        .maker_fee(spread.maker_fee)
        .taker_fee(spread.taker_fee)
        .ts_event(ts_event)
        .ts_init(ts_init)
        .build()
        .unwrap();
    Ok(InstrumentAny::CryptoFuturesSpread(futures_spread))
}

/// Fields shared by [`CryptoOptionSpread`] and [`CryptoFuturesSpread`] construction
/// from a Deribit combo instrument response.
struct DeribitSpreadCommon {
    id: InstrumentId,
    raw_symbol: Symbol,
    underlying: Currency,
    quote_currency: Currency,
    settlement_currency: Currency,
    is_inverse: bool,
    strategy_type: Ustr,
    activation_ns: UnixNanos,
    expiration_ns: UnixNanos,
    price_precision: u8,
    price_increment: Price,
    size_precision: u8,
    size_increment: Quantity,
    multiplier: Quantity,
    lot_size: Quantity,
    maker_fee: Decimal,
    taker_fee: Decimal,
}

fn build_spread_common(
    instrument: &DeribitInstrument,
    _ts_init: UnixNanos,
    _ts_event: UnixNanos,
) -> anyhow::Result<DeribitSpreadCommon> {
    let id = InstrumentId::new(Symbol::new(instrument.instrument_name), *DERIBIT_VENUE);
    let raw_symbol = Symbol::new(instrument.instrument_name);
    let underlying = Currency::get_or_create_crypto(instrument.base_currency);
    let quote_currency = Currency::get_or_create_crypto(instrument.quote_currency);
    let settlement_currency = instrument
        .settlement_currency
        .map_or(underlying, Currency::get_or_create_crypto);
    let is_inverse = instrument
        .instrument_type
        .as_ref()
        .is_some_and(|t| t == "reversed");
    let strategy_type = second_segment(instrument.instrument_name.as_str())
        .map_or_else(|| Ustr::from("SPREAD"), Ustr::from);

    let activation_ns = UnixNanos::from((instrument.creation_timestamp as u64) * 1_000_000);
    let expiration_ns = UnixNanos::from(
        instrument
            .expiration_timestamp
            .context("Missing expiration_timestamp for combo")? as u64
            * 1_000_000,
    );

    let price_increment = Price::from_decimal(instrument.tick_size)?;
    let size_increment = Quantity::from_decimal(instrument.min_trade_amount)?;
    let multiplier = deribit_amount_quantity_multiplier();

    let maker_fee = Decimal::from_str(&instrument.maker_commission.to_string())
        .context("Failed to parse maker_commission")?;
    let taker_fee = Decimal::from_str(&instrument.taker_commission.to_string())
        .context("Failed to parse taker_commission")?;

    Ok(DeribitSpreadCommon {
        id,
        raw_symbol,
        underlying,
        quote_currency,
        settlement_currency,
        is_inverse,
        strategy_type,
        activation_ns,
        expiration_ns,
        price_precision: price_increment.precision,
        price_increment,
        size_precision: size_increment.precision,
        size_increment,
        multiplier,
        lot_size: size_increment,
        maker_fee,
        taker_fee,
    })
}

fn deribit_amount_quantity_multiplier() -> Quantity {
    // Deribit quantities use `amount`; `contract_size` converts amount to contract count
    Quantity::from(1)
}

/// Parses Deribit account summaries into a Nautilus [`AccountState`].
///
/// Processes multiple currency summaries and creates balance entries for each currency.
///
/// # Errors
///
/// Returns an error if:
/// - Money conversion fails for any balance field
/// - Decimal conversion fails for margin values
pub fn parse_account_state(
    summaries: &[DeribitAccountSummary],
    account_id: AccountId,
    ts_init: UnixNanos,
    ts_event: UnixNanos,
) -> anyhow::Result<AccountState> {
    let mut balances = Vec::new();
    let mut margins = Vec::new();

    // Parse each currency summary
    for summary in summaries {
        let ccy_str = summary.currency.as_str().trim();

        // Skip balances with empty currency codes
        if ccy_str.is_empty() {
            log::debug!("Skipping balance detail with empty currency code | raw_data={summary:?}");
            continue;
        }

        let currency = Currency::get_or_create_crypto_with_context(
            ccy_str,
            Some("DERIBIT - Parsing account state"),
        );

        // Segregated mode: `margin_balance` and `available_funds` are per-currency scoped.
        // Cross-margin mode: both are the cross-collateral portfolio value re-denominated
        // in this currency, summing them across currencies N-fold overcounts the same value.
        // Use `equity` (actual per-currency holdings) for total and `available_withdrawal_funds`
        // (per-currency withdrawable, ~ equity minus fee buffer) for free.
        //
        // Trade-off: in cross-margin, the risk engine reads `balance.free` as buying power
        // for new orders (see `Account::balance_free`), so this is conservative versus the
        // venue-reported `available_funds` which includes cross-collateral. Preserving that
        // value would require breaking the `total = locked + free` invariant or re-introducing
        // the cross-denominated overcount, so per-currency consistency wins here.
        let is_cross_margin = summary.cross_collateral_enabled.unwrap_or(false);
        let (total, free) = if is_cross_margin {
            (
                summary.equity,
                summary.available_withdrawal_funds.unwrap_or(Decimal::ZERO),
            )
        } else {
            (summary.margin_balance, summary.available_funds)
        };
        let balance = AccountBalance::from_total_and_free(total, free, currency)?;
        balances.push(balance);

        // Parse margin balances if present
        if let (Some(initial_margin), Some(maintenance_margin)) =
            (summary.initial_margin, summary.maintenance_margin)
            && (!initial_margin.is_zero() || !maintenance_margin.is_zero())
        {
            let initial = Money::from_decimal(initial_margin, currency)?;
            let maintenance = Money::from_decimal(maintenance_margin, currency)?;
            // Deribit reports cross-margin per collateral currency; emit as an
            // account-wide entry keyed by that currency.
            margins.push(MarginBalance::new(initial, maintenance, None));
        }
    }

    // Ensure at least one balance exists (Nautilus requires non-empty balances)
    if balances.is_empty() {
        let zero_currency = Currency::USD();
        let zero_money = Money::zero(zero_currency);
        let zero_balance = AccountBalance::new(zero_money, zero_money, zero_money);
        balances.push(zero_balance);
    }

    let account_type = AccountType::Margin;
    let is_reported = true;

    Ok(AccountState::new(
        account_id,
        account_type,
        balances,
        margins,
        is_reported,
        UUID4::new(),
        ts_event,
        ts_init,
        None,
    ))
}

/// Parses a Deribit WebSocket portfolio message into a Nautilus [`AccountState`].
///
/// This function converts real-time portfolio updates from the `user.portfolio.{currency}`
/// subscription channel into Nautilus account state events.
///
/// # Returns
///
/// An `AccountState` containing balances and margin information.
///
/// # Errors
///
/// Returns an error if Money conversion fails for any balance field.
pub fn parse_portfolio_to_account_state(
    portfolio: &DeribitPortfolioMsg,
    account_id: AccountId,
    ts_init: UnixNanos,
) -> anyhow::Result<AccountState> {
    let ccy_str = portfolio.currency.trim();

    // Skip empty currency codes
    if ccy_str.is_empty() {
        anyhow::bail!("Portfolio message has empty currency code");
    }

    let currency = Currency::get_or_create_crypto_with_context(
        ccy_str,
        Some("DERIBIT - Parsing portfolio update"),
    );

    // See `parse_account_state` for the rationale: cross-margin uses equity and
    // `available_withdrawal_funds` (per-currency consistency, conservative free balance);
    // segregated uses `margin_balance` and `available_funds` (per-currency scoped).
    let is_cross_margin = portfolio.cross_collateral_enabled.unwrap_or(false);
    let (total, free) = if is_cross_margin {
        (
            portfolio.equity,
            portfolio
                .available_withdrawal_funds
                .unwrap_or(Decimal::ZERO),
        )
    } else {
        (portfolio.margin_balance, portfolio.available_funds)
    };
    let balance = AccountBalance::from_total_and_free(total, free, currency)?;
    let balances = vec![balance];

    // Parse margin balances
    let mut margins = Vec::new();
    let initial_margin = portfolio.initial_margin;
    let maintenance_margin = portfolio.maintenance_margin;

    // Only create margin balance if there are actual margin requirements
    if !initial_margin.is_zero() || !maintenance_margin.is_zero() {
        let initial = Money::from_decimal(initial_margin, currency)?;
        let maintenance = Money::from_decimal(maintenance_margin, currency)?;
        // Deribit reports cross-margin per collateral currency; emit as an
        // account-wide entry keyed by that currency.
        margins.push(MarginBalance::new(initial, maintenance, None));
    }

    let account_type = AccountType::Margin;
    let is_reported = true;

    Ok(AccountState::new(
        account_id,
        account_type,
        balances,
        margins,
        is_reported,
        UUID4::new(),
        ts_init, // Use ts_init for both since we don't have server timestamp in portfolio msg
        ts_init,
        None,
    ))
}

/// Builds a [`TradeId`] for a Deribit public trade, prefixing the venue ID with
/// the trade's provenance when applicable.
///
/// Strategies that need to distinguish RFQ-, block-, or combo-origin trades from
/// plain trades can pattern-match the prefix on the resulting `TradeId`. The
/// raw Deribit `trade_id` is preserved after the prefix so correlation back to
/// the venue is straightforward via a prefix strip.
///
/// Precedence (most specific wins): `RFQ-` > `BLK-` > `COMBO-` > unprefixed.
/// Block RFQs are themselves block trades on Deribit, so the `RFQ-` tag is the
/// stronger signal; combo trades executed as blocks are tagged `BLK-` since
/// the block flow is the more important reconciliation signal.
#[must_use]
pub fn build_public_trade_id(
    trade_id: &str,
    block_rfq_id: Option<i64>,
    block_trade_id: Option<&str>,
    combo_id: Option<&str>,
) -> TradeId {
    if block_rfq_id.is_some() {
        TradeId::new(format!("RFQ-{trade_id}"))
    } else if block_trade_id.is_some() {
        TradeId::new(format!("BLK-{trade_id}"))
    } else if combo_id.is_some() {
        TradeId::new(format!("COMBO-{trade_id}"))
    } else {
        TradeId::new(trade_id)
    }
}

// Parses a Deribit public trade into a Nautilus [`TradeTick`].
///
/// # Errors
///
/// Returns an error if:
/// - The direction is not "buy" or "sell"
/// - Decimal conversion fails for price or size
pub fn parse_trade_tick(
    trade: &DeribitPublicTrade,
    instrument_id: InstrumentId,
    price_precision: u8,
    size_precision: u8,
    ts_init: UnixNanos,
) -> anyhow::Result<TradeTick> {
    // Parse aggressor side from direction
    let aggressor_side = match trade.direction.as_str() {
        "buy" => AggressorSide::Buy,
        "sell" => AggressorSide::Sell,
        other => anyhow::bail!("Invalid trade direction: {other}"),
    };
    let price = Price::from_decimal_dp(trade.price, price_precision)?;
    let size = Quantity::from_decimal_dp(trade.amount, size_precision)?;
    let ts_event = UnixNanos::from((trade.timestamp as u64) * NANOSECONDS_IN_MILLISECOND);
    let trade_id = build_public_trade_id(
        &trade.trade_id,
        trade.block_rfq_id,
        trade.block_trade_id.as_deref(),
        trade.combo_id.as_deref(),
    );

    Ok(TradeTick::new(
        instrument_id,
        price,
        size,
        aggressor_side,
        trade_id,
        ts_event,
        ts_init,
    ))
}

/// Returns true when `Bar.volume` should be populated from the chart `cost` field (USD) instead
/// of the `volume` field (base currency).
///
/// Deribit's `trades.{instrument}` channel reports each trade's `amount` in USD for inverse
/// perpetuals and inverse futures, and in the underlying base currency for options and linear
/// futures. To keep `Bar.volume` and `TradeTick.size` on a single unit per instrument, route
/// inverse non-option products through `cost`. Options and option spreads stay on `volume` even
/// when flagged `is_inverse`, because their trade `amount` is reported in base currency.
///
/// Reference: <https://docs.deribit.com/api-reference/market-data/public-get_last_trades_by_currency>
#[must_use]
pub fn use_cost_for_bar_volume(instrument: &InstrumentAny) -> bool {
    if !instrument.is_inverse() {
        return false;
    }
    !matches!(
        instrument.instrument_class(),
        InstrumentClass::Option | InstrumentClass::OptionSpread
    )
}

/// Parses Deribit TradingView chart data into Nautilus [`Bar`]s.
///
/// Converts OHLCV arrays from the `public/get_tradingview_chart_data` endpoint
/// into a vector of [`Bar`] objects.
///
/// When `use_cost_for_volume` is true, `Bar.volume` is populated from `chart_data.cost` (USD)
/// instead of `chart_data.volume` (base currency) - see [`use_cost_for_bar_volume`].
///
/// # Errors
///
/// Returns an error if:
/// - The status is not "ok"
/// - Array lengths are inconsistent
/// - No data points are present
pub fn parse_bars(
    chart_data: &DeribitTradingViewChartData,
    bar_type: BarType,
    price_precision: u8,
    size_precision: u8,
    use_cost_for_volume: bool,
    ts_init: UnixNanos,
) -> anyhow::Result<Vec<Bar>> {
    // Check status
    if chart_data.status != "ok" {
        anyhow::bail!(
            "Chart data status is '{}', expected 'ok'",
            chart_data.status
        );
    }

    let num_bars = chart_data.ticks.len();

    // Verify array lengths match
    anyhow::ensure!(
        chart_data.open.len() == num_bars
            && chart_data.high.len() == num_bars
            && chart_data.low.len() == num_bars
            && chart_data.close.len() == num_bars
            && chart_data.volume.len() == num_bars
            && chart_data.cost.len() == num_bars,
        "Inconsistent array lengths in chart data"
    );

    if num_bars == 0 {
        return Ok(Vec::new());
    }

    let mut bars = Vec::with_capacity(num_bars);

    for i in 0..num_bars {
        let open = Price::new_checked(chart_data.open[i], price_precision)
            .with_context(|| format!("Invalid open price at index {i}"))?;
        let high = Price::new_checked(chart_data.high[i], price_precision)
            .with_context(|| format!("Invalid high price at index {i}"))?;
        let low = Price::new_checked(chart_data.low[i], price_precision)
            .with_context(|| format!("Invalid low price at index {i}"))?;
        let close = Price::new_checked(chart_data.close[i], price_precision)
            .with_context(|| format!("Invalid close price at index {i}"))?;
        let raw_volume = if use_cost_for_volume {
            chart_data.cost[i]
        } else {
            chart_data.volume[i]
        };
        let volume = Quantity::new_checked(raw_volume, size_precision)
            .with_context(|| format!("Invalid volume at index {i}"))?;

        // Convert timestamp from milliseconds to nanoseconds
        let ts_event = UnixNanos::from((chart_data.ticks[i] as u64) * NANOSECONDS_IN_MILLISECOND);

        let bar = Bar::new_checked(bar_type, open, high, low, close, volume, ts_event, ts_init)
            .with_context(|| format!("Invalid OHLC bar at index {i}"))?;
        bars.push(bar);
    }

    Ok(bars)
}

/// Parses Deribit order book data into a Nautilus [`OrderBook`].
///
/// Converts bids and asks from the `public/get_order_book` endpoint
/// into an L2_MBP order book.
///
/// # Errors
///
/// Returns an error if order book creation fails.
pub fn parse_order_book(
    order_book_data: &DeribitOrderBook,
    instrument_id: InstrumentId,
    price_precision: u8,
    size_precision: u8,
    ts_init: UnixNanos,
) -> anyhow::Result<OrderBook> {
    let ts_event = UnixNanos::from((order_book_data.timestamp as u64) * NANOSECONDS_IN_MILLISECOND);
    let mut book = OrderBook::new(instrument_id, BookType::L2_MBP);

    for (idx, [price, amount]) in order_book_data.bids.iter().enumerate() {
        let order = BookOrder::new(
            OrderSide::Buy,
            Price::new(*price, price_precision),
            Quantity::new(*amount, size_precision),
            idx as u64,
        );
        book.add(order, 0, idx as u64, ts_event);
    }

    let bids_len = order_book_data.bids.len();
    for (idx, [price, amount]) in order_book_data.asks.iter().enumerate() {
        let order = BookOrder::new(
            OrderSide::Sell,
            Price::new(*price, price_precision),
            Quantity::new(*amount, size_precision),
            (bids_len + idx) as u64,
        );
        book.add(order, 0, (bids_len + idx) as u64, ts_event);
    }

    book.ts_last = ts_init;

    Ok(book)
}

/// Converts a Nautilus BarType to a Deribit chart resolution.
///
/// Deribit resolutions: "1", "3", "5", "10", "15", "30", "60", "120", "180", "360", "720", "1D"
pub fn bar_spec_to_resolution(bar_type: &BarType) -> String {
    use nautilus_model::enums::BarAggregation;

    let spec = bar_type.spec();
    match spec.aggregation {
        BarAggregation::Minute => {
            let step = spec.step.get();
            // Map to nearest Deribit resolution
            match step {
                1 => "1".to_string(),
                2..=3 => "3".to_string(),
                4..=5 => "5".to_string(),
                6..=10 => "10".to_string(),
                11..=15 => "15".to_string(),
                16..=30 => "30".to_string(),
                31..=60 => "60".to_string(),
                61..=120 => "120".to_string(),
                121..=180 => "180".to_string(),
                181..=360 => "360".to_string(),
                361..=720 => "720".to_string(),
                _ => "1D".to_string(),
            }
        }
        BarAggregation::Hour => {
            let step = spec.step.get();
            match step {
                1 => "60".to_string(),
                2 => "120".to_string(),
                3 => "180".to_string(),
                4..=6 => "360".to_string(),
                7..=12 => "720".to_string(),
                _ => "1D".to_string(),
            }
        }
        BarAggregation::Day => "1D".to_string(),
        _ => {
            log::warn!(
                "Unsupported bar aggregation {:?}, defaulting to 1 minute",
                spec.aggregation
            );
            "1".to_string()
        }
    }
}

#[cfg(test)]
mod tests {
    use nautilus_model::{instruments::Instrument, types::Money};
    use rstest::rstest;
    use rust_decimal_macros::dec;

    use super::*;
    use crate::{
        common::testing::load_test_json,
        http::models::{
            DeribitAccountSummariesResponse, DeribitJsonRpcResponse, DeribitTradesResponse,
        },
    };

    #[rstest]
    fn test_parse_perpetual_instrument() {
        let json_data = load_test_json("http_get_instrument.json");
        let response: DeribitJsonRpcResponse<DeribitInstrument> =
            serde_json::from_str(&json_data).unwrap();
        let deribit_inst = response.result.expect("Test data must have result");

        let instrument_any =
            parse_deribit_instrument_any(&deribit_inst, UnixNanos::default(), UnixNanos::default())
                .unwrap();
        let instrument = instrument_any.expect("Should parse perpetual instrument");

        let InstrumentAny::CryptoPerpetual(perpetual) = instrument else {
            panic!("Expected CryptoPerpetual, was {instrument:?}");
        };
        assert_eq!(perpetual.id(), InstrumentId::from("BTC-PERPETUAL.DERIBIT"));
        assert_eq!(perpetual.raw_symbol(), Symbol::from("BTC-PERPETUAL"));
        assert_eq!(perpetual.base_currency().unwrap().code, "BTC");
        assert_eq!(perpetual.quote_currency().code, "USD");
        assert_eq!(perpetual.settlement_currency().code, "BTC");
        assert!(perpetual.is_inverse());
        assert_eq!(perpetual.price_precision(), 1);
        assert_eq!(perpetual.size_precision(), 0);
        assert_eq!(perpetual.price_increment(), Price::from("0.5"));
        assert_eq!(perpetual.size_increment(), Quantity::from("10"));
        assert_eq!(perpetual.multiplier(), Quantity::from("1"));
        assert_eq!(
            perpetual.calculate_notional_value(
                Quantity::from("10"),
                Price::from("50000"),
                Some(false)
            ),
            Money::from("0.0002 BTC")
        );
        assert_eq!(
            perpetual.calculate_notional_value(
                Quantity::from("10"),
                Price::from("50000"),
                Some(true)
            ),
            Money::from("10 USD")
        );
        assert_eq!(perpetual.lot_size(), Some(Quantity::from("10")));
        assert_eq!(perpetual.maker_fee(), dec!(0));
        assert_eq!(perpetual.taker_fee(), dec!(0.0005));
        assert_eq!(perpetual.max_quantity(), None);
        assert_eq!(perpetual.min_quantity(), Some(Quantity::from("10")));
    }

    #[rstest]
    fn test_parse_future_instrument() {
        let json_data = load_test_json("http_get_instruments.json");
        let response: DeribitJsonRpcResponse<Vec<DeribitInstrument>> =
            serde_json::from_str(&json_data).unwrap();
        let instruments = response.result.expect("Test data must have result");
        let deribit_inst = instruments
            .iter()
            .find(|i| i.instrument_name.as_str() == "BTC-27DEC24")
            .expect("Test data must contain BTC-27DEC24");

        let instrument_any =
            parse_deribit_instrument_any(deribit_inst, UnixNanos::default(), UnixNanos::default())
                .unwrap();
        let instrument = instrument_any.expect("Should parse future instrument");

        let InstrumentAny::CryptoFuture(future) = instrument else {
            panic!("Expected CryptoFuture, was {instrument:?}");
        };
        assert_eq!(future.id(), InstrumentId::from("BTC-27DEC24.DERIBIT"));
        assert_eq!(future.raw_symbol(), Symbol::from("BTC-27DEC24"));
        assert_eq!(future.underlying().unwrap(), "BTC");
        assert_eq!(future.quote_currency().code, "USD");
        assert_eq!(future.settlement_currency().code, "BTC");
        assert!(future.is_inverse());

        // Verify timestamps
        assert_eq!(
            future.activation_ns(),
            Some(UnixNanos::from(1719561600000_u64 * 1_000_000))
        );
        assert_eq!(
            future.expiration_ns(),
            Some(UnixNanos::from(1735300800000_u64 * 1_000_000))
        );
        assert_eq!(future.price_precision(), 1);
        assert_eq!(future.size_precision(), 0);
        assert_eq!(future.price_increment(), Price::from("0.5"));
        assert_eq!(future.size_increment(), Quantity::from("10"));
        assert_eq!(future.multiplier(), Quantity::from("1"));
        assert_eq!(future.lot_size(), Some(Quantity::from("10")));
        assert_eq!(future.maker_fee, dec!(0));
        assert_eq!(future.taker_fee, dec!(0.0005));
    }

    #[rstest]
    fn test_parse_option_instrument() {
        let json_data = load_test_json("http_get_instruments.json");
        let response: DeribitJsonRpcResponse<Vec<DeribitInstrument>> =
            serde_json::from_str(&json_data).unwrap();
        let instruments = response.result.expect("Test data must have result");
        let deribit_inst = instruments
            .iter()
            .find(|i| i.instrument_name.as_str() == "BTC-27DEC24-100000-C")
            .expect("Test data must contain BTC-27DEC24-100000-C");

        let instrument_any =
            parse_deribit_instrument_any(deribit_inst, UnixNanos::default(), UnixNanos::default())
                .unwrap();
        let instrument = instrument_any.expect("Should parse option instrument");

        // Verify it's a CryptoOption
        let InstrumentAny::CryptoOption(option) = instrument else {
            panic!("Expected CryptoOption, was {instrument:?}");
        };

        assert_eq!(
            option.id(),
            InstrumentId::from("BTC-27DEC24-100000-C.DERIBIT")
        );
        assert_eq!(option.raw_symbol(), Symbol::from("BTC-27DEC24-100000-C"));
        assert_eq!(option.underlying.code.as_str(), "BTC");
        assert_eq!(option.quote_currency.code.as_str(), "BTC");
        assert_eq!(option.settlement_currency.code.as_str(), "BTC");
        assert!(option.is_inverse);
        assert_eq!(option.option_kind, OptionKind::Call);
        assert_eq!(option.strike_price, Price::from("100000"));
        assert_eq!(
            option.activation_ns,
            UnixNanos::from(1719561600000_u64 * 1_000_000)
        );
        assert_eq!(
            option.expiration_ns,
            UnixNanos::from(1735300800000_u64 * 1_000_000)
        );
        assert_eq!(option.price_precision, 4);
        assert_eq!(option.price_increment, Price::from("0.0005"));
        assert_eq!(option.size_precision, 1);
        assert_eq!(option.size_increment, Quantity::from("0.1"));
        assert_eq!(option.multiplier, Quantity::from("1"));
        assert_eq!(option.lot_size, Quantity::from("0.1"));
        assert_eq!(option.maker_fee, dec!(0.0003));
        assert_eq!(option.taker_fee, dec!(0.0003));
    }

    #[rstest]
    fn test_parse_account_state_with_positions() {
        let json_data = load_test_json("http_get_account_summaries.json");
        let response: DeribitJsonRpcResponse<DeribitAccountSummariesResponse> =
            serde_json::from_str(&json_data).unwrap();
        let result = response.result.expect("Test data must have result");

        let account_id = AccountId::from("DERIBIT-001");

        // Extract server timestamp from response
        let ts_event =
            extract_server_timestamp(response.us_out).expect("Test data must have us_out");
        let ts_init = UnixNanos::default();

        let account_state = parse_account_state(&result.summaries, account_id, ts_init, ts_event)
            .expect("Should parse account state");

        // Verify we got 2 currencies (BTC and ETH)
        assert_eq!(account_state.balances.len(), 2);

        // Test BTC balance (has open positions with unrealized PnL)
        let btc_balance = account_state
            .balances
            .iter()
            .find(|b| b.currency.code == "BTC")
            .expect("BTC balance should exist");

        // From test data:
        // margin_balance: 302.62729214, available_funds: 301.38059622
        // initial_margin: 1.24669592
        //
        // Using margin_balance:
        // total = margin_balance = 302.62729214
        // free = available_funds = 301.38059622
        // locked = total - free = 302.62729214 - 301.38059622 = 1.24669592 (exactly initial_margin!)
        assert_eq!(btc_balance.total.as_f64(), 302.62729214);
        assert_eq!(btc_balance.free.as_f64(), 301.38059622);

        // Verify locked equals initial_margin exactly
        let locked = btc_balance.locked.as_f64();
        assert!(
            locked > 0.0,
            "Locked should be positive when positions exist"
        );
        assert!(
            (locked - 1.24669592).abs() < 0.0001,
            "Locked ({locked}) should equal initial_margin (1.24669592)"
        );

        // Test ETH balance (no positions)
        let eth_balance = account_state
            .balances
            .iter()
            .find(|b| b.currency.code == "ETH")
            .expect("ETH balance should exist");

        // From test data: margin_balance: 100, available_funds: 99.999598, initial_margin: 0.000402
        // total = margin_balance = 100
        // free = available_funds = 99.999598
        // locked = 100 - 99.999598 = 0.000402 (equals initial_margin)
        assert_eq!(eth_balance.total.as_f64(), 100.0);
        assert_eq!(eth_balance.free.as_f64(), 99.999598);
        assert_eq!(eth_balance.locked.as_f64(), 0.000402);

        // Verify account metadata
        assert_eq!(account_state.account_id, account_id);
        assert_eq!(account_state.account_type, AccountType::Margin);
        assert!(account_state.is_reported);

        // Verify ts_event matches server timestamp (us_out = 1687352432005000 microseconds)
        let expected_ts_event = UnixNanos::from(1687352432005000_u64 * NANOSECONDS_IN_MICROSECOND);
        assert_eq!(
            account_state.ts_event, expected_ts_event,
            "ts_event should match server timestamp from response"
        );
    }

    #[rstest]
    fn test_parse_account_state_cross_margin() {
        let json_data = load_test_json("http_get_account_summaries_cross_margin.json");
        let response: DeribitJsonRpcResponse<DeribitAccountSummariesResponse> =
            serde_json::from_str(&json_data).unwrap();
        let result = response.result.expect("Test data must have result");

        let account_id = AccountId::from("DERIBIT-001");
        let ts_event =
            extract_server_timestamp(response.us_out).expect("Test data must have us_out");
        let ts_init = UnixNanos::default();

        let account_state = parse_account_state(&result.summaries, account_id, ts_init, ts_event)
            .expect("Should parse cross-margin account state");

        // All 4 currencies in fixture have cross_collateral_enabled=true (cross_pm mode)
        // BTC: equity=2.288e-5 (actual holding), margin_balance=3.1639e-4 (portfolio-wide)
        // USDT: equity=23.61869 (actual holding), margin_balance=25.713074 (portfolio-wide)
        // SOL: equity=0 (no holding), margin_balance=0.29488918 (phantom)
        // ETH: equity=8.6e-5 (small holding), margin_balance=0.01089 (portfolio-wide)

        assert_eq!(account_state.balances.len(), 4);

        // BTC: total should be equity (2.288e-5), NOT margin_balance (3.1639e-4)
        let btc = account_state
            .balances
            .iter()
            .find(|b| b.currency.code == "BTC")
            .expect("BTC balance should exist");
        assert_eq!(btc.total.as_f64(), 2.288e-5);
        assert_eq!(btc.free.as_f64(), 2.288e-5); // available_withdrawal_funds
        assert_eq!(btc.locked.as_f64(), 0.0);

        // USDT: total should be equity (23.61869), NOT margin_balance (25.713074)
        let usdt = account_state
            .balances
            .iter()
            .find(|b| b.currency.code == "USDT")
            .expect("USDT balance should exist");
        assert_eq!(usdt.total.as_f64(), 23.61869);
        assert_eq!(usdt.free.as_f64(), 23.618645); // available_withdrawal_funds
        let usdt_locked = usdt.locked.as_f64();
        assert!(
            (usdt_locked - 0.000045).abs() < 0.001,
            "USDT locked ({usdt_locked}) should be close to 0.000045"
        );

        // SOL: equity=0, should produce zero balance (not margin_balance=0.29488918)
        let sol = account_state
            .balances
            .iter()
            .find(|b| b.currency.code == "SOL")
            .expect("SOL balance should exist");
        assert_eq!(sol.total.as_f64(), 0.0);
        assert_eq!(sol.free.as_f64(), 0.0);

        // ETH: equity=8.6e-5 (small holding), NOT margin_balance=0.01089 (portfolio-wide)
        let eth = account_state
            .balances
            .iter()
            .find(|b| b.currency.code == "ETH")
            .expect("ETH balance should exist");
        assert_eq!(eth.total.as_f64(), 8.6e-5);
        assert_eq!(eth.free.as_f64(), 8.5e-5); // available_withdrawal_funds

        // Verify account metadata
        assert_eq!(account_state.account_type, AccountType::Margin);
        assert!(account_state.is_reported);
    }

    #[rstest]
    fn test_parse_trade_tick_sell() {
        let json_data = load_test_json("http_get_last_trades.json");
        let response: DeribitJsonRpcResponse<DeribitTradesResponse> =
            serde_json::from_str(&json_data).unwrap();
        let result = response.result.expect("Test data must have result");

        assert!(result.has_more, "has_more should be true");
        assert_eq!(result.trades.len(), 10, "Should have 10 trades");

        let raw_trade = &result.trades[0];
        let instrument_id = InstrumentId::from("ETH-PERPETUAL.DERIBIT");
        let ts_init = UnixNanos::from(1766335632425576_u64 * 1000); // from usOut

        let trade = parse_trade_tick(raw_trade, instrument_id, 1, 0, ts_init)
            .expect("Should parse trade tick");

        assert_eq!(trade.instrument_id, instrument_id);
        assert_eq!(trade.price, Price::from("2968.3"));
        assert_eq!(trade.size, Quantity::from("1"));
        assert_eq!(trade.aggressor_side, AggressorSide::Sell);
        assert_eq!(trade.trade_id, TradeId::new("ETH-284830839"));
        // timestamp 1766332040636 ms -> ns
        assert_eq!(
            trade.ts_event,
            UnixNanos::from(1766332040636_u64 * 1_000_000)
        );
        assert_eq!(trade.ts_init, ts_init);
    }

    #[rstest]
    fn test_parse_trade_tick_buy() {
        let json_data = load_test_json("http_get_last_trades.json");
        let response: DeribitJsonRpcResponse<DeribitTradesResponse> =
            serde_json::from_str(&json_data).unwrap();
        let result = response.result.expect("Test data must have result");

        // Last trade is a buy with amount 106
        let raw_trade = &result.trades[9];
        let instrument_id = InstrumentId::from("ETH-PERPETUAL.DERIBIT");
        let ts_init = UnixNanos::default();

        let trade = parse_trade_tick(raw_trade, instrument_id, 1, 0, ts_init)
            .expect("Should parse trade tick");

        assert_eq!(trade.instrument_id, instrument_id);
        assert_eq!(trade.price, Price::from("2968.3"));
        assert_eq!(trade.size, Quantity::from("106"));
        assert_eq!(trade.aggressor_side, AggressorSide::Buy);
        assert_eq!(trade.trade_id, TradeId::new("ETH-284830854"));
    }

    /// Builds a minimal [`DeribitPublicTrade`] via JSON to exercise the HTTP
    /// trade-tick path. Mirrors the WS-side `make_trade_msg` helper.
    fn make_public_trade(
        trade_id: &str,
        block_trade_id: Option<&str>,
        block_rfq_id: Option<i64>,
        combo_id: Option<&str>,
    ) -> DeribitPublicTrade {
        let raw = serde_json::json!({
            "trade_id": trade_id,
            "instrument_name": "BTC-PERPETUAL",
            "price": 77000.0,
            "amount": 10.0,
            "direction": "buy",
            "timestamp": 1_779_107_386_210_i64,
            "trade_seq": 1,
            "tick_direction": 0,
            "block_trade_id": block_trade_id,
            "block_rfq_id": block_rfq_id,
            "combo_id": combo_id,
        });
        serde_json::from_value(raw).unwrap()
    }

    #[rstest]
    #[case::block_rfq(None, Some(99_i64), None, "RFQ-244343055")]
    #[case::block_trade(Some("12345"), None, None, "BLK-244343055")]
    #[case::combo_leg(None, None, Some("BTC-FS-25DEC26_PERP"), "COMBO-244343055")]
    fn test_parse_trade_tick_provenance_prefix(
        #[case] block_trade_id: Option<&str>,
        #[case] block_rfq_id: Option<i64>,
        #[case] combo_id: Option<&str>,
        #[case] expected_trade_id: &str,
    ) {
        let trade = make_public_trade("244343055", block_trade_id, block_rfq_id, combo_id);
        let instrument_id = InstrumentId::from("BTC-PERPETUAL.DERIBIT");
        let tick = parse_trade_tick(&trade, instrument_id, 1, 0, UnixNanos::default())
            .expect("Should parse trade tick");
        assert_eq!(tick.trade_id, TradeId::new(expected_trade_id));
    }

    #[rstest]
    fn test_use_cost_for_bar_volume() {
        // Inverse perpetual: BTC-PERPETUAL → cost (USD)
        let perp_json = load_test_json("http_get_instrument.json");
        let perp_response: DeribitJsonRpcResponse<DeribitInstrument> =
            serde_json::from_str(&perp_json).unwrap();
        let perp_inst = perp_response.result.expect("Test data must have result");
        let perp =
            parse_deribit_instrument_any(&perp_inst, UnixNanos::default(), UnixNanos::default())
                .unwrap()
                .expect("Should parse perpetual");
        assert!(perp.is_inverse());
        assert!(use_cost_for_bar_volume(&perp));

        // BTC inverse option: is_inverse, but trade amount is in BTC, so stay on volume
        let instruments_json = load_test_json("http_get_instruments.json");
        let instruments_response: DeribitJsonRpcResponse<Vec<DeribitInstrument>> =
            serde_json::from_str(&instruments_json).unwrap();
        let instruments = instruments_response
            .result
            .expect("Test data must have result");

        let option_inst = instruments
            .iter()
            .find(|i| i.instrument_name.as_str() == "BTC-27DEC24-100000-C")
            .expect("Test data must contain BTC-27DEC24-100000-C");
        let option =
            parse_deribit_instrument_any(option_inst, UnixNanos::default(), UnixNanos::default())
                .unwrap()
                .expect("Should parse option");
        assert!(option.is_inverse());
        assert!(
            !use_cost_for_bar_volume(&option),
            "options report trade amount in base currency, must keep using volume",
        );

        // Inverse future: same convention as perp - cost (USD)
        let future_inst = instruments
            .iter()
            .find(|i| i.instrument_name.as_str() == "BTC-27DEC24")
            .expect("Test data must contain BTC-27DEC24");
        let future =
            parse_deribit_instrument_any(future_inst, UnixNanos::default(), UnixNanos::default())
                .unwrap()
                .expect("Should parse future");
        assert!(future.is_inverse());
        assert!(use_cost_for_bar_volume(&future));
    }

    #[rstest]
    fn test_parse_bars_uses_volume_field() {
        let json_data = load_test_json("http_get_tradingview_chart_data.json");
        let response: DeribitJsonRpcResponse<DeribitTradingViewChartData> =
            serde_json::from_str(&json_data).unwrap();
        let chart_data = response.result.expect("Test data must have result");

        let bar_type = BarType::from("BTC-PERPETUAL.DERIBIT-1-MINUTE-LAST-EXTERNAL");
        let ts_init = UnixNanos::from(1766487086146245_u64 * NANOSECONDS_IN_MICROSECOND);

        let bars =
            parse_bars(&chart_data, bar_type, 1, 8, false, ts_init).expect("Should parse bars");

        assert_eq!(bars.len(), 5, "Should parse 5 bars");

        // Verify first bar
        let first_bar = &bars[0];
        assert_eq!(first_bar.bar_type, bar_type);
        assert_eq!(first_bar.open, Price::from("87451.0"));
        assert_eq!(first_bar.high, Price::from("87456.5"));
        assert_eq!(first_bar.low, Price::from("87451.0"));
        assert_eq!(first_bar.close, Price::from("87456.5"));
        assert_eq!(first_bar.volume, Quantity::from("2.94375216"));
        assert_eq!(
            first_bar.ts_event,
            UnixNanos::from(1766483460000_u64 * NANOSECONDS_IN_MILLISECOND)
        );
        assert_eq!(first_bar.ts_init, ts_init);

        // Verify last bar
        let last_bar = &bars[4];
        assert_eq!(last_bar.open, Price::from("87456.0"));
        assert_eq!(last_bar.high, Price::from("87456.5"));
        assert_eq!(last_bar.low, Price::from("87456.0"));
        assert_eq!(last_bar.close, Price::from("87456.0"));
        assert_eq!(last_bar.volume, Quantity::from("0.1018798"));
        assert_eq!(
            last_bar.ts_event,
            UnixNanos::from(1766483700000_u64 * NANOSECONDS_IN_MILLISECOND)
        );
    }

    #[rstest]
    fn test_parse_bars_cost_path() {
        let json_data = load_test_json("http_get_tradingview_chart_data.json");
        let response: DeribitJsonRpcResponse<DeribitTradingViewChartData> =
            serde_json::from_str(&json_data).unwrap();
        let chart_data = response.result.expect("Test data must have result");

        let bar_type = BarType::from("BTC-PERPETUAL.DERIBIT-1-MINUTE-LAST-EXTERNAL");
        let ts_init = UnixNanos::from(1766487086146245_u64 * NANOSECONDS_IN_MICROSECOND);

        // Cost path picks `cost` (USD), matching trade `amount` on inverse perps/futures.
        let bars =
            parse_bars(&chart_data, bar_type, 1, 0, true, ts_init).expect("Should parse bars");
        assert_eq!(bars.len(), 5);
        assert_eq!(bars[0].volume, Quantity::from("257490"));
        assert_eq!(bars[4].volume, Quantity::from("8910"));
    }

    #[rstest]
    fn test_parse_order_book() {
        let json_data = load_test_json("http_get_order_book.json");
        let response: DeribitJsonRpcResponse<DeribitOrderBook> =
            serde_json::from_str(&json_data).unwrap();
        let order_book_data = response.result.expect("Test data must have result");

        let instrument_id = InstrumentId::from("BTC-PERPETUAL.DERIBIT");
        let ts_init = UnixNanos::from(1766554855146274_u64 * NANOSECONDS_IN_MICROSECOND);

        let book = parse_order_book(&order_book_data, instrument_id, 1, 0, ts_init)
            .expect("Should parse order book");

        // Verify book metadata
        assert_eq!(book.instrument_id, instrument_id);
        assert_eq!(book.book_type, BookType::L2_MBP);
        assert_eq!(book.ts_last, ts_init);

        // Verify book has both sides
        assert!(book.has_bid(), "Book should have bids");
        assert!(book.has_ask(), "Book should have asks");

        // Verify best bid using OrderBook methods
        assert_eq!(
            book.best_bid_price(),
            Some(Price::from("87002.5")),
            "Best bid price should match"
        );
        assert_eq!(
            book.best_bid_size(),
            Some(Quantity::from("199190")),
            "Best bid size should match"
        );

        // Verify best ask using OrderBook methods
        assert_eq!(
            book.best_ask_price(),
            Some(Price::from("87003.0")),
            "Best ask price should match"
        );
        assert_eq!(
            book.best_ask_size(),
            Some(Quantity::from("125090")),
            "Best ask size should match"
        );

        // Verify spread (best_ask - best_bid = 87003.0 - 87002.5 = 0.5)
        let spread = book.spread().expect("Spread should exist");
        assert!(
            (spread - 0.5).abs() < 0.0001,
            "Spread should be 0.5, was {spread}"
        );

        // Verify midpoint ((87003.0 + 87002.5) / 2 = 87002.75)
        let midpoint = book.midpoint().expect("Midpoint should exist");
        assert!(
            (midpoint - 87002.75).abs() < 0.0001,
            "Midpoint should be 87002.75, was {midpoint}"
        );

        // Verify level counts match input data
        let bid_count = book.bids(None).count();
        let ask_count = book.asks(None).count();
        assert_eq!(
            bid_count,
            order_book_data.bids.len(),
            "Bid levels count should match input data"
        );
        assert_eq!(
            ask_count,
            order_book_data.asks.len(),
            "Ask levels count should match input data"
        );
        assert_eq!(bid_count, 20, "Should have 20 bid levels");
        assert_eq!(ask_count, 20, "Should have 20 ask levels");

        // Verify depth limiting works (get top 5 levels)
        assert_eq!(
            book.bids(Some(5)).count(),
            5,
            "Should limit to 5 bid levels"
        );
        assert_eq!(
            book.asks(Some(5)).count(),
            5,
            "Should limit to 5 ask levels"
        );

        // Verify bids_as_map and asks_as_map
        let bids_map = book.bids_as_map(None);
        let asks_map = book.asks_as_map(None);
        assert_eq!(bids_map.len(), 20, "Bids map should have 20 entries");
        assert_eq!(asks_map.len(), 20, "Asks map should have 20 entries");

        // Verify specific prices exist in maps
        assert!(
            bids_map.contains_key(&dec!(87002.5)),
            "Bids map should contain best bid price"
        );
        assert!(
            asks_map.contains_key(&dec!(87003.0)),
            "Asks map should contain best ask price"
        );

        // Verify worst levels exist
        assert!(
            bids_map.contains_key(&dec!(86980.0)),
            "Bids map should contain worst bid price"
        );
        assert!(
            asks_map.contains_key(&dec!(87031.5)),
            "Asks map should contain worst ask price"
        );
    }

    fn make_instrument_id(symbol: &str) -> InstrumentId {
        InstrumentId::new(Symbol::from(symbol), *DERIBIT_VENUE)
    }

    #[rstest]
    fn test_parse_futures_and_perpetuals() {
        // Perpetuals are classified as "future" in Deribit API
        let cases = [
            ("BTC-PERPETUAL", "future", "BTC"),
            ("ETH-PERPETUAL", "future", "ETH"),
            ("SOL-PERPETUAL", "future", "SOL"),
            // Futures with expiry dates
            ("BTC-25MAR23", "future", "BTC"),
            ("BTC-5AUG23", "future", "BTC"), // Single digit day
            ("ETH-28MAR25", "future", "ETH"),
        ];

        for (symbol, expected_kind, expected_currency) in cases {
            let (kind, currency) = parse_instrument_kind_currency(&make_instrument_id(symbol));
            assert_eq!(kind, expected_kind, "kind mismatch for {symbol}");
            assert_eq!(
                currency, expected_currency,
                "currency mismatch for {symbol}"
            );
        }
    }

    #[rstest]
    fn test_parse_options() {
        let cases = [
            // Standard options: {CURRENCY}-{DMMMYY}-{STRIKE}-{C|P}
            ("BTC-25MAR23-420-C", "option", "BTC"),
            ("BTC-5AUG23-580-P", "option", "BTC"),
            ("ETH-28MAR25-4000-C", "option", "ETH"),
            // Linear option with decimal strike (d = decimal point)
            ("XRP_USDC-30JUN23-0d625-C", "option", "XRP"),
        ];

        for (symbol, expected_kind, expected_currency) in cases {
            let (kind, currency) = parse_instrument_kind_currency(&make_instrument_id(symbol));
            assert_eq!(kind, expected_kind, "kind mismatch for {symbol}");
            assert_eq!(
                currency, expected_currency,
                "currency mismatch for {symbol}"
            );
        }
    }

    #[rstest]
    // Future combos: {CURRENCY}-FS-...
    #[case::future_combo_vs_perp("BTC-FS-19MAY26_PERP", "future_combo", "BTC")]
    #[case::future_combo_inter_month("BTC-FS-22MAY26_19MAY26", "future_combo", "BTC")]
    #[case::future_combo_eth("ETH-FS-26JUN26_PERP", "future_combo", "ETH")]
    // Option combos: {CURRENCY}-{STRATEGY}-...
    #[case::option_combo_call_spread("BTC-CS-19MAY26-70000_75000", "option_combo", "BTC")]
    #[case::option_combo_strangle("BTC-STRG-19MAY26-74000_79000", "option_combo", "BTC")]
    #[case::option_combo_straddle("BTC-STRD-29MAY26-77000", "option_combo", "BTC")]
    #[case::option_combo_box("BTC-BOX-25DEC26-58000_60000", "option_combo", "BTC")]
    #[case::option_combo_put_spread_eth("ETH-PS-26JUN26-3500_4000", "option_combo", "ETH")]
    fn test_parse_combo_kinds(
        #[case] symbol: &str,
        #[case] expected_kind: &str,
        #[case] expected_currency: &str,
    ) {
        let (kind, currency) = parse_instrument_kind_currency(&make_instrument_id(symbol));
        assert_eq!(kind, expected_kind, "kind mismatch for {symbol}");
        assert_eq!(
            currency, expected_currency,
            "currency mismatch for {symbol}"
        );
    }

    #[rstest]
    fn test_parse_option_combo_instrument() {
        let json_data = load_test_json("http_get_instruments_option_combo.json");
        let response: DeribitJsonRpcResponse<Vec<DeribitInstrument>> =
            serde_json::from_str(&json_data).unwrap();
        let instruments = response.result.expect("Test data must have result");
        let raw = instruments
            .iter()
            .find(|i| i.instrument_name.as_str() == "BTC-STRG-19MAY26-74000_79000")
            .expect("fixture must contain BTC-STRG-19MAY26-74000_79000");

        let any = parse_deribit_instrument_any(raw, UnixNanos::default(), UnixNanos::default())
            .unwrap()
            .expect("Should parse option combo");

        let InstrumentAny::CryptoOptionSpread(spread) = any else {
            panic!("Expected CryptoOptionSpread, was {any:?}");
        };
        assert_eq!(
            spread.id,
            InstrumentId::from("BTC-STRG-19MAY26-74000_79000.DERIBIT")
        );
        assert_eq!(spread.underlying.code.as_str(), "BTC");
        assert_eq!(spread.strategy_type.as_str(), "STRG");
        assert_eq!(spread.quote_currency.code.as_str(), "BTC");
        assert_eq!(spread.settlement_currency.code.as_str(), "BTC");
        assert!(spread.is_inverse);
        assert_eq!(spread.price_precision, 4);
        assert_eq!(spread.price_increment, Price::from("0.0001"));
        assert_eq!(spread.size_precision, 1);
        assert_eq!(spread.size_increment, Quantity::from("0.1"));
        assert_eq!(spread.multiplier, Quantity::from("1"));
        assert_eq!(spread.lot_size, Quantity::from("0.1"));
        assert_eq!(
            spread.expiration_ns,
            UnixNanos::from(1779177600000_u64 * 1_000_000)
        );
        assert_eq!(
            spread.activation_ns,
            UnixNanos::from(1779100724000_u64 * 1_000_000)
        );
        assert_eq!(spread.maker_fee, dec!(0));
        assert_eq!(spread.taker_fee, dec!(0));
    }

    #[rstest]
    fn test_deserialize_option_combo_trade_with_legs() {
        let json_data = load_test_json("http_get_last_trades_option_combo.json");
        let response: DeribitJsonRpcResponse<DeribitTradesResponse> =
            serde_json::from_str(&json_data).unwrap();
        let result = response.result.expect("Test data must have result");

        let combo_trade = &result.trades[0];
        assert_eq!(combo_trade.trade_id, "244365193");
        assert_eq!(combo_trade.instrument_name, "BTC-CS-19MAY26-70000_75000");
        assert_eq!(combo_trade.combo_id.as_deref(), None);
        assert_eq!(combo_trade.combo_trade_id.as_deref(), None);

        let legs = combo_trade
            .legs
            .as_ref()
            .expect("Combo trade must have legs");
        assert_eq!(legs.len(), 2);

        let leg_75c = &legs[0];
        assert_eq!(leg_75c.instrument_name, "BTC-19MAY26-75000-C");
        assert_eq!(leg_75c.trade_id, "244365195");
        assert_eq!(leg_75c.combo_trade_id, "244365193");
        assert_eq!(leg_75c.combo_id, "BTC-CS-19MAY26-70000_75000");
        assert_eq!(leg_75c.direction, "buy");
        assert_eq!(leg_75c.price, dec!(0.0174));
        assert_eq!(leg_75c.amount, dec!(0.1));
        assert_eq!(leg_75c.iv, Some(dec!(41.01)));

        let leg_70c = &legs[1];
        assert_eq!(leg_70c.instrument_name, "BTC-19MAY26-70000-C");
        assert_eq!(leg_70c.trade_id, "244365194");
        assert_eq!(leg_70c.direction, "sell");
        assert_eq!(leg_70c.iv, Some(dec!(83.39)));
    }

    #[rstest]
    fn test_deserialize_future_combo_trade_with_legs() {
        let json_data = load_test_json("http_get_last_trades_future_combo.json");
        let response: DeribitJsonRpcResponse<DeribitTradesResponse> =
            serde_json::from_str(&json_data).unwrap();
        let result = response.result.expect("Test data must have result");

        let combo_trade = &result.trades[0];
        assert_eq!(combo_trade.trade_id, "244343053");
        assert_eq!(combo_trade.instrument_name, "BTC-FS-25DEC26_PERP");
        assert_eq!(combo_trade.price, dec!(1320.0));
        assert_eq!(combo_trade.amount, dec!(10.0));

        let legs = combo_trade
            .legs
            .as_ref()
            .expect("Future combo trade must have legs");
        assert_eq!(legs.len(), 2);

        // Leg 1: BTC-25DEC26 sell. Exact field values rather than is_empty.
        let leg_25dec = &legs[0];
        assert_eq!(leg_25dec.instrument_name, "BTC-25DEC26");
        assert_eq!(leg_25dec.trade_id, "244343055");
        assert_eq!(leg_25dec.combo_id, "BTC-FS-25DEC26_PERP");
        assert_eq!(leg_25dec.combo_trade_id, "244343053");
        assert_eq!(leg_25dec.direction, "sell");
        assert_eq!(leg_25dec.price, dec!(78624.0));
        assert_eq!(leg_25dec.amount, dec!(10.0));
        assert_eq!(leg_25dec.contracts, Some(dec!(1.0)));
        assert!(leg_25dec.iv.is_none(), "future leg must not carry iv");

        // Leg 2: BTC-PERPETUAL buy.
        let leg_perp = &legs[1];
        assert_eq!(leg_perp.instrument_name, "BTC-PERPETUAL");
        assert_eq!(leg_perp.trade_id, "244343054");
        assert_eq!(leg_perp.combo_id, "BTC-FS-25DEC26_PERP");
        assert_eq!(leg_perp.combo_trade_id, "244343053");
        assert_eq!(leg_perp.direction, "buy");
        assert_eq!(leg_perp.price, dec!(77304.0));
        assert!(leg_perp.iv.is_none(), "future leg must not carry iv");
    }

    #[rstest]
    fn test_deserialize_historical_combo_leg_with_missing_optional_fields() {
        // Pins the review-fix loop's optionality decisions on DeribitTradeLeg.
        // Synthesised fixture: one combo trade where the parent omits
        // contracts/index_price/mark_price (already optional pre-patch), and
        // legs omit varying subsets of the same Option<Decimal> fields plus
        // `iv`. A regression that re-tightens any of them will fail here.
        let json_data = load_test_json("http_get_last_trades_historical_combo.json");
        let response: DeribitJsonRpcResponse<DeribitTradesResponse> =
            serde_json::from_str(&json_data).unwrap();
        let result = response.result.expect("Test data must have result");

        let combo_trade = &result.trades[0];
        assert_eq!(combo_trade.trade_id, "999000000");
        assert_eq!(combo_trade.instrument_name, "BTC-CS-19MAY26-70000_75000");
        // Parent-level optional fields all absent on this historical sample.
        assert!(combo_trade.contracts.is_none());
        assert!(combo_trade.index_price.is_none());
        assert!(combo_trade.mark_price.is_none());

        let legs = combo_trade
            .legs
            .as_ref()
            .expect("Combo trade must have legs");
        assert_eq!(legs.len(), 2);

        // Leg 1: every Option<Decimal> field absent (contracts, index_price,
        // mark_price, iv). Required fields still strong-asserted.
        let leg1 = &legs[0];
        assert_eq!(leg1.instrument_name, "BTC-19MAY26-75000-C");
        assert_eq!(leg1.trade_id, "999000001");
        assert_eq!(leg1.combo_id, "BTC-CS-19MAY26-70000_75000");
        assert_eq!(leg1.combo_trade_id, "999000000");
        assert_eq!(leg1.direction, "buy");
        assert_eq!(leg1.price, dec!(0.0174));
        assert_eq!(leg1.amount, dec!(0.1));
        assert!(leg1.contracts.is_none());
        assert!(leg1.index_price.is_none());
        assert!(leg1.mark_price.is_none());
        assert!(leg1.iv.is_none());

        // Leg 2: contracts and mark_price absent; iv and index_price present.
        // Confirms the optional fields are independently parsed.
        let leg2 = &legs[1];
        assert_eq!(leg2.instrument_name, "BTC-19MAY26-70000-C");
        assert_eq!(leg2.trade_id, "999000002");
        assert!(leg2.contracts.is_none());
        assert!(leg2.mark_price.is_none());
        assert_eq!(leg2.index_price, Some(dec!(76185.14)));
        assert_eq!(leg2.iv, Some(dec!(83.39)));
    }

    #[rstest]
    fn test_parse_combo_instrument_missing_expiration_errors() {
        // Locks invariant I9: build_spread_common must reject combo
        // instruments without an expiration_timestamp rather than producing a
        // zero-expiration InstrumentAny.
        let json_data = load_test_json("http_get_instruments_option_combo.json");
        let response: DeribitJsonRpcResponse<Vec<DeribitInstrument>> =
            serde_json::from_str(&json_data).unwrap();
        let mut instruments = response.result.expect("Test data must have result");
        let raw = instruments
            .iter_mut()
            .find(|i| i.instrument_name.as_str() == "BTC-STRG-19MAY26-74000_79000")
            .expect("fixture must contain BTC-STRG-19MAY26-74000_79000");
        raw.expiration_timestamp = None;

        let result = parse_deribit_instrument_any(raw, UnixNanos::default(), UnixNanos::default());
        let err = result.expect_err("Should error when expiration_timestamp is missing");
        let msg = format!("{err:#}");
        assert!(
            msg.contains("Missing expiration_timestamp for combo"),
            "unexpected error: {msg}"
        );
    }

    #[rstest]
    fn test_deserialize_perpetual_combo_leg_tags() {
        // Per-leg stream carries combo_id + combo_trade_id when the leg
        // originated from a combo (gating evidence from Step 1).
        let json_data = load_test_json("http_get_last_trades_perpetual_with_combo_tags.json");
        let response: DeribitJsonRpcResponse<DeribitTradesResponse> =
            serde_json::from_str(&json_data).unwrap();
        let result = response.result.expect("Test data must have result");

        for trade in &result.trades {
            assert_eq!(trade.instrument_name, "BTC-PERPETUAL");
            assert_eq!(trade.combo_id.as_deref(), Some("BTC-FS-25DEC26_PERP"));
            assert!(
                trade.combo_trade_id.is_some(),
                "Per-leg trade should carry combo_trade_id"
            );
            // Per-leg stream entries never carry a nested `legs` array.
            assert!(trade.legs.is_none());
        }
    }

    #[rstest]
    fn test_parse_future_combo_instrument() {
        let json_data = load_test_json("http_get_instruments_future_combo.json");
        let response: DeribitJsonRpcResponse<Vec<DeribitInstrument>> =
            serde_json::from_str(&json_data).unwrap();
        let instruments = response.result.expect("Test data must have result");
        let raw = instruments
            .iter()
            .find(|i| i.instrument_name.as_str() == "BTC-FS-19MAY26_PERP")
            .expect("fixture must contain BTC-FS-19MAY26_PERP");

        let any = parse_deribit_instrument_any(raw, UnixNanos::default(), UnixNanos::default())
            .unwrap()
            .expect("Should parse future combo");

        let InstrumentAny::CryptoFuturesSpread(spread) = any else {
            panic!("Expected CryptoFuturesSpread, was {any:?}");
        };
        assert_eq!(spread.id, InstrumentId::from("BTC-FS-19MAY26_PERP.DERIBIT"));
        assert_eq!(spread.underlying.code.as_str(), "BTC");
        assert_eq!(spread.strategy_type.as_str(), "FS");
        // Future combo quote_currency on BTC contracts is USD.
        assert_eq!(spread.quote_currency.code.as_str(), "USD");
        assert_eq!(spread.settlement_currency.code.as_str(), "BTC");
        assert!(spread.is_inverse);
        assert_eq!(spread.price_precision, 1);
        assert_eq!(spread.price_increment, Price::from("0.5"));
        assert_eq!(spread.size_precision, 0);
        assert_eq!(spread.size_increment, Quantity::from("10"));
        assert_eq!(spread.multiplier, Quantity::from("1"));
        assert_eq!(spread.lot_size, Quantity::from("10"));
        assert_eq!(
            spread.expiration_ns,
            UnixNanos::from(1779177600000_u64 * 1_000_000)
        );
    }

    #[rstest]
    fn test_build_public_trade_id_plain() {
        let id = build_public_trade_id("244343053", None, None, None);
        assert_eq!(id.as_str(), "244343053");
    }

    #[rstest]
    fn test_build_public_trade_id_combo_only() {
        let id = build_public_trade_id("244365195", None, None, Some("BTC-CS-19MAY26-70000_75000"));
        assert_eq!(id.as_str(), "COMBO-244365195");
    }

    #[rstest]
    fn test_build_public_trade_id_block_only() {
        let id = build_public_trade_id("244343053", None, Some("12345"), None);
        assert_eq!(id.as_str(), "BLK-244343053");
    }

    #[rstest]
    fn test_build_public_trade_id_rfq_only() {
        let id = build_public_trade_id("244343053", Some(99), None, None);
        assert_eq!(id.as_str(), "RFQ-244343053");
    }

    #[rstest]
    fn test_build_public_trade_id_precedence_block_beats_combo() {
        // A combo executed as a block carries both combo_id and block_trade_id.
        // The block tag wins because it is the more important reconciliation signal.
        let id = build_public_trade_id(
            "244343053",
            None,
            Some("12345"),
            Some("BTC-FS-25DEC26_PERP"),
        );
        assert_eq!(id.as_str(), "BLK-244343053");
    }

    #[rstest]
    fn test_build_public_trade_id_precedence_rfq_beats_all() {
        let id = build_public_trade_id(
            "244343053",
            Some(99),
            Some("12345"),
            Some("BTC-FS-25DEC26_PERP"),
        );
        assert_eq!(id.as_str(), "RFQ-244343053");
    }

    #[rstest]
    fn test_parse_spot() {
        let cases = [
            ("BTC_USDC", "spot", "BTC"),
            ("ETH_USDT", "spot", "ETH"),
            ("SOL_USDC", "spot", "SOL"),
        ];

        for (symbol, expected_kind, expected_currency) in cases {
            let (kind, currency) = parse_instrument_kind_currency(&make_instrument_id(symbol));
            assert_eq!(kind, expected_kind, "kind mismatch for {symbol}");
            assert_eq!(
                currency, expected_currency,
                "currency mismatch for {symbol}"
            );
        }
    }

    #[rstest]
    fn test_parse_portfolio_to_account_state() {
        let json_data = load_test_json("ws_portfolio.json");
        let notification: serde_json::Value = serde_json::from_str(&json_data).unwrap();

        // Extract the data field from the notification
        let data = notification
            .get("params")
            .and_then(|p| p.get("data"))
            .expect("Test data must have params.data");

        let portfolio: DeribitPortfolioMsg =
            serde_json::from_value(data.clone()).expect("Should deserialize portfolio message");

        // Verify deserialization
        assert_eq!(portfolio.currency, "USDT");
        assert_eq!(portfolio.equity, dec!(55.00055));
        assert_eq!(portfolio.balance, dec!(55.00055));
        assert_eq!(portfolio.available_funds, dec!(53.868247));
        assert_eq!(portfolio.margin_balance, dec!(54.968258));
        assert_eq!(portfolio.initial_margin, dec!(1.100011));
        assert_eq!(portfolio.maintenance_margin, dec!(0.0));
        assert_eq!(portfolio.cross_collateral_enabled, Some(true));
        assert_eq!(portfolio.margin_model.as_deref(), Some("cross_sm"));

        // Test parsing to AccountState
        let account_id = AccountId::new("DERIBIT-master");
        let ts_init = UnixNanos::from(1700000000000000000_u64);

        let account_state =
            parse_portfolio_to_account_state(&portfolio, account_id, ts_init).unwrap();

        // Verify account state
        assert_eq!(account_state.account_id, account_id);
        assert_eq!(account_state.account_type, AccountType::Margin);
        assert!(account_state.is_reported);

        // Verify balances (should have 1 balance for USDT)
        // cross_collateral_enabled=true so total=equity, free=available_withdrawal_funds
        assert_eq!(account_state.balances.len(), 1);
        let balance = &account_state.balances[0];
        assert_eq!(balance.currency.code, "USDT");
        assert_eq!(balance.total.as_f64(), 55.00055); // equity (not margin_balance)
        assert_eq!(balance.free.as_f64(), 54.968257); // available_withdrawal_funds (not available_funds)

        // locked = total - free = 55.00055 - 54.968257 = 0.032293
        let locked = balance.locked.as_f64();
        assert!(
            (locked - 0.032293).abs() < 0.001,
            "Locked ({locked}) should be close to 0.032293"
        );

        // Verify margins (should have 1 margin since initial_margin > 0)
        assert_eq!(account_state.margins.len(), 1);
        let margin = &account_state.margins[0];
        assert_eq!(margin.initial.as_f64(), 1.100011);
        assert_eq!(margin.maintenance.as_f64(), 0.0);
        assert!(margin.instrument_id.is_none());
        assert_eq!(margin.currency.code.as_str(), "USDT");
    }

    #[rstest]
    #[case::minute_1(1, "MINUTE", "1")]
    #[case::minute_2(2, "MINUTE", "3")]
    #[case::minute_3(3, "MINUTE", "3")]
    #[case::minute_4(4, "MINUTE", "5")]
    #[case::minute_5(5, "MINUTE", "5")]
    #[case::minute_6(6, "MINUTE", "10")]
    #[case::minute_10(10, "MINUTE", "10")]
    #[case::minute_12(12, "MINUTE", "15")]
    #[case::minute_15(15, "MINUTE", "15")]
    #[case::minute_20(20, "MINUTE", "30")]
    #[case::minute_30(30, "MINUTE", "30")]
    #[case::hour_1(1, "HOUR", "60")]
    #[case::hour_2(2, "HOUR", "120")]
    #[case::hour_3(3, "HOUR", "180")]
    #[case::hour_4(4, "HOUR", "360")]
    #[case::hour_6(6, "HOUR", "360")]
    #[case::hour_12(12, "HOUR", "720")]
    #[case::day_1(1, "DAY", "1D")]
    fn test_bar_spec_to_resolution(
        #[case] step: u64,
        #[case] aggregation: &str,
        #[case] expected: &str,
    ) {
        let bar_type_str = format!("BTC-PERPETUAL.DERIBIT-{step}-{aggregation}-LAST-EXTERNAL");
        let bar_type = BarType::from(bar_type_str.as_str());
        let resolution = bar_spec_to_resolution(&bar_type);
        assert_eq!(resolution, expected);
    }
}