nautilus_derive/http/

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

//! HTTP payload models and JSON-RPC envelope types for the Derive REST API.
//!
//! Envelope types (`JsonRpcRequest`, `JsonRpcResponse`, `JsonRpcError`) cover
//! the wire framing shared with the WebSocket transport. Payload structs below
//! mirror the response shapes generated by Derive's upstream Rust SDK at
//! [`derivexyz/cockpit`](https://github.com/derivexyz/cockpit/tree/master/orderbook-types/src/generated),
//! adapted to project conventions:
//!
//! - `bigdecimal::BigDecimal` -> [`rust_decimal::Decimal`]. Required account and order
//!   financial fields, private fill amount/price/fee, and public trade amount/price
//!   use strict raw-token decimal decoding;
//!   other fields retain `deserialize_decimal` / `deserialize_optional_decimal`.
//! - Hot-path string identifiers (`instrument_name`, `currency`) -> [`Ustr`]
//!   for interning across decoded messages.
//! - `uuid::Uuid` fields kept as [`String`] to avoid a fresh dep when only a
//!   couple of methods carry one.

use std::collections::HashMap;

#[cfg(test)]
use nautilus_core::string::secret::REDACTED;
use nautilus_core::{
    Params,
    serialization::{
        deserialize_decimal_token,
        deserialize_optional_decimal_token as deserialize_optional_decimal,
        serialize_decimal_as_str,
    },
    string::secret::SecretString,
};
use rust_decimal::Decimal;
use serde::{Deserialize, Serialize};
use serde_json::{Value, value::RawValue};
use ustr::Ustr;

use crate::common::{
    enums::{
        DeriveAssetType, DeriveInstrumentType, DeriveLiquidityRole, DeriveOptionKind,
        DeriveOrderCancelReason, DeriveOrderSide, DeriveOrderStatus, DeriveOrderType,
        DeriveTimeInForce, DeriveTriggerPriceType, DeriveTriggerType,
    },
    parse::{deserialize_decimal, deserialize_salvaged_vec, salvage_rows},
};

/// Outbound JSON-RPC request frame. Used as-is by the WebSocket transport; the
/// REST transport addresses the method by URL path and sends only `params` on
/// the wire, but keeps the same `id` for telemetry.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct JsonRpcRequest<P> {
    /// JSON-RPC version tag; constant `"2.0"`.
    pub jsonrpc: &'static str,
    /// Correlator chosen by the client.
    pub id: u64,
    /// Method name (e.g. `public/get_all_instruments`).
    pub method: &'static str,
    /// Method-specific params payload.
    pub params: P,
}

impl<P> JsonRpcRequest<P> {
    /// Constructs a `2.0` request with the given correlator, method, and params.
    #[must_use]
    pub fn new(id: u64, method: &'static str, params: P) -> Self {
        Self {
            jsonrpc: "2.0",
            id,
            method,
            params,
        }
    }
}

/// Inbound JSON-RPC response frame. Exactly one of `result` or `error` is set
/// by the venue.
#[derive(Debug, Clone, Deserialize)]
#[serde(bound(deserialize = "R: Deserialize<'de>"))]
pub struct JsonRpcResponse<R> {
    /// Correlator echoing the request `id`. The Derive REST API may omit this
    /// for some endpoints, hence `Option`.
    #[serde(default, deserialize_with = "deserialize_optional_jsonrpc_id")]
    pub id: Option<u64>,
    /// Result payload on success.
    #[serde(default, deserialize_with = "deserialize_present_jsonrpc_result")]
    pub result: Option<R>,
    /// Error payload on failure.
    #[serde(default)]
    pub error: Option<JsonRpcError>,
}

fn deserialize_present_jsonrpc_result<'de, D, R>(deserializer: D) -> Result<Option<R>, D::Error>
where
    D: serde::Deserializer<'de>,
    R: Deserialize<'de>,
{
    R::deserialize(deserializer).map(Some)
}

fn deserialize_optional_jsonrpc_id<'de, D>(deserializer: D) -> Result<Option<u64>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    let value = Option::<Value>::deserialize(deserializer)?;
    match value {
        None | Some(Value::Null) => Ok(None),
        Some(Value::Number(number)) => number
            .as_u64()
            .map(Some)
            .ok_or_else(|| serde::de::Error::custom("JSON-RPC id must be an unsigned integer")),
        Some(Value::String(value)) => Ok(value.parse::<u64>().ok()),
        Some(other) => Err(serde::de::Error::custom(format!(
            "JSON-RPC id must be an unsigned integer or string, was {other}"
        ))),
    }
}

/// JSON-RPC error object as returned by Derive on failed requests.
#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)]
pub struct JsonRpcError {
    /// Numeric error code defined by the venue.
    pub code: i64,
    /// Human-readable error message.
    pub message: String,
    /// Optional structured diagnostic payload.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub data: Option<Value>,
}

/// Option-specific fields appearing on `public/get_all_instruments` and legacy
/// full ticker payloads when the instrument is an option.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct DeriveOptionPublicDetails {
    /// Option expiry as a UNIX timestamp in seconds.
    pub expiry: i64,
    /// Underlying index identifier (e.g. `"ETH-USD"`).
    pub index: Ustr,
    /// Call or put.
    pub option_type: DeriveOptionKind,
    /// Final settlement price, populated after expiry.
    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
    pub settlement_price: Option<Decimal>,
    /// Strike price in quote currency.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub strike: Decimal,
}

/// Perp-specific fields appearing on `public/get_all_instruments` and legacy full
/// ticker payloads when the instrument is a perpetual.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct DerivePerpPublicDetails {
    /// Cumulative funding accrued since contract inception.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub aggregate_funding: Decimal,
    /// Current funding rate per funding interval.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub funding_rate: Decimal,
    /// Underlying index identifier (e.g. `"ETH-USD"`).
    pub index: Ustr,
    /// Maximum allowable funding rate per hour.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub max_rate_per_hour: Decimal,
    /// Minimum allowable funding rate per hour.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub min_rate_per_hour: Decimal,
    /// Legacy static interest-rate component, absent from API v3 definitions.
    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
    pub static_interest_rate: Option<Decimal>,
}

/// Instrument definition returned by `public/get_all_instruments`.
#[derive(Clone, Debug, Serialize, Deserialize)]
#[serde(remote = "Self")]
pub struct DeriveInstrument {
    /// Minimum increment of the `amount` field for orders.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub amount_step: Decimal,
    /// On-chain address of the base asset.
    pub base_asset_address: Ustr,
    /// Sub-id of the base asset within the asset module (decimal string).
    pub base_asset_sub_id: Ustr,
    /// Underlying currency (e.g. `"ETH"`).
    pub base_currency: Ustr,
    /// Base flat fee in USD.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub base_fee: Decimal,
    /// Canonical instrument name (e.g. `"ETH-PERP"`, `"ETH-20250627-3500-C"`).
    pub instrument_name: Ustr,
    /// Instrument category.
    pub instrument_type: DeriveInstrumentType,
    /// Whether the instrument is currently tradable.
    pub is_active: bool,
    /// Maker fee rate (fraction).
    #[serde(deserialize_with = "deserialize_decimal")]
    pub maker_fee_rate: Decimal,
    /// Optional cap on the mark-price-derived fee rate.
    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
    pub mark_price_fee_rate_cap: Option<Decimal>,
    /// Maximum allowed order amount.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub maximum_amount: Decimal,
    /// Venue-reported minimum contracts or tokens per trade.
    /// Taker orders can fill below this value.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub minimum_amount: Decimal,
    /// Option-specific details (populated when `instrument_type == option`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub option_details: Option<DeriveOptionPublicDetails>,
    /// Perp-specific details (populated when `instrument_type == perp`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub perp_details: Option<DerivePerpPublicDetails>,
    /// Quote currency (e.g. `"USDC"`).
    pub quote_currency: Ustr,
    /// Scheduled activation timestamp (UNIX seconds).
    pub scheduled_activation: i64,
    /// Scheduled deactivation timestamp (UNIX seconds; `i64::MAX` if none).
    pub scheduled_deactivation: i64,
    /// Taker fee rate (fraction).
    #[serde(deserialize_with = "deserialize_decimal")]
    pub taker_fee_rate: Decimal,
    /// Minimum price increment.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub tick_size: Decimal,
    /// Original instrument response fields, before typed decoding or normalization.
    #[serde(skip)]
    pub raw: Option<Params>,
}

impl<'de> Deserialize<'de> for DeriveInstrument {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let raw = Box::<RawValue>::deserialize(deserializer)?;
        let mut typed = serde_json::Deserializer::from_str(raw.get());

        // The remote derive decodes the typed fields without calling this implementation
        let mut instrument = Self::deserialize(&mut typed).map_err(serde::de::Error::custom)?;
        instrument.raw = Some(serde_json::from_str(raw.get()).map_err(serde::de::Error::custom)?);
        Ok(instrument)
    }
}

impl Serialize for DeriveInstrument {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        Self::serialize(self, serializer)
    }
}

/// 24-hour rolling trading statistics embedded in ticker payloads.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct DeriveAggregateTradingStats {
    /// Total contract volume over the last 24 hours.
    #[serde(alias = "c", deserialize_with = "deserialize_decimal")]
    pub contract_volume: Decimal,
    /// Highest trade price in the last 24 hours.
    #[serde(alias = "h", deserialize_with = "deserialize_decimal")]
    pub high: Decimal,
    /// Lowest trade price in the last 24 hours.
    #[serde(alias = "l", deserialize_with = "deserialize_decimal")]
    pub low: Decimal,
    /// Number of trades over the last 24 hours.
    #[serde(alias = "n", deserialize_with = "deserialize_decimal")]
    pub num_trades: Decimal,
    /// Current total open interest.
    #[serde(alias = "oi", deserialize_with = "deserialize_decimal")]
    pub open_interest: Decimal,
    /// 24-hour percentage price change.
    #[serde(alias = "p", deserialize_with = "deserialize_decimal")]
    pub percent_change: Decimal,
    /// 24-hour premium volume in USD (legacy field name).
    #[serde(alias = "pr", deserialize_with = "deserialize_decimal")]
    pub usd_change: Decimal,
}

