Implement OKX spot margin reconciliation and quote-quantity orders

cjdsellers · cjdsellers · commit d3f012269dbe · 2025-10-25T18:10:30.000+10:00
diff --git a/crates/adapters/okx/src/common/parse.rs b/crates/adapters/okx/src/common/parse.rs
@@ -59,7 +59,7 @@ use crate::{
         consts::OKX_VENUE,
         enums::{
             OKXExecType, OKXInstrumentType, OKXOrderStatus, OKXOrderType, OKXPositionSide, OKXSide,
-            OKXVipLevel,
+            OKXTargetCurrency, OKXVipLevel,
         },
         models::OKXInstrument,
     },
@@ -532,18 +532,100 @@ pub fn parse_order_status_report(
     size_precision: u8,
     ts_init: UnixNanos,
 ) -> OrderStatusReport {
-    let quantity = order
-        .sz
-        .parse::<f64>()
-        .ok()
-        .map(|v| Quantity::new(v, size_precision))
-        .unwrap_or_default();
-    let filled_qty = order
-        .acc_fill_sz
-        .parse::<f64>()
-        .ok()
-        .map(|v| Quantity::new(v, size_precision))
-        .unwrap_or_default();
+    // Parse quantities based on target currency
+    // OKX always returns acc_fill_sz in base currency, but sz depends on tgt_ccy
+
+    // Determine if this is a quote-quantity order
+    // Method 1: Explicit tgt_ccy field set to QuoteCcy
+    let is_quote_qty_explicit = order.tgt_ccy == Some(OKXTargetCurrency::QuoteCcy);
+
+    // Method 2: Use OKX defaults when tgt_ccy is None (old orders or missing field)
+    // OKX API defaults for SPOT market orders: BUY orders use quote_ccy, SELL orders use base_ccy
+    // Note: tgtCcy only applies to SPOT market orders (not limit orders)
+    // For limit orders, sz is always in base currency regardless of side
+    let is_quote_qty_heuristic = order.tgt_ccy.is_none()
+        && (order.inst_type == OKXInstrumentType::Spot
+            || order.inst_type == OKXInstrumentType::Margin)
+        && order.side == OKXSide::Buy
+        && order.ord_type == OKXOrderType::Market;
+
+    let (quantity, filled_qty) = if is_quote_qty_explicit || is_quote_qty_heuristic {
+        // Quote-quantity order: sz is in quote currency, need to convert to base
+        let sz_quote = order.sz.parse::<f64>().unwrap_or(0.0);
+
+        // Determine the price to use for conversion
+        // Priority: 1) limit price (px) for limit orders, 2) avg_px for market orders
+        let conversion_price = if !order.px.is_empty() && order.px != "0" {
+            // Limit order: use the limit price (order.px)
+            order.px.parse::<f64>().unwrap_or(0.0)
+        } else if !order.avg_px.is_empty() && order.avg_px != "0" {
+            // Market order with fills: use average fill price
+            order.avg_px.parse::<f64>().unwrap_or(0.0)
+        } else {
+            log::warn!(
+                "No price available for conversion: ord_id={}, px='{}', avg_px='{}'",
+                order.ord_id.as_str(),
+                order.px,
+                order.avg_px
+            );
+            0.0
+        };
+
+        // Convert quote quantity to base: quantity_base = sz_quote / price
+        let quantity_base = if conversion_price > 0.0 {
+            Quantity::new(sz_quote / conversion_price, size_precision)
+        } else {
+            // No price available, can't convert - use sz as-is temporarily
+            log::warn!(
+                "Cannot convert, using sz as-is: ord_id={}, sz={}",
+                order.ord_id.as_str(),
+                order.sz
+            );
+            order
+                .sz
+                .parse::<f64>()
+                .ok()
+                .map(|v| Quantity::new(v, size_precision))
+                .unwrap_or_default()
+        };
+
+        let filled_qty = order
+            .acc_fill_sz
+            .parse::<f64>()
+            .ok()
+            .map(|v| Quantity::new(v, size_precision))
+            .unwrap_or_default();
+
+        (quantity_base, filled_qty)
+    } else {
+        // Base-quantity order: both sz and acc_fill_sz are in base currency
+        let quantity = order
+            .sz
+            .parse::<f64>()
+            .ok()
+            .map(|v| Quantity::new(v, size_precision))
+            .unwrap_or_default();
+        let filled_qty = order
+            .acc_fill_sz
+            .parse::<f64>()
+            .ok()
+            .map(|v| Quantity::new(v, size_precision))
+            .unwrap_or_default();
+
+        (quantity, filled_qty)
+    };
+
+    // For quote-quantity orders marked as FILLED, adjust quantity to match filled_qty
+    // to avoid precision mismatches from quote-to-base conversion
+    let (quantity, filled_qty) = if (is_quote_qty_explicit || is_quote_qty_heuristic)
+        && order.state == OKXOrderStatus::Filled
+        && filled_qty.is_positive()
+    {
+        (filled_qty, filled_qty)
+    } else {
+        (quantity, filled_qty)
+    };
+
     let order_side: OrderSide = order.side.into();
     let okx_status: OKXOrderStatus = order.state;
     let order_status: OrderStatus = okx_status.into();
diff --git a/crates/adapters/okx/src/http/models.rs b/crates/adapters/okx/src/http/models.rs
@@ -175,6 +175,7 @@ pub struct OKXAccount {
 /// Represents a balance detail for a single currency in an OKX account.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
+#[cfg_attr(feature = "python", pyo3::pyclass)]
 pub struct OKXBalanceDetail {
     /// Available balance.
     pub avail_bal: String,
diff --git a/crates/adapters/okx/src/python/http.rs b/crates/adapters/okx/src/python/http.rs
@@ -539,6 +539,29 @@ impl OKXHttpClient {
             Python::attach(|py| timestamp.into_py_any(py))
         })
     }
+
+    #[pyo3(name = "http_get_balance")]
+    fn py_http_get_balance<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyAny>> {
+        let client = self.clone();
+
+        pyo3_async_runtimes::tokio::future_into_py(py, async move {
+            let accounts = client
+                .inner
+                .http_get_balance()
+                .await
+                .map_err(to_pyvalue_err)?;
+
+            let details: Vec<_> = accounts
+                .into_iter()
+                .flat_map(|account| account.details)
+                .collect();
+
+            Python::attach(|py| {
+                let pylist = PyList::new(py, details)?;
+                Ok(pylist.into_py_any_unwrap(py))
+            })
+        })
+    }
 }
 
 impl From<OKXHttpError> for PyErr {
diff --git a/crates/adapters/okx/src/python/mod.rs b/crates/adapters/okx/src/python/mod.rs
@@ -17,6 +17,7 @@
 
 pub mod enums;
 pub mod http;
+pub mod models;
 pub mod urls;
 pub mod websocket;
 
@@ -32,6 +33,7 @@ pub fn okx(_: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<super::websocket::OKXWebSocketClient>()?;
     m.add_class::<super::websocket::messages::OKXWebSocketError>()?;
     m.add_class::<super::http::OKXHttpClient>()?;
+    m.add_class::<crate::http::models::OKXBalanceDetail>()?;
     m.add_class::<crate::common::enums::OKXInstrumentType>()?;
     m.add_class::<crate::common::enums::OKXContractType>()?;
     m.add_class::<crate::common::enums::OKXMarginMode>()?;
diff --git a/crates/adapters/okx/src/python/models.rs b/crates/adapters/okx/src/python/models.rs
@@ -0,0 +1,36 @@
+// -------------------------------------------------------------------------------------------------
+//  Copyright (C) 2015-2025 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.
+// -------------------------------------------------------------------------------------------------
+
+use pyo3::prelude::*;
+
+use crate::http::models::OKXBalanceDetail;
+
+#[pymethods]
+impl OKXBalanceDetail {
+    #[getter]
+    fn ccy(&self) -> String {
+        self.ccy.to_string()
+    }
+
+    #[getter]
+    fn cash_bal(&self) -> &str {
+        &self.cash_bal
+    }
+
+    #[getter]
+    fn liab(&self) -> &str {
+        &self.liab
+    }
+}
diff --git a/crates/adapters/okx/src/websocket/parse.rs b/crates/adapters/okx/src/websocket/parse.rs
@@ -46,8 +46,8 @@ use crate::{
     common::{
         consts::{OKX_POST_ONLY_CANCEL_REASON, OKX_POST_ONLY_CANCEL_SOURCE},
         enums::{
-            OKXBookAction, OKXCandleConfirm, OKXOrderCategory, OKXOrderStatus, OKXOrderType,
-            OKXTriggerType,
+            OKXBookAction, OKXCandleConfirm, OKXInstrumentType, OKXOrderCategory, OKXOrderStatus,
+            OKXOrderType, OKXSide, OKXTargetCurrency, OKXTriggerType,
         },
         models::OKXInstrument,
         parse::{
@@ -892,8 +892,77 @@ pub fn parse_order_status_report(
     };
 
     let size_precision = instrument.size_precision();
-    let quantity = parse_quantity(&msg.sz, size_precision)?;
-    let filled_qty = parse_quantity(&msg.acc_fill_sz.clone().unwrap_or_default(), size_precision)?;
+
+    // Parse quantities based on target currency
+    // OKX always returns acc_fill_sz in base currency, but sz depends on tgt_ccy
+
+    // Determine if this is a quote-quantity order
+    // Method 1: Explicit tgt_ccy field set to QuoteCcy
+    let is_quote_qty_explicit = msg.tgt_ccy == Some(OKXTargetCurrency::QuoteCcy);
+
+    // Method 2: Use OKX defaults when tgt_ccy is None (old orders or missing field)
+    // OKX API defaults for SPOT market orders: BUY orders use quote_ccy, SELL orders use base_ccy
+    // Note: tgtCcy only applies to SPOT market orders (not limit orders)
+    // For limit orders, sz is always in base currency regardless of side
+    let is_quote_qty_heuristic = msg.tgt_ccy.is_none()
+        && (msg.inst_type == OKXInstrumentType::Spot || msg.inst_type == OKXInstrumentType::Margin)
+        && msg.side == OKXSide::Buy
+        && msg.ord_type == OKXOrderType::Market;
+
+    let (quantity, filled_qty) = if is_quote_qty_explicit || is_quote_qty_heuristic {
+        // Quote-quantity order: sz is in quote currency, need to convert to base
+        let sz_quote = msg.sz.parse::<f64>().map_err(|e| {
+            anyhow::anyhow!("Failed to parse sz='{}' as quote quantity: {}", msg.sz, e)
+        })?;
+
+        // Determine the price to use for conversion
+        // Priority: 1) limit price (px) for limit orders, 2) avg_px for market orders
+        let conversion_price = if !msg.px.is_empty() && msg.px != "0" {
+            // Limit order: use the limit price (msg.px)
+            msg.px
+                .parse::<f64>()
+                .map_err(|e| anyhow::anyhow!("Failed to parse px='{}': {}", msg.px, e))?
+        } else if !msg.avg_px.is_empty() && msg.avg_px != "0" {
+            // Market order with fills: use average fill price
+            msg.avg_px
+                .parse::<f64>()
+                .map_err(|e| anyhow::anyhow!("Failed to parse avg_px='{}': {}", msg.avg_px, e))?
+        } else {
+            0.0
+        };
+
+        // Convert quote quantity to base: quantity_base = sz_quote / price
+        let quantity_base = if conversion_price > 0.0 {
+            Quantity::new(sz_quote / conversion_price, size_precision)
+        } else {
+            // No price available, can't convert - use sz as-is temporarily
+            // This will be corrected once the order gets filled and price is available
+            parse_quantity(&msg.sz, size_precision)?
+        };
+
+        let filled_qty =
+            parse_quantity(&msg.acc_fill_sz.clone().unwrap_or_default(), size_precision)?;
+
+        (quantity_base, filled_qty)
+    } else {
+        // Base-quantity order: both sz and acc_fill_sz are in base currency
+        let quantity = parse_quantity(&msg.sz, size_precision)?;
+        let filled_qty =
+            parse_quantity(&msg.acc_fill_sz.clone().unwrap_or_default(), size_precision)?;
+
+        (quantity, filled_qty)
+    };
+
+    // For quote-quantity orders marked as FILLED, adjust quantity to match filled_qty
+    // to avoid precision mismatches from quote-to-base conversion
+    let (quantity, filled_qty) = if (is_quote_qty_explicit || is_quote_qty_heuristic)
+        && msg.state == OKXOrderStatus::Filled
+        && filled_qty.is_positive()
+    {
+        (filled_qty, filled_qty)
+    } else {
+        (quantity, filled_qty)
+    };
 
     let ts_accepted = parse_millisecond_timestamp(msg.c_time);
     let ts_last = parse_millisecond_timestamp(msg.u_time);
diff --git a/examples/live/okx/okx_exec_tester.py b/examples/live/okx/okx_exec_tester.py
@@ -41,15 +41,15 @@
 
 # Configuration - Change instrument_type to switch between trading modes
 instrument_type = OKXInstrumentType.SWAP  # SPOT, SWAP, FUTURES, OPTION
-use_spot_margin = False
+use_spot_margin = True
 token = "ETH"
 
 # Symbol mapping based on instrument type
 if instrument_type == OKXInstrumentType.SPOT:
     symbol = f"{token}-USDT"
     contract_types: tuple[OKXContractType, ...] | None = None  # SPOT doesn't use contract types
     if use_spot_margin:
-        order_qty = Decimal("20.00")
+        order_qty = Decimal("10.00")
         use_quote_quantity = True
     else:
         order_qty = Decimal("0.01")
@@ -182,6 +182,7 @@
             contract_types=contract_types,
             margin_mode=OKXMarginMode.CROSS,
             use_spot_margin=use_spot_margin,
+            # use_spot_cash_position_reports=True,  # Spot CASH position reports
             # use_mm_mass_cancel=True,
             is_demo=False,  # If client uses the demo API
             use_fills_channel=False,  # Set to True if VIP5+ to get separate fill reports
diff --git a/nautilus_trader/adapters/okx/config.py b/nautilus_trader/adapters/okx/config.py
@@ -137,6 +137,12 @@ class OKXExecClientConfig(LiveExecClientConfig, frozen=True):
         If True, uses OKX's mass-cancel endpoint for cancel_all_orders operations.
         This endpoint is typically restricted to market makers and high-volume traders.
         If False, cancels orders individually (works for all users).
+    use_spot_cash_position_reports : bool, default False
+        If True, generates position reports for SPOT CASH instruments based on wallet balances.
+        Positive balances (cash_bal - liab) are treated as LONG positions, and negative balances
+        (borrowing) as SHORT positions. This may lead to unintended liquidation of wallet assets
+        if strategies are not designed to handle SPOT positions properly.
+        If False, SPOT instruments return FLAT position reports (default behavior).
 
     """
 
@@ -157,3 +163,4 @@ class OKXExecClientConfig(LiveExecClientConfig, frozen=True):
     retry_delay_max_ms: PositiveInt | None = 10_000
     use_fills_channel: bool = False
     use_mm_mass_cancel: bool = False
+    use_spot_cash_position_reports: bool = False
diff --git a/nautilus_trader/adapters/okx/execution.py b/nautilus_trader/adapters/okx/execution.py
diff --git a/nautilus_trader/core/nautilus_pyo3.pyi b/nautilus_trader/core/nautilus_pyo3.pyi
diff --git a/tests/integration_tests/adapters/okx/test_spot_cash_position_reports.py b/tests/integration_tests/adapters/okx/test_spot_cash_position_reports.py