/// Option pricing greeks and implied volatilities (option tickers only).
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct DeriveOptionPricing {
    /// Implied volatility of the current best ask.
    #[serde(alias = "ai", deserialize_with = "deserialize_decimal")]
    pub ask_iv: Decimal,
    /// Implied volatility of the current best bid.
    #[serde(alias = "bi", deserialize_with = "deserialize_decimal")]
    pub bid_iv: Decimal,
    /// Option delta.
    #[serde(alias = "d", deserialize_with = "deserialize_decimal")]
    pub delta: Decimal,
    /// Forward price used in pricing.
    #[serde(alias = "f", deserialize_with = "deserialize_decimal")]
    pub forward_price: Decimal,
    /// Option gamma.
    #[serde(alias = "g", deserialize_with = "deserialize_decimal")]
    pub gamma: Decimal,
    /// Implied volatility of the option.
    #[serde(alias = "i", deserialize_with = "deserialize_decimal")]
    pub iv: Decimal,
    /// Mark price of the option.
    #[serde(alias = "m", deserialize_with = "deserialize_decimal")]
    pub mark_price: Decimal,
    /// Option rho.
    #[serde(alias = "r", deserialize_with = "deserialize_decimal")]
    pub rho: Decimal,
    /// Option theta.
    #[serde(alias = "t", deserialize_with = "deserialize_decimal")]
    pub theta: Decimal,
    /// Option vega.
    #[serde(alias = "v", deserialize_with = "deserialize_decimal")]
    pub vega: Decimal,
}

/// Current ticker snapshot returned by `public/get_tickers` and `ticker_slim`.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct DeriveTickerSnapshot {
    /// Instrument identifier, injected from the `tickers` map key.
    #[serde(default)]
    pub instrument_name: Ustr,
    /// Best ask amount.
    #[serde(
        rename = "A",
        alias = "best_ask_amount",
        deserialize_with = "deserialize_decimal"
    )]
    pub best_ask_amount: Decimal,
    /// Best ask price.
    #[serde(
        rename = "a",
        alias = "best_ask_price",
        deserialize_with = "deserialize_decimal"
    )]
    pub best_ask_price: Decimal,
    /// Best bid amount.
    #[serde(
        rename = "B",
        alias = "best_bid_amount",
        deserialize_with = "deserialize_decimal"
    )]
    pub best_bid_amount: Decimal,
    /// Best bid price.
    #[serde(
        rename = "b",
        alias = "best_bid_price",
        deserialize_with = "deserialize_decimal"
    )]
    pub best_bid_price: Decimal,
    /// Current hourly funding rate for perpetuals.
    #[serde(
        rename = "f",
        alias = "funding_rate",
        default,
        deserialize_with = "deserialize_optional_decimal"
    )]
    pub funding_rate: Option<Decimal>,
    /// Current oracle index price for the underlying.
    #[serde(
        rename = "I",
        alias = "index_price",
        deserialize_with = "deserialize_decimal"
    )]
    pub index_price: Decimal,
    /// Current mark price.
    #[serde(
        rename = "M",
        alias = "mark_price",
        deserialize_with = "deserialize_decimal"
    )]
    pub mark_price: Decimal,
    /// Maximum allowed price.
    #[serde(
        rename = "maxp",
        alias = "max_price",
        deserialize_with = "deserialize_decimal"
    )]
    pub max_price: Decimal,
    /// Minimum allowed price.
    #[serde(
        rename = "minp",
        alias = "min_price",
        deserialize_with = "deserialize_decimal"
    )]
    pub min_price: Decimal,
    /// Option pricing greeks (options only).
    #[serde(default)]
    pub option_pricing: Option<DeriveOptionPricing>,
    /// 24-hour rolling statistics.
    #[serde(default)]
    pub stats: Option<DeriveAggregateTradingStats>,
    /// Ticker timestamp (UNIX ms).
    #[serde(rename = "t", alias = "timestamp")]
    pub timestamp: i64,
}

/// Result returned by `public/get_tickers`.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct DeriveTickersResult {
    /// Ticker snapshots keyed by instrument name.
    pub tickers: HashMap<String, DeriveTickerSnapshot>,
}

/// Legacy full ticker snapshot pushed on the deprecated WS
/// `ticker.{instrument_name}.{interval}` channel.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct DeriveTicker {
    /// Minimum order amount increment.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub amount_step: Decimal,
    /// On-chain address of the base asset.
    pub base_asset_address: Ustr,
    /// Sub-id of the base asset within the asset module (decimal string).
    pub base_asset_sub_id: Ustr,
    /// Underlying currency.
    pub base_currency: Ustr,
    /// Base flat fee in USD.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub base_fee: Decimal,
    /// Best ask amount.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub best_ask_amount: Decimal,
    /// Best ask price.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub best_ask_price: Decimal,
    /// Best bid amount.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub best_bid_amount: Decimal,
    /// Best bid price.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub best_bid_price: Decimal,
    /// Current oracle index price for the underlying.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub index_price: Decimal,
    /// Instrument identifier.
    pub instrument_name: Ustr,
    /// Instrument category.
    pub instrument_type: DeriveInstrumentType,
    /// Whether the instrument is currently tradable.
    pub is_active: bool,
    /// Maker fee rate.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub maker_fee_rate: Decimal,
    /// Current mark price.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub mark_price: Decimal,
    /// Optional fee-rate cap derived from mark price.
    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
    pub mark_price_fee_rate_cap: Option<Decimal>,
    /// Maximum allowed price.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub max_price: Decimal,
    /// Maximum order amount.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub maximum_amount: Decimal,
    /// Minimum allowed price.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub min_price: Decimal,
    /// Minimum order amount.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub minimum_amount: Decimal,
    /// Option-specific reference data.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub option_details: Option<DeriveOptionPublicDetails>,
    /// Option pricing greeks (options only).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub option_pricing: Option<DeriveOptionPricing>,
    /// Perp-specific reference data.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub perp_details: Option<DerivePerpPublicDetails>,
    /// Quote currency.
    pub quote_currency: Ustr,
    /// Scheduled activation timestamp (UNIX seconds).
    pub scheduled_activation: i64,
    /// Scheduled deactivation timestamp (UNIX seconds; `i64::MAX` if none).
    pub scheduled_deactivation: i64,
    /// 24-hour rolling statistics. Populated by the WebSocket ticker channel.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub stats: Option<DeriveAggregateTradingStats>,
    /// Taker fee rate.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub taker_fee_rate: Decimal,
    /// Minimum price increment.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub tick_size: Decimal,
    /// Ticker timestamp (UNIX ms).
    pub timestamp: i64,
}

/// Order record returned by `private/order`, `private/get_open_orders`,
/// `private/get_order_history`, and the `{subaccount_id}.orders` WS channel.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DeriveOrder {
    /// Order amount in base units.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub amount: Decimal,
    /// Average fill price.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub average_price: Decimal,
    /// Cancel reason; [`DeriveOrderCancelReason::Empty`] when not cancelled.
    #[serde(default = "cancel_reason_empty")]
    pub cancel_reason: DeriveOrderCancelReason,
    /// Creation timestamp (UNIX ms).
    pub creation_timestamp: i64,
    /// Order side.
    pub direction: DeriveOrderSide,
    /// Cumulative filled amount.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub filled_amount: Decimal,
    /// Instrument identifier.
    pub instrument_name: Ustr,
    /// Whether this order was generated via `private/transfer_position`.
    pub is_transfer: bool,
    /// Free-form user label.
    #[serde(default)]
    pub label: Ustr,
    /// Last update timestamp (UNIX ms).
    pub last_update_timestamp: i64,
    /// Limit price in quote currency.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub limit_price: Decimal,
    /// Max fee in quote currency signed into the order.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub max_fee: Decimal,
    /// Whether MMP tags this order.
    pub mmp: bool,
    /// Order UNIX nanosecond nonce, encoded as a decimal string.
    #[serde(
        serialize_with = "crate::signing::nonce::serialize_nonce",
        deserialize_with = "crate::signing::nonce::deserialize_nonce"
    )]
    pub nonce: u64,
    /// Total fees paid against this order.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub order_fee: Decimal,
    /// Venue-assigned order ID (UUID-shaped).
    pub order_id: String,
    /// Order status.
    pub order_status: DeriveOrderStatus,
    /// Order type.
    pub order_type: DeriveOrderType,
    /// RFQ quote ID when the order is an RFQ execution.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub quote_id: Option<String>,
    /// Replaced order ID when this order resulted from a replace.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub replaced_order_id: Option<String>,
    /// 65-byte order signature, `0x`-prefixed hex.
    pub signature: SecretString,
    /// Signature expiry (UNIX seconds).
    pub signature_expiry_sec: i64,
    /// Session-key signer address.
    pub signer: Ustr,
    /// Owning subaccount.
    pub subaccount_id: i64,
    /// Time-in-force.
    pub time_in_force: DeriveTimeInForce,
    /// Trigger price for trigger orders.
    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
    pub trigger_price: Option<Decimal>,
    /// Trigger price source for trigger orders.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub trigger_price_type: Option<DeriveTriggerPriceType>,
    /// Trigger rejection text when the trigger worker cannot submit.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub trigger_reject_message: Option<String>,
    /// Stop-loss or take-profit trigger flag.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub trigger_type: Option<DeriveTriggerType>,
}

/// Result envelope returned by `private/order`.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct DeriveOrderResult {
    /// Accepted order.
    pub order: DeriveOrder,
    /// Trades generated synchronously by the submission, when any.
    #[serde(default, deserialize_with = "deserialize_salvaged_vec")]
    pub trades: Vec<DeriveTrade>,
}

/// Result envelope returned by `private/replace`.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct DeriveReplaceResult {
    /// Newly accepted replacement order, absent when cancellation succeeded but creation failed.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub order: Option<DeriveOrder>,
    /// Cancelled stale order, omitted by some responses and mocks.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cancelled_order: Option<DeriveOrder>,
    /// Replacement creation error after the stale order was cancelled.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub create_order_error: Option<JsonRpcError>,
}

/// Confirmed outcome returned by `private/replace`.
#[derive(Clone, Debug)]
pub enum DeriveReplaceOutcome {
    /// The stale order was cancelled and the replacement was accepted.
    Replaced(DeriveOrder),
    /// The stale order was cancelled but replacement creation failed.
    Canceled {
        /// Cancelled stale order returned by the venue.
        cancelled_order: DeriveOrder,
        /// Structured error returned by replacement creation.
        create_order_error: JsonRpcError,
    },
}

impl DeriveReplaceResult {
    /// Validates the response shape and cancellation identity.
    ///
    /// # Errors
    ///
    /// Returns an error if fields contradict each other, a cancellation record is unexpected, or
    /// the replacement state is invalid.
    pub(crate) fn into_outcome(
        self,
        expected_cancel_order_id: &str,
        expected_replacement_label: &str,
        expected_subaccount_id: u64,
        expected_instrument: &str,
    ) -> Result<DeriveReplaceOutcome, String> {
        let validate_cancelled_order = |order: &DeriveOrder| {
            if order.order_id != expected_cancel_order_id {
                return Err(format!(
                    "private/replace cancelled order {} did not match requested order {expected_cancel_order_id}",
                    order.order_id,
                ));
            }

            if order.order_status != DeriveOrderStatus::Cancelled {
                return Err(format!(
                    "private/replace cancellation record for {expected_cancel_order_id} had status {}",
                    order.order_status,
                ));
            }

            validate_replace_order_scope(
                order,
                expected_replacement_label,
                expected_subaccount_id,
                expected_instrument,
            )
        };

        match (self.order, self.cancelled_order, self.create_order_error) {
            (Some(order), cancelled_order, None) => {
                if order.order_id == expected_cancel_order_id {
                    return Err(format!(
                        "private/replace returned the cancelled order {expected_cancel_order_id} as its replacement",
                    ));
                }

                if !matches!(
                    order.order_status,
                    DeriveOrderStatus::Open | DeriveOrderStatus::Filled
                ) {
                    return Err(format!(
                        "private/replace replacement {} had status {}",
                        order.order_id, order.order_status,
                    ));
                }

                validate_replace_order_scope(
                    &order,
                    expected_replacement_label,
                    expected_subaccount_id,
                    expected_instrument,
                )?;

                if let Some(cancelled_order) = cancelled_order.as_ref() {
                    validate_cancelled_order(cancelled_order)?;
                }

                Ok(DeriveReplaceOutcome::Replaced(order))
            }
            (None, Some(cancelled_order), Some(create_order_error)) => {
                validate_cancelled_order(&cancelled_order)?;
                Ok(DeriveReplaceOutcome::Canceled {
                    cancelled_order,
                    create_order_error,
                })
            }
            _ => Err("private/replace returned an inconsistent result".to_string()),
        }
    }
}

fn validate_replace_order_scope(
    order: &DeriveOrder,
    expected_replacement_label: &str,
    expected_subaccount_id: u64,
    expected_instrument: &str,
) -> Result<(), String> {
    if u64::try_from(order.subaccount_id).ok() != Some(expected_subaccount_id)
        || order.instrument_name != expected_instrument
    {
        return Err(format!(
            "private/replace order {} did not match requested account and instrument",
            order.order_id
        ));
    }

    if order.label != expected_replacement_label {
        return Err(format!(
            "private/replace order {} had label {}, expected {expected_replacement_label}",
            order.order_id, order.label
        ));
    }

    Ok(())
}

/// Result returned by `private/cancel_by_label`.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct DeriveCancelByLabelResult {
    /// Confirmed count, or -1 for an unscoped acknowledgement requiring state confirmation.
    pub cancelled_orders: i64,
}

/// Result returned by `private/cancel_by_instrument`.
pub type DeriveCancelByInstrumentResult = DeriveCancelByLabelResult;

/// Empty result returned by state-changing endpoints without a typed payload.
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize)]
pub struct DeriveEmptyResult {}

impl<'de> Deserialize<'de> for DeriveEmptyResult {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        match Value::deserialize(deserializer)? {
            Value::Null | Value::Object(_) => Ok(Self {}),
            Value::String(value) if value == "ok" => Ok(Self {}),
            other => Err(serde::de::Error::custom(format!(
                "empty Derive result must be an object, null, or \"ok\", was {other}"
            ))),
        }
    }
}

/// Position record returned by `private/get_positions` and embedded in
/// `private/get_subaccount` responses.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct DerivePosition {
    /// Signed position amount; positive = long, negative = short.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub amount: Decimal,
    /// Average entry price over the lifetime of the position; includes opening fees for perpetuals.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub average_price: Decimal,
    /// Position opening timestamp (UNIX ms).
    pub creation_timestamp: i64,
    /// Cumulative funding accrued by this position (perps only).
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub cumulative_funding: Decimal,
    /// Position delta (with respect to forward for options).
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub delta: Decimal,
    /// Position gamma (zero for non-options).
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub gamma: Decimal,
    /// Current oracle index price for the underlying.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub index_price: Decimal,
    /// Signed USD initial-health contribution, including mark-to-market value.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub initial_margin: Decimal,
    /// Instrument identifier (same as the base asset name).
    pub instrument_name: Ustr,
    /// Instrument category.
    pub instrument_type: DeriveInstrumentType,
    /// Effective leverage (perps only).
    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
    pub leverage: Option<Decimal>,
    /// Index price at which the position would liquidate.
    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
    pub liquidation_price: Option<Decimal>,
    /// Signed USD maintenance-health contribution, including mark-to-market value.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub maintenance_margin: Decimal,
    /// Current mark price.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub mark_price: Decimal,
    /// USD mark-to-market value of the position.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub mark_value: Decimal,
    /// Net USD settled from this position.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub net_settlements: Decimal,
    /// USD open-order margin contribution for this asset.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub open_orders_margin: Decimal,
    /// Funding not yet settled into cash balance (perps only).
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub pending_funding: Decimal,
    /// Realized PnL booked on this position.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub realized_pnl: Decimal,
    /// Position theta (zero for non-options).
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub theta: Decimal,
    /// Unrealized PnL.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub unrealized_pnl: Decimal,
    /// Position vega (zero for non-options).
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub vega: Decimal,
}

/// Collateral row inside a `private/get_subaccount` response.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct DeriveCollateral {
    /// Collateral amount.
    #[serde(
        deserialize_with = "deserialize_decimal_token",
        serialize_with = "serialize_decimal_as_str"
    )]
    pub amount: Decimal,
    /// Asset name (e.g. `"ETH"`, `"USDC"`).
    pub asset_name: Ustr,
    /// Asset category.
    pub asset_type: DeriveAssetType,
    /// Cumulative interest earned or paid.
    #[serde(
        deserialize_with = "deserialize_decimal_token",
        serialize_with = "serialize_decimal_as_str"
    )]
    pub cumulative_interest: Decimal,
    /// Underlying currency.
    pub currency: Ustr,
    /// USD initial margin credit from this collateral.
    #[serde(
        deserialize_with = "deserialize_decimal_token",
        serialize_with = "serialize_decimal_as_str"
    )]
    pub initial_margin: Decimal,
    /// USD maintenance margin credit.
    #[serde(
        deserialize_with = "deserialize_decimal_token",
        serialize_with = "serialize_decimal_as_str"
    )]
    pub maintenance_margin: Decimal,
    /// Current mark price of the asset.
    #[serde(
        deserialize_with = "deserialize_decimal_token",
        serialize_with = "serialize_decimal_as_str"
    )]
    pub mark_price: Decimal,
    /// USD value (`amount * mark_price`).
    #[serde(
        deserialize_with = "deserialize_decimal_token",
        serialize_with = "serialize_decimal_as_str"
    )]
    pub mark_value: Decimal,
    /// Interest not yet settled on-chain.
    #[serde(
        deserialize_with = "deserialize_decimal_token",
        serialize_with = "serialize_decimal_as_str"
    )]
    pub pending_interest: Decimal,
}

/// Subaccount snapshot returned by `private/get_subaccount`.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct DeriveSubaccount {
    /// Collateral rows contributing to margin.
    pub collaterals: Vec<DeriveCollateral>,
    /// Total initial margin credit from collaterals.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub collaterals_initial_margin: Decimal,
    /// Total maintenance margin credit from collaterals.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub collaterals_maintenance_margin: Decimal,
    /// Mark-to-market value of all collaterals.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub collaterals_value: Decimal,
    /// Currencies covered by the subaccount manager.
    pub currency: Vec<Ustr>,
    /// Whether the venue failed to load the portfolio.
    pub failed_to_fetch: bool,
    /// Signed net initial margin health, excluding open-order reservations.
    /// Negative health blocks risk-increasing trades.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub initial_margin: Decimal,
    /// Whether the subaccount is mid-liquidation.
    pub is_under_liquidation: bool,
    /// Free-form subaccount label.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub label: Option<String>,
    /// Signed net maintenance margin health; negative permits liquidation.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub maintenance_margin: Decimal,
    /// Venue manager identity.
    pub manager_id: u32,
    /// Open-ended venue margin model (for example `"SM"` or `"PM2"`).
    pub margin_type: String,
    /// Maintenance-margin credit from risk-universe loss socialization.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub mm_credits: Decimal,
    /// Open orders held by the subaccount.
    pub open_orders: Vec<DeriveOrder>,
    /// Signed USD open-order reservation, excluded from `initial_margin`.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub open_orders_margin: Decimal,
    /// Open positions held by the subaccount.
    pub positions: Vec<DerivePosition>,
    /// Signed USD initial-health contribution from positions, including mark-to-market value.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub positions_initial_margin: Decimal,
    /// Signed USD maintenance-health contribution from positions, including mark-to-market value.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub positions_maintenance_margin: Decimal,
    /// Mark-to-market value of positions.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub positions_value: Decimal,
    /// Maintenance-margin change after the next option expiry.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub projected_margin_change: Decimal,
    /// Risk universe containing the manager.
    pub risk_universe_id: u32,
    /// Subaccount identifier.
    pub subaccount_id: i64,
    /// Total subaccount value (collateral + positions).
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub subaccount_value: Decimal,
    /// Pending vault-deposit reservations on the source subaccount.
    pub vault_deposit_holds: Vec<DeriveVaultDepositHold>,
}

/// Pending vault-deposit reservation returned with a subaccount.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DeriveVaultDepositHold {
    /// Reserved amount in native asset units.
    #[serde(
        deserialize_with = "deserialize_decimal_token",
        serialize_with = "serialize_decimal_as_str"
    )]
    pub amount: Decimal,
    /// Reserved asset.
    pub asset_name: Ustr,
    /// Asset currency.
    pub currency: Ustr,
    /// Target vault identifier.
    pub vault_id: u64,
}

/// Private trade record returned by `private/get_trade_history` and the
/// `{subaccount_id}.trades` WS channel.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct DeriveTrade {
    /// Trade side.
    pub direction: DeriveOrderSide,
    /// Underlying index price at the time of the trade.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub index_price: Decimal,
    /// Instrument identifier.
    pub instrument_name: Ustr,
    /// Whether this trade was generated via `private/transfer_position`.
    pub is_transfer: bool,
    /// Free-form user label inherited from the order.
    #[serde(default)]
    pub label: Ustr,
    /// Maker / taker role of the user.
    pub liquidity_role: DeriveLiquidityRole,
    /// Mark price at the time of the trade.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub mark_price: Decimal,
    /// Originating order ID.
    pub order_id: String,
    /// RFQ quote ID when relevant.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub quote_id: Option<String>,
    /// Realized PnL booked by this trade.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub realized_pnl: Decimal,
    /// Owning subaccount.
    pub subaccount_id: i64,
    /// Trade timestamp (UNIX ms).
    pub timestamp: i64,
    /// Filled amount on this trade.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub trade_amount: Decimal,
    /// Fee charged for this trade.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub trade_fee: Decimal,
    /// Trade identifier.
    pub trade_id: String,
    /// Trade execution price.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub trade_price: Decimal,
    /// Ethereum L1 batch transaction hash, absent before settlement.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub tx_hash: Option<String>,
    /// Settlement batch stage when reported, independent of trade execution.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub batch_status: Option<String>,
    /// Settlement operation identity, independent of the trade and order IDs.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub op_uuid: Option<String>,
    /// Owning wallet address, absent in pending order responses.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub wallet: Option<Ustr>,
}

/// Public trade record returned by `public/get_trade_history` and the
/// `trades.{instrument_type}.{currency}` WS channel.
///
/// Public REST and WS rows carry participant roles and account detail. Optional
/// fields also accept sparse frames; settlement metadata does not gate trades.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct DerivePublicTrade {
    /// Trade side.
    pub direction: DeriveOrderSide,
    /// Underlying index price at the time of the trade.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub index_price: Decimal,
    /// Instrument identifier.
    pub instrument_name: Ustr,
    /// Role of this row's participant in the trade. The REST history endpoint
    /// returns one maker row and one taker row per trade under the same
    /// `trade_id`. Public WS rows also carry participant roles.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub liquidity_role: Option<DeriveLiquidityRole>,
    /// Mark price at the time of the trade.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub mark_price: Decimal,
    /// RFQ quote ID when relevant.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub quote_id: Option<String>,
    /// RFQ session ID when the trade originated from a request-for-quote.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub rfq_id: Option<String>,
    /// Realized PnL attributed to this participant, when supplied.
    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
    pub realized_pnl: Option<Decimal>,
    /// Participant subaccount, when supplied.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub subaccount_id: Option<i64>,
    /// Trade timestamp (UNIX ms).
    pub timestamp: i64,
    /// Filled amount.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub trade_amount: Decimal,
    /// Fee charged to this participant, when supplied.
    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
    pub trade_fee: Option<Decimal>,
    /// Trade identifier.
    pub trade_id: String,
    /// Execution price.
    #[serde(deserialize_with = "deserialize_decimal_token")]
    pub trade_price: Decimal,
    /// Ethereum L1 batch transaction hash from historical rows, when supplied.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub tx_hash: Option<String>,
    /// Settlement batch stage from historical rows, when supplied.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub batch_status: Option<String>,
    /// Settlement operation identity accepted when supplied.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub op_uuid: Option<String>,
    /// Participant wallet address, when supplied.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub wallet: Option<Ustr>,
}

/// Pagination metadata attached to listing endpoints.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct DerivePaginationInfo {
    /// Total number of items across all pages.
    pub count: i64,
    /// Number of pages available.
    pub num_pages: i64,
}

#[derive(Debug, Clone, Deserialize)]
pub(crate) struct DeriveInstrumentsResult {
    pub(crate) instruments: Vec<DeriveInstrument>,
    pub(crate) pagination: DerivePaginationInfo,
}

/// Paginated `private/get_orders` result envelope.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct DeriveOrdersResult {
    /// Orders on the current page. Deliberately strict: reconciliation infers
    /// state from absence, so a dropped order row is worse than a loud failure.
    pub orders: Vec<DeriveOrder>,
    /// Pagination metadata.
    pub pagination: DerivePaginationInfo,
    /// Owning subaccount.
    pub subaccount_id: i64,
}

/// `private/get_open_orders` result envelope.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct DeriveOpenOrdersResult {
    /// Currently open orders. Deliberately strict: reconciliation infers
    /// state from absence, so a dropped order row is worse than a loud failure.
    pub orders: Vec<DeriveOrder>,
    /// Owning subaccount.
    pub subaccount_id: i64,
}

/// Paginated `private/get_trade_history` result envelope.
#[derive(Clone, Debug, Serialize)]
pub struct DeriveTradesResult {
    /// Trades on the current page.
    pub trades: Vec<DeriveTrade>,
    /// Pagination metadata.
    pub pagination: DerivePaginationInfo,
    /// Owning subaccount.
    pub subaccount_id: i64,
    #[serde(skip)]
    pub(crate) records_complete: bool,
}

impl<'de> Deserialize<'de> for DeriveTradesResult {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        #[derive(Deserialize)]
        struct TradePage {
            trades: Vec<Box<RawValue>>,
            pagination: DerivePaginationInfo,
            subaccount_id: i64,
        }
        #[derive(Deserialize)]
        struct TradeFee {
            #[serde(rename = "trade_fee", deserialize_with = "deserialize_decimal_token")]
            _trade_fee: Decimal,
        }
        let page = TradePage::deserialize(deserializer)?;
        for trade in &page.trades {
            if !trade.get().starts_with('{') {
                return Err(serde::de::Error::custom(
                    "private trade row must be an object",
                ));
            }

            let _: TradeFee =
                serde_json::from_str(trade.get()).map_err(serde::de::Error::custom)?;
        }

        let count = page.trades.len();
        let trades: Vec<DeriveTrade> = salvage_rows(page.trades);
        Ok(Self {
            records_complete: trades.len() == count,
            trades,
            pagination: page.pagination,
            subaccount_id: page.subaccount_id,
        })
    }
}

/// Paginated `public/get_trade_history` result envelope.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct DerivePublicTradesResult {
    /// Trades on the current page.
    pub trades: Vec<DerivePublicTrade>,
    /// Pagination metadata.
    pub pagination: DerivePaginationInfo,
}

/// OHLCV candle returned by `public/get_tradingview_chart_data`.
///
/// The venue ships the `result` field as a flat array of these records; the
/// HTTP client deserializes that array directly into `Vec<DerivePublicCandle>`.
/// Timestamps are UNIX **seconds** (not milliseconds, as on the trade and
/// funding endpoints).
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct DerivePublicCandle {
    /// Open price for the bucket.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub open_price: Decimal,
    /// High price for the bucket.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub high_price: Decimal,
    /// Low price for the bucket.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub low_price: Decimal,
    /// Close price for the bucket.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub close_price: Decimal,
    /// Notional volume in USD over the bucket.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub volume_usd: Decimal,
    /// Base-asset volume (contracts) over the bucket.
    #[serde(deserialize_with = "deserialize_decimal")]
    pub volume_contracts: Decimal,
    /// Sample timestamp (UNIX seconds).
    pub timestamp: i64,
    /// Bucket start timestamp (UNIX seconds); regularly spaced by `period`.
    pub timestamp_bucket: i64,
}

/// Funding rate sample returned by `public/get_funding_rate_history`.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct DerivePublicFundingRate {
    /// Funding rate observed at `timestamp` (fraction per funding interval).
    #[serde(deserialize_with = "deserialize_decimal")]
    pub funding_rate: Decimal,
    /// Sample timestamp (UNIX ms).
    pub timestamp: i64,
}

/// `public/get_funding_rate_history` result envelope.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct DerivePublicFundingRateHistoryResult {
    /// Funding rate samples in venue response order (currently newest to oldest).
    pub funding_rate_history: Vec<DerivePublicFundingRate>,
}

/// `private/get_positions` result envelope.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct DerivePositionsResult {
    /// Positions held by the subaccount. Deliberately strict: mass status
    /// synthesizes flat reports for instruments absent from this list, so a
    /// dropped position row would report "flat" for a position the venue
    /// still holds.
    pub positions: Vec<DerivePosition>,
    /// Owning subaccount.
    pub subaccount_id: i64,
}

fn cancel_reason_empty() -> DeriveOrderCancelReason {
    DeriveOrderCancelReason::Empty
}

#[cfg(test)]
mod tests {
    use std::path::PathBuf;

    use nautilus_core::UnixNanos;
    use nautilus_model::identifiers::AccountId;
    use rstest::rstest;
    use serde_json::{Value, json};

    use super::*;

    fn data_path() -> PathBuf {
        PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("test_data")
    }

    fn load_json(filename: &str) -> Value {
        let content = std::fs::read_to_string(data_path().join(filename))
            .unwrap_or_else(|_| panic!("failed to read {filename}"));
        serde_json::from_str(&content).expect("invalid json")
    }

    #[rstest]
    fn test_request_serializes_with_jsonrpc_version_tag() {
        let req = JsonRpcRequest::new(7, "public/get_instruments", json!({"currency": "ETH"}));
        let wire = serde_json::to_value(&req).unwrap();
        assert_eq!(wire["jsonrpc"], "2.0");
        assert_eq!(wire["id"], 7);
        assert_eq!(wire["method"], "public/get_instruments");
        assert_eq!(wire["params"]["currency"], "ETH");
    }

    #[rstest]
    fn test_response_decodes_success_envelope() {
        let body = json!({"id": 1, "result": {"instruments": []}});
        let resp: JsonRpcResponse<Value> = serde_json::from_value(body).unwrap();
        assert_eq!(resp.id, Some(1));
        assert!(resp.error.is_none());
        assert!(resp.result.is_some());
    }

    #[rstest]
    fn test_response_decodes_error_envelope() {
        let body = json!({
            "id": 9,
            "error": {"code": -32600, "message": "Invalid Request"}
        });
        let resp: JsonRpcResponse<Value> = serde_json::from_value(body).unwrap();
        assert_eq!(resp.id, Some(9));
        assert!(resp.result.is_none());
        let err = resp.error.expect("error present");
        assert_eq!(err.code, -32600);
        assert_eq!(err.message, "Invalid Request");
        assert!(err.data.is_none());
    }

    #[rstest]
    fn test_response_decodes_error_envelope_with_data_field() {
        let body = json!({
            "id": 9,
            "error": {
                "code": -32602,
                "message": "Invalid params",
                "data": {"field": "currency"},
            }
        });
        let resp: JsonRpcResponse<Value> = serde_json::from_value(body).unwrap();
        let err = resp.error.expect("error present");
        assert_eq!(err.data, Some(json!({"field": "currency"})));
    }

    #[rstest]
    fn test_response_tolerates_missing_id() {
        let body = json!({"result": {"ok": true}});
        let resp: JsonRpcResponse<Value> = serde_json::from_value(body).unwrap();
        assert!(resp.id.is_none());
        assert!(resp.result.is_some());
    }

    #[rstest]
    fn test_response_tolerates_string_id() {
        let body = json!({"id": "e3c970c6-94aa-420c-b6db-d0f585a7fde9", "result": {"ok": true}});
        let resp: JsonRpcResponse<Value> = serde_json::from_value(body).unwrap();
        assert!(resp.id.is_none());
        assert!(resp.result.is_some());
    }

    #[rstest]
    fn test_response_decodes_numeric_string_id() {
        let body = json!({"id": "42", "result": {"ok": true}});
        let resp: JsonRpcResponse<Value> = serde_json::from_value(body).unwrap();
        assert_eq!(resp.id, Some(42));
        assert!(resp.result.is_some());
    }

    #[rstest]
    fn test_instrument_decodes_perp_with_perp_details() {
        let body = load_json("perps/instrument_eth.json");
        let instrument: DeriveInstrument = serde_json::from_value(body).unwrap();
        assert_eq!(instrument.instrument_name, "ETH-PERP");
        assert_eq!(instrument.instrument_type, DeriveInstrumentType::Perp);
        assert!(instrument.option_details.is_none());
        let perp = instrument.perp_details.expect("perp details present");
        assert_eq!(perp.index, "ETH-USD");
    }

    #[rstest]
    fn test_instrument_decodes_option_with_option_details() {
        let mut body = load_json("options/instrument_eth.json");
        body["scheduled_activation"] = json!(0);
        let instrument: DeriveInstrument = serde_json::from_value(body).unwrap();
        let option = instrument.option_details.expect("option details present");
        assert_eq!(option.option_type, DeriveOptionKind::Call);
        assert_eq!(option.strike.to_string(), "3500");
        assert!(option.settlement_price.is_none());
    }

    #[rstest]
    #[case(1_695_836_058_725_001_000)]
    #[case(u64::MAX)]
    fn test_order_nonce_string_round_trip(#[case] nonce: u64) {
        let mut body = load_json("perps/http_order_eth_partially_filled.json");
        body["nonce"] = json!(nonce.to_string());
        let order: DeriveOrder = serde_json::from_value(body).unwrap();
        let encoded = serde_json::to_value(&order).unwrap();
        let decoded: DeriveOrder = serde_json::from_value(encoded.clone()).unwrap();
        assert_eq!(order.nonce, nonce);
        assert_eq!(encoded["nonce"], nonce.to_string());
        assert_eq!(serde_json::to_value(decoded).unwrap(), encoded);
    }

    #[rstest]
    #[case(json!(""))]
    #[case(json!("-1"))]
    #[case(json!("18446744073709551616"))]
    #[case(json!(1_695_836_058_725_001_000_u64))]
    fn test_order_nonce_rejects_invalid_wire_values(#[case] nonce: Value) {
        let mut body = load_json("perps/http_order_eth_partially_filled.json");
        body["nonce"] = nonce;
        assert!(serde_json::from_value::<DeriveOrder>(body).is_err());
    }

    #[rstest]
    #[case(true, false)]
    #[case(false, true)]
    #[case(true, true)]
    fn test_order_defaults_optional_label_and_cancel_reason(
        #[case] omit_label: bool,
        #[case] omit_reason: bool,
    ) {
        let mut body = load_json("perps/http_order_eth_partially_filled.json");
        if omit_label {
            body["label"] = json!("");
        }

        let expected: DeriveOrder = serde_json::from_value(body.clone()).unwrap();
        let fields = body.as_object_mut().unwrap();
        if omit_label {
            fields.remove("label");
        }

        if omit_reason {
            fields.remove("cancel_reason");
        }

        let order: DeriveOrder = serde_json::from_value(body).unwrap();
        assert_eq!(
            serde_json::to_value(order).unwrap(),
            serde_json::to_value(expected).unwrap()
        );
    }

    #[rstest]
    fn test_order_decodes_partially_filled_market_order() {
        // Distinct `amount` and `filled_amount` so a struct-field swap is
        // detectable. Every Ustr-typed field has a unique value so a serde
        // rename or field-order regression surfaces against a single fixture.
        let body = load_json("perps/http_order_eth_partially_filled.json");
        let order: DeriveOrder = serde_json::from_value(body).unwrap();
        let debug = format!("{order:?}");
        assert_eq!(order.amount.to_string(), "2.0");
        assert_eq!(order.filled_amount.to_string(), "1.5");
        assert_eq!(order.average_price.to_string(), "3500.25");
        assert_eq!(order.order_status, DeriveOrderStatus::Filled);
        assert_eq!(order.cancel_reason, DeriveOrderCancelReason::Empty);
        assert_eq!(order.direction, DeriveOrderSide::Buy);
        assert_eq!(order.time_in_force, DeriveTimeInForce::Ioc);
        assert_eq!(order.order_type, DeriveOrderType::Market);
        assert_eq!(order.instrument_name, "ETH-PERP");
        assert_eq!(order.label, "alpha-strategy");
        assert_eq!(order.signer, "0xsigner");
        assert_eq!(order.order_id, "abc-123");
        assert_eq!(order.subaccount_id, 42);
        assert_eq!(order.signature_expiry_sec, 1_700_001_000);
        assert!(!order.mmp);
        assert!(!order.is_transfer);
        assert!(order.quote_id.is_none());
        assert!(order.replaced_order_id.is_none());
        assert!(debug.contains(REDACTED));
        assert!(!debug.contains("0xdead"));
    }

    #[rstest]
    fn test_replace_result_decodes_canceled_without_replacement() {
        let mut cancelled_order = load_json("perps/http_order_eth_partially_filled.json");
        cancelled_order["order_id"] = json!("old-order");
        cancelled_order["order_status"] = json!("cancelled");
        cancelled_order["label"] = json!("replacement-label");
        let result: DeriveReplaceResult = serde_json::from_value(json!({
            "order": null,
            "cancelled_order": cancelled_order,
            "create_order_error": {
                "code": 10001,
                "message": "insufficient margin",
            },
        }))
        .unwrap();

        let outcome = result
            .into_outcome("old-order", "replacement-label", 42, "ETH-PERP")
            .unwrap();

        let DeriveReplaceOutcome::Canceled {
            cancelled_order,
            create_order_error,
        } = outcome
        else {
            panic!("expected canceled outcome");
        };

        assert_eq!(cancelled_order.order_id, "old-order");
        assert_eq!(cancelled_order.order_status, DeriveOrderStatus::Cancelled);
        assert_eq!(create_order_error.code, 10001);
        assert_eq!(create_order_error.message, "insufficient margin");
        assert!(create_order_error.data.is_none());
    }

    #[rstest]
    fn test_replace_result_rejects_non_cancelled_partial_record() {
        let mut cancelled_order = load_json("perps/http_order_eth_partially_filled.json");
        cancelled_order["order_id"] = json!("old-order");
        cancelled_order["order_status"] = json!("open");
        let result: DeriveReplaceResult = serde_json::from_value(json!({
            "order": null,
            "cancelled_order": cancelled_order,
            "create_order_error": {
                "code": 10001,
                "message": "insufficient margin",
            },
        }))
        .unwrap();

        let error = result
            .into_outcome("old-order", "replacement-label", 42, "ETH-PERP")
            .unwrap_err();
        assert!(error.contains("had status open"));
    }

    #[rstest]
    fn test_replace_result_rejects_mismatched_replacement_label() {
        let mut replacement_order = load_json("perps/http_order_eth_partially_filled.json");
        replacement_order["order_id"] = json!("new-order");
        replacement_order["order_status"] = json!("open");
        replacement_order["label"] = json!("wrong-label");
        let result: DeriveReplaceResult = serde_json::from_value(json!({
            "order": replacement_order,
            "cancelled_order": null,
            "create_order_error": null,
        }))
        .unwrap();

        let error = result
            .into_outcome("old-order", "expected-label", 42, "ETH-PERP")
            .unwrap_err();
        assert!(error.contains("had label wrong-label, expected expected-label"));
    }

    #[rstest]
    fn test_position_decodes_perp_with_optional_leverage() {
        // Distinct decimal values per field so a struct-field swap surfaces.
        let body = load_json("perps/http_position_eth.json");
        let position: DerivePosition = serde_json::from_value(body).unwrap();
        assert_eq!(position.instrument_type, DeriveInstrumentType::Perp);
        assert_eq!(position.instrument_name, "ETH-PERP");
        assert_eq!(position.amount.to_string(), "-2");
        assert_eq!(position.delta.to_string(), "-2");
        assert_eq!(position.gamma.to_string(), "0.1");
        assert_eq!(position.theta.to_string(), "-0.3");
        assert_eq!(position.vega.to_string(), "0.5");
        assert_eq!(position.unrealized_pnl.to_string(), "8");
        assert_eq!(position.mark_value.to_string(), "-7008");
        assert_eq!(
            position.leverage.as_ref().map(ToString::to_string),
            Some("5.0".into()),
        );
        assert_eq!(
            position.liquidation_price.as_ref().map(ToString::to_string),
            Some("4200".into()),
        );
    }

    #[rstest]
    fn test_subaccount_decodes_with_collaterals_and_open_orders() {
        let body = load_json("common/http_subaccount_usdc.json");
        let subaccount: DeriveSubaccount = serde_json::from_value(body).unwrap();
        assert_eq!(subaccount.subaccount_id, 42);
        assert_eq!(subaccount.margin_type, "SM");
        assert_eq!(subaccount.collaterals.len(), 1);
        assert_eq!(subaccount.collaterals[0].asset_type, DeriveAssetType::Erc20);
        assert!(!subaccount.is_under_liquidation);
    }

    #[rstest]
    #[case("currency")]
    #[case("manager_id")]
    #[case("risk_universe_id")]
    #[case("failed_to_fetch")]
    #[case("margin_type")]
    #[case("mm_credits")]
    #[case("projected_margin_change")]
    #[case("vault_deposit_holds")]
    #[case("positions_value")]
    #[case("positions")]
    #[case("open_orders")]
    fn test_subaccount_requires_complete_v3_envelope(#[case] field: &str) {
        let mut body = load_json("common/http_subaccount_pm2.json");
        body.as_object_mut().unwrap().remove(field);

        assert!(serde_json::from_value::<DeriveSubaccount>(body).is_err());
    }

    #[rstest]
    #[case(serde_json::Value::Null)]
    #[case(json!(""))]
    fn test_subaccount_rejects_null_or_empty_required_decimals(#[case] invalid: Value) {
        for field in [
            "initial_margin",
            "maintenance_margin",
            "positions_initial_margin",
            "positions_maintenance_margin",
            "positions_value",
            "open_orders_margin",
            "mm_credits",
            "projected_margin_change",
        ] {
            let mut body = load_json("common/http_subaccount_pm2.json");
            body[field] = invalid.clone();
            assert!(
                serde_json::from_value::<DeriveSubaccount>(body).is_err(),
                "{field}"
            );
        }

        let mut body = load_json("common/http_subaccount_pm2.json");
        body["collaterals"][0]["amount"] = invalid;
        assert!(serde_json::from_value::<DeriveSubaccount>(body).is_err());
    }

    #[rstest]
    #[case("amount")]
    #[case("average_price")]
    #[case("filled_amount")]
    #[case("limit_price")]
    #[case("max_fee")]
    #[case("order_fee")]
    fn test_subaccount_rejects_empty_or_null_order_decimal(#[case] field: &str) {
        for invalid in [Value::Null, json!("")] {
            let mut body = load_json("common/http_subaccount_pm2.json");
            let mut order = load_json("perps/http_order_eth_partially_filled.json");
            order[field] = invalid;
            body["open_orders"] = json!([order]);

            assert!(
                serde_json::from_value::<DeriveSubaccount>(body).is_err(),
                "{field}"
            );
        }
    }

    #[rstest]
    fn test_subaccount_decodes_high_scale_decimal_values() {
        let body = load_json("common/http_subaccount_high_scale.json");
        let subaccount: DeriveSubaccount = serde_json::from_value(body).unwrap();
        let position = &subaccount.positions[0];

        assert_eq!(
            subaccount.initial_margin.to_string(),
            "0.1234567890123456789012345679",
        );
        assert_eq!(
            subaccount.collaterals[0].amount.to_string(),
            "0.1234567890123456789012345679",
        );
        assert_eq!(
            position.pending_funding.to_string(),
            "0.1234567890123456789012345679",
        );
        assert_eq!(
            position.leverage.as_ref().map(ToString::to_string),
            Some("5.1234567890123456789012345679".into()),
        );
        assert_eq!(
            position.liquidation_price.as_ref().map(ToString::to_string),
            Some("4200.1234567890123456789012346".into()),
        );

        // Order rows nested in the snapshot carry the same high-scale values.
        let open_order = &subaccount.open_orders[0];
        assert_eq!(
            open_order.filled_amount.to_string(),
            "0.1234567890123456789012345679",
        );
        assert_eq!(
            open_order.max_fee.to_string(),
            "0.1234567890123456789012345679",
        );
    }

    #[rstest]
    fn test_subaccount_retains_unknown_order_status_for_account_conversion() {
        let body = load_json("common/http_subaccount_unknown_variants.json");
        let subaccount: DeriveSubaccount = serde_json::from_value(body).unwrap();
        assert_eq!(subaccount.open_orders.len(), 2);
        assert_eq!(
            subaccount.open_orders[1].order_status,
            DeriveOrderStatus::Unknown
        );
        let mut modeled = subaccount.clone();
        modeled.open_orders[1].order_status = DeriveOrderStatus::Open;
        let expected = crate::http::parse::parse_derive_subaccount_to_balances(&modeled).unwrap();
        let actual = crate::http::parse::parse_derive_subaccount_to_balances(&subaccount).unwrap();

        assert_eq!(actual, expected);
    }

    #[rstest]
    fn test_subaccount_decodes_populated_vault_deposit_hold() {
        let mut body = load_json("common/http_subaccount_pm2.json");
        let hold = json!({
            "amount": "0.000000000123456789",
            "asset_name": "ETH",
            "currency": "ETH",
            "vault_id": 123,
        });
        body["vault_deposit_holds"] = json!([hold]);

        let subaccount: DeriveSubaccount = serde_json::from_value(body).unwrap();

        assert_eq!(
            serde_json::to_value(&subaccount.vault_deposit_holds).unwrap(),
            json!([hold])
        );
        assert_eq!(
            subaccount.vault_deposit_holds[0].amount.to_string(),
            "0.000000000123456789"
        );
    }

    #[rstest]
    fn test_public_trade_round_trips() {
        let body = load_json("perps/http_public_trade_eth_sell.json");
        let trade: DerivePublicTrade = serde_json::from_value(body).unwrap();
        assert_eq!(trade.direction, DeriveOrderSide::Sell);
        assert_eq!(trade.batch_status.as_deref(), Some("Settled"));
        let reserialized = serde_json::to_value(&trade).unwrap();
        assert_eq!(reserialized["instrument_name"], "ETH-PERP");
        assert_eq!(reserialized["liquidity_role"], "taker");
    }

    #[rstest]
    fn test_orders_result_envelope_decodes() {
        let body = json!({
            "orders": [],
            "pagination": {"count": 0, "num_pages": 0},
            "subaccount_id": 42,
        });
        let result: DeriveOrdersResult = serde_json::from_value(body).unwrap();
        assert!(result.orders.is_empty());
        assert_eq!(result.subaccount_id, 42);
        assert_eq!(result.pagination.count, 0);
    }

    #[rstest]
    fn test_orders_result_decodes_unknown_variant_fields() {
        let body = load_json("perps/http_orders_result_eth_unknown_variants.json");
        let result: DeriveOrdersResult = serde_json::from_value(body).unwrap();

        assert_eq!(result.orders.len(), 2);
        assert_eq!(result.orders[0].order_status, DeriveOrderStatus::Open);
        let unknowns = &result.orders[1];
        assert_eq!(unknowns.order_status, DeriveOrderStatus::Cancelled);
        assert_eq!(unknowns.cancel_reason, DeriveOrderCancelReason::Unknown);
        assert_eq!(unknowns.order_type, DeriveOrderType::Unknown);
        assert_eq!(unknowns.time_in_force, DeriveTimeInForce::Unknown);
        assert_eq!(unknowns.trigger_type, Some(DeriveTriggerType::Unknown));
        assert_eq!(
            unknowns.trigger_price_type,
            Some(DeriveTriggerPriceType::Unknown),
        );
    }

    #[rstest]
    fn test_orders_result_retains_unknown_status_and_rejects_report_conversion() {
        let mut body = load_json("perps/http_orders_result_eth_unknown_variants.json");
        body["orders"][0]["order_status"] = json!("queued");
        let result: DeriveOrdersResult = serde_json::from_value(body).unwrap();
        assert_eq!(result.orders.len(), 2);
        assert_eq!(result.orders[0].order_status, DeriveOrderStatus::Unknown);
        let error = crate::http::parse::parse_derive_order_to_report(
            &result.orders[0],
            AccountId::from("DERIVE-001"),
            UnixNanos::from(17),
        )
        .unwrap_err();
        assert_eq!(error.to_string(), "unmodeled Derive order status");
    }

    #[rstest]
    fn test_positions_result_fails_on_undecodable_row() {
        // Pins the deliberate strictness documented on the struct.
        let mut body = load_json("perps/http_positions_result_eth.json");
        body["positions"][0]["amount"] = json!({});

        assert!(serde_json::from_value::<DerivePositionsResult>(body).is_err());
    }

    fn perp_ticker_json() -> Value {
        load_json("perps/http_ticker_eth_snapshot.json")
    }

    #[rstest]
    fn test_ticker_decodes_perp_snapshot() {
        let ticker: DeriveTicker = serde_json::from_value(perp_ticker_json()).unwrap();
        assert_eq!(ticker.instrument_name, "ETH-PERP");
        assert_eq!(ticker.instrument_type, DeriveInstrumentType::Perp);
        assert_eq!(ticker.mark_price.to_string(), "3500.5");
        assert_eq!(ticker.best_bid_price.to_string(), "3499.5");
        assert_eq!(ticker.best_ask_price.to_string(), "3501.0");
        assert_eq!(ticker.timestamp, 1_700_000_000_000);
        assert!(ticker.option_details.is_none());
        assert!(ticker.option_pricing.is_none());
        let perp = ticker.perp_details.expect("perp details present");
        assert_eq!(perp.index, "ETH-USD");
        assert_eq!(perp.funding_rate.to_string(), "0.0002");
        let stats = ticker
            .stats
            .as_ref()
            .expect("WS ticker fixture includes stats");
        assert_eq!(stats.contract_volume.to_string(), "12345.6");
        assert_eq!(stats.high.to_string(), "3600");
        assert_eq!(stats.num_trades.to_string(), "789");
    }

    #[rstest]
    fn test_ticker_decodes_option_snapshot_with_greeks() {
        let body = load_json("options/http_ticker_eth_snapshot.json");
        let ticker: DeriveTicker = serde_json::from_value(body).unwrap();
        assert_eq!(ticker.instrument_type, DeriveInstrumentType::Option);
        assert!(ticker.perp_details.is_none());
        let option = ticker.option_details.expect("option details present");
        assert_eq!(option.option_type, DeriveOptionKind::Call);
        assert_eq!(option.strike.to_string(), "3500");
        assert!(option.settlement_price.is_none());
        let greeks = ticker.option_pricing.expect("option pricing present");
        assert_eq!(greeks.delta.to_string(), "0.55");
        assert_eq!(greeks.gamma.to_string(), "0.0008");
        assert_eq!(greeks.theta.to_string(), "-2.1");
        assert_eq!(greeks.vega.to_string(), "4.5");
        assert_eq!(greeks.iv.to_string(), "0.60");
        assert_eq!(greeks.forward_price.to_string(), "3505");
    }

    #[rstest]
    fn test_private_trade_decodes_with_order_link() {
        // Asserts the fields that distinguish DeriveTrade from DerivePublicTrade
        // (order_id, label, is_transfer, realized_pnl) plus the Ustr-typed
        // wallet and the typed enum fields.
        let body = load_json("perps/http_private_trade_eth.json");
        let trade: DeriveTrade = serde_json::from_value(body).unwrap();
        assert_eq!(trade.direction, DeriveOrderSide::Buy);
        assert_eq!(trade.liquidity_role, DeriveLiquidityRole::Maker);
        assert_eq!(trade.batch_status.as_deref(), Some("Settled"));
        assert_eq!(trade.instrument_name, "ETH-PERP");
        assert_eq!(trade.label, "alpha-strategy");
        assert_eq!(trade.wallet.as_ref().map(Ustr::as_str), Some("0xwallet"));
        assert_eq!(trade.order_id, "order-abc");
        assert_eq!(trade.trade_id, "trade-xyz");
        assert_eq!(trade.subaccount_id, 42);
        assert_eq!(trade.realized_pnl.to_string(), "12.5");
        assert_eq!(trade.trade_amount.to_string(), "0.5");
        assert_eq!(trade.trade_price.to_string(), "3499.0");
        assert!(!trade.is_transfer);
        assert!(trade.quote_id.is_none());
        assert_eq!(trade.tx_hash.as_deref(), Some("0xhash"));
    }

    #[rstest]
    #[case("trade_amount", "0.5")]
    #[case("trade_price", "3499.0")]
    #[case("trade_fee", "0.02")]
    fn test_native_trade_numeric_tokens_preserve_exact_value(
        #[case] field: &str,
        #[case] original: &str,
        #[values(
            ("1234567.123456789012", rust_decimal_macros::dec!(1234567.123456789012)),
            ("1.234567890123456789e-10", rust_decimal_macros::dec!(0.0000000001234567890123456789))
        )]
        (token, expected): (&str, Decimal),
    ) {
        let fixture = include_str!("../../test_data/perps/http_private_trade_eth.json");
        let row = fixture.replace(
            &format!("\"{field}\": \"{original}\""),
            &format!("\"{field}\": {token}"),
        );
        assert_ne!(row, fixture);
        let direct: DeriveTrade = serde_json::from_str(&row).unwrap();
        let page = serde_json::to_string(&serde_json::json!({
            "pagination": {"count": 1, "num_pages": 1},
            "subaccount_id": 42,
        }))
        .unwrap();
        let page = format!("{},\"trades\":[{row}]}}", page.trim_end_matches('}'));
        let page: DeriveTradesResult = serde_json::from_str(&page).unwrap();
        let subscription: crate::websocket::DeriveTradesSubscriptionData =
            serde_json::from_str(&format!("[{row}]")).unwrap();

        assert_eq!(page.trades.len(), 1);
        assert_eq!(subscription.trades.len(), 1);
        assert!(page.records_complete);

        for trade in [&direct, &page.trades[0], &subscription.trades[0]] {
            assert_eq!(
                trade.trade_amount,
                if field == "trade_amount" {
                    expected
                } else {
                    rust_decimal_macros::dec!(0.5)
                }
            );
            assert_eq!(
                trade.trade_price,
                if field == "trade_price" {
                    expected
                } else {
                    rust_decimal_macros::dec!(3499.0)
                }
            );
            assert_eq!(
                trade.trade_fee,
                if field == "trade_fee" {
                    expected
                } else {
                    rust_decimal_macros::dec!(0.02)
                }
            );
            assert_eq!(
                serde_json::to_value(trade).unwrap(),
                serde_json::to_value(&direct).unwrap()
            );
        }
    }

    #[rstest]
    fn test_v3_trade_rest_and_private_subscription_schema_parity() {
        let native: Vec<Value> = serde_json::from_str(include_str!(
            "../../test_data/perps/http_trades_v3_native.json"
        ))
        .unwrap();
        let stages: Vec<Value> = serde_json::from_str(include_str!(
            "../../test_data/common/trade_batch_stages.json"
        ))
        .unwrap();

        for stage in stages {
            let mut row = native[0].clone();
            row["batch_status"] = stage.clone();
            row["op_uuid"] = Value::Null;
            row["tx_hash"] = Value::Null;
            let result: DeriveTradesResult = serde_json::from_value(json!({
                "trades": [row.clone()], "pagination": {"count": 1, "num_pages": 1},
                "subaccount_id": 42,
            }))
            .unwrap();
            let subscription: crate::websocket::DeriveTradesSubscriptionData =
                serde_json::from_value(json!([row])).unwrap();
            assert_eq!(result.trades.len(), 1);
            assert_eq!(subscription.trades.len(), 1);
            let rest = &result.trades[0];
            let ws = &subscription.trades[0];
            assert_eq!(
                serde_json::to_value(rest).unwrap(),
                serde_json::to_value(ws).unwrap()
            );
            assert_eq!(rest.batch_status.as_deref(), stage.as_str());
            assert_eq!(rest.op_uuid, None);
            assert_eq!(rest.tx_hash, None);
            assert_eq!(rest.trade_fee, rust_decimal_macros::dec!(0.087052478068));
            assert_eq!(rest.trade_id, "pm2-held-fixture-trade-close");
            assert_eq!(rest.order_id, "pm2-held-fixture-order-close");
        }

        let mut row = native[1].clone();
        row.as_object_mut().unwrap().remove("batch_status");
        row.as_object_mut().unwrap().remove("op_uuid");
        row.as_object_mut().unwrap().remove("tx_hash");
        row.as_object_mut().unwrap().remove("label");
        let early: DeriveTrade = serde_json::from_value(row).unwrap();
        assert_eq!(early.batch_status, None);
        assert_eq!(early.op_uuid, None);
        assert_eq!(early.tx_hash, None);
        assert_eq!(early.label, Ustr::from(""));
    }

    #[rstest]
    #[case("trade_amount")]
    #[case("trade_price")]
    #[case("trade_fee")]
    fn test_v3_required_execution_decimals_reject_invalid_values(
        #[case] field: &str,
        #[values("null", "empty", "missing")] invalid: &str,
    ) {
        let mut row = load_json("perps/http_private_trade_eth.json");
        match invalid {
            "null" => row[field] = Value::Null,
            "empty" => row[field] = json!(""),
            "missing" => {
                row.as_object_mut().unwrap().remove(field);
            }
            _ => unreachable!(),
        }

        assert!(serde_json::from_value::<DeriveTrade>(row.clone()).is_err());
        let rest = serde_json::from_value::<DeriveTradesResult>(json!({
            "trades": [row.clone()], "pagination": {"count": 1, "num_pages": 1}, "subaccount_id": 42,
        }));
        let ws: crate::websocket::DeriveTradesSubscriptionData =
            serde_json::from_value(json!([row.clone()])).unwrap();
        let mut order = load_json("spot/http_submit_order_response_mainnet.json")["result"].clone();
        order["trades"] = json!([row.clone()]);
        let order_result: DeriveOrderResult = serde_json::from_value(order).unwrap();

        if field == "trade_fee" {
            assert!(rest.is_err());
        } else {
            let rest = rest.unwrap();
            assert_eq!(rest.trades.len(), 0);
            assert!(!rest.records_complete);
        }

        assert_eq!(ws.trades.len(), 0);
        assert_eq!(order_result.trades.len(), 0);
        assert!(
            serde_json::from_value::<crate::websocket::DeriveTradesSubscriptionData>(row.clone())
                .is_err()
        );

        if field != "trade_fee" {
            assert!(serde_json::from_value::<DerivePublicTrade>(row.clone()).is_err());
            let valid = load_json("perps/http_public_trade_eth_sell.json");
            assert!(
                serde_json::from_value::<DerivePublicTradesResult>(json!({
                    "trades": [valid, row.clone()],
                    "pagination": {"count": 2, "num_pages": 1},
                }))
                .is_err()
            );
            let payload: crate::websocket::WsSubscriptionPayload = serde_json::from_str(
                &json!({"channel": "trades.perp.ETH", "data": [valid, row]}).to_string(),
            )
            .unwrap();
            assert!(crate::websocket::parse_public_ws_data(&payload).is_err());
        }
    }

    #[rstest]
    #[case(json!("0"))]
    #[case(json!(0))]
    fn test_v3_execution_fee_accepts_explicit_zero(#[case] fee: Value) {
        let mut row = load_json("perps/http_private_trade_eth.json");
        row["trade_fee"] = fee;
        let trade: DeriveTrade = serde_json::from_value(row).unwrap();
        assert_eq!(trade.trade_fee, Decimal::ZERO);
        assert_eq!(trade.trade_amount, rust_decimal_macros::dec!(0.5));
        assert_eq!(trade.trade_price, rust_decimal_macros::dec!(3499));
    }

    #[rstest]
    fn test_private_trade_decodes_high_scale_decimal_values() {
        let mut body = load_json("perps/http_private_trade_eth.json");
        body["trade_fee"] = json!("1.234567890123456789012345678912345e-1");
        body["realized_pnl"] = json!("0.1234567890123456789012345678912345");

        let trade: DeriveTrade = serde_json::from_value(body).unwrap();

        assert_eq!(
            trade.trade_fee.to_string(),
            "0.1234567890123456789012345679"
        );
        assert_eq!(
            trade.realized_pnl.to_string(),
            "0.1234567890123456789012345679",
        );
    }

    #[rstest]
    fn test_order_result_decodes_pending_trade_with_null_tx_hash() {
        let mut body = load_json("spot/http_submit_order_response_mainnet.json");
        let mut trade = load_json("perps/http_private_trade_eth.json");
        trade["tx_hash"] = Value::Null;
        trade["batch_status"] = Value::Null;
        trade.as_object_mut().unwrap().remove("wallet");
        body["result"]["trades"] = json!([trade]);

        let result: DeriveOrderResult =
            serde_json::from_value(body["result"].clone()).expect("result decodes");

        assert_eq!(result.trades.len(), 1);
        assert!(result.trades[0].tx_hash.is_none());
        assert_eq!(result.trades[0].batch_status, None);
        assert!(result.trades[0].wallet.is_none());
    }

    #[rstest]
    fn test_empty_result_decodes_cancel_ack_shapes() {
        let object: DeriveEmptyResult = serde_json::from_value(json!({})).unwrap();
        let ok_string: DeriveEmptyResult = serde_json::from_value(json!("ok")).unwrap();
        let null_envelope: JsonRpcResponse<DeriveEmptyResult> =
            serde_json::from_value(json!({"id": 1, "result": null})).unwrap();

        assert_eq!(object, DeriveEmptyResult {});
        assert_eq!(ok_string, DeriveEmptyResult {});
        assert_eq!(null_envelope.result, Some(DeriveEmptyResult {}));
    }

    #[rstest]
    #[case("common/ws_cancel_by_label_zero.json", 0)]
    #[case("common/ws_cancel_by_label_nonzero.json", 2)]
    fn test_cancel_order_by_label_result_decodes_count(
        #[case] filename: &str,
        #[case] expected: i64,
    ) {
        let response: JsonRpcResponse<DeriveCancelByLabelResult> =
            serde_json::from_value(load_json(filename)).expect("response decodes");

        assert_eq!(response.result.unwrap().cancelled_orders, expected);
    }

    #[rstest]
    fn test_order_result_preserves_trades_with_unknown_status() {
        let mut order = load_json("perps/http_order_eth_partially_filled.json");
        order["order_status"] = serde_json::json!("future-status");
        let trade = load_json("perps/http_private_trade_eth.json");
        let result: DeriveOrderResult = serde_json::from_value(serde_json::json!({
            "order": order, "trades": [trade],
        }))
        .unwrap();
        assert_eq!(result.trades.len(), 1);
        assert_eq!(
            serde_json::to_value(&result.trades[0]).unwrap(),
            serde_json::to_value(serde_json::from_value::<DeriveTrade>(trade).unwrap()).unwrap()
        );
    }

    #[rstest]
    fn test_trades_result_envelope_decodes() {
        let body = load_json("perps/http_trades_result_eth.json");
        let result: DeriveTradesResult = serde_json::from_value(body).unwrap();
        assert_eq!(result.trades.len(), 1);
        assert_eq!(result.subaccount_id, 7);
        assert_eq!(result.pagination.count, 1);
        assert_eq!(result.pagination.num_pages, 1);
        assert_eq!(result.trades[0].trade_id, "t-1");
        assert!(result.records_complete);
    }

    #[rstest]
    fn test_trades_result_salvages_unknown_variant_rows() {
        let body = load_json("perps/http_trades_result_eth_unknown_variants.json");
        let result: DeriveTradesResult = serde_json::from_value(body).unwrap();

        // The `short`-direction row is undecodable and skipped; the rest survive.
        assert_eq!(result.trades.len(), 2);
        assert_eq!(result.trades[0].trade_id, "t-1");
        let unknowns = &result.trades[1];
        assert_eq!(unknowns.trade_id, "t-2");
        assert_eq!(unknowns.liquidity_role, DeriveLiquidityRole::Unknown);
        assert!(!result.records_complete);
    }

    #[rstest]
    #[case(json!("invalid-fee"))]
    #[case(json!(""))]
    #[case(Value::Null)]
    fn test_trades_result_rejects_undecodable_fee(#[case] fee: Value) {
        let mut body = load_json("perps/http_trades_result_eth.json");
        let mut bad = body["trades"][0].clone();
        bad["trade_id"] = json!("bad-fee-row");
        bad["trade_fee"] = fee;
        body["trades"].as_array_mut().unwrap().push(bad);
        assert!(serde_json::from_value::<DeriveTradesResult>(body).is_err());
    }

    #[rstest]
    #[case(serde_json::json!(["0.1"]))]
    #[case(serde_json::json!(0.1))]
    #[case(serde_json::Value::Null)]
    fn test_trades_result_rejects_non_object_fee_rows(#[case] row: Value) {
        let result = serde_json::from_value::<DeriveTradesResult>(json!({
            "trades": [row],
            "pagination": {"count": 1, "num_pages": 1},
            "subaccount_id": 42,
        }));

        assert_eq!(
            result.unwrap_err().to_string(),
            "private trade row must be an object"
        );
    }

    #[rstest]
    fn test_trades_result_preserves_unknown_batch_metadata() {
        let mut body = load_json("perps/http_trades_result_eth.json");
        body["trades"][0]["batch_status"] = json!("FutureStage");

        let result: DeriveTradesResult = serde_json::from_value(body).unwrap();

        assert_eq!(result.trades.len(), 1);
        assert_eq!(
            result.trades[0].batch_status.as_deref(),
            Some("FutureStage")
        );
    }

    #[rstest]
    fn test_public_trades_result_envelope_decodes() {
        let body = load_json("perps/http_public_trades_result_eth.json");
        let result: DerivePublicTradesResult = serde_json::from_value(body).unwrap();
        assert_eq!(result.trades.len(), 1);
        assert_eq!(result.pagination.count, 1);
        assert_eq!(result.trades[0].trade_id, "pub-1");
    }

    #[rstest]
    fn test_public_funding_rate_history_result_envelope_decodes() {
        let body = load_json("perps/http_public_funding_rate_history_eth.json");
        let result: DerivePublicFundingRateHistoryResult = serde_json::from_value(body).unwrap();
        assert_eq!(result.funding_rate_history.len(), 3);
        let first = &result.funding_rate_history[0];
        assert_eq!(first.funding_rate.to_string(), "0.00012");
        assert_eq!(first.timestamp, 1_700_000_000_000);
        assert_eq!(
            result.funding_rate_history.last().unwrap().timestamp,
            1_700_007_200_000,
        );
    }

    #[rstest]
    fn test_public_candles_decode_array() {
        // The venue ships `result` as a flat array; the HTTP client decodes
        // directly into `Vec<DerivePublicCandle>`. The fixture mirrors that
        // wire shape.
        let body = load_json("perps/http_public_candles_eth.json");
        let candles: Vec<DerivePublicCandle> = serde_json::from_value(body).unwrap();
        assert_eq!(candles.len(), 3);
        let first = &candles[0];
        assert_eq!(first.open_price.to_string(), "3500.0");
        assert_eq!(first.high_price.to_string(), "3501.5");
        assert_eq!(first.low_price.to_string(), "3499.0");
        assert_eq!(first.close_price.to_string(), "3501.0");
        assert_eq!(first.volume_usd.to_string(), "12345.6");
        assert_eq!(first.volume_contracts.to_string(), "3.527");
        // Distinct `timestamp` vs `timestamp_bucket` so a field-swap mutation
        // in any downstream parser is detectable.
        assert_eq!(first.timestamp, 1_700_000_007);
        assert_eq!(first.timestamp_bucket, 1_700_000_000);
        assert_eq!(candles.last().unwrap().timestamp_bucket, 1_700_001_800);
    }

    #[rstest]
    fn test_positions_result_envelope_decodes() {
        let body = load_json("perps/http_positions_result_eth.json");
        let result: DerivePositionsResult = serde_json::from_value(body).unwrap();
        assert_eq!(result.positions.len(), 1);
        assert_eq!(result.subaccount_id, 42);
        assert_eq!(result.positions[0].instrument_name, "ETH-PERP");
        assert!(result.positions[0].leverage.is_none());
        assert!(result.positions[0].liquidation_price.is_none());
    }
}