Fix OKX SPOT handling and currency registration

cjdsellers · cjdsellers · commit 5b6fa6264c7e · 2025-10-15T19:37:36.000+10:00
- Add instrument type filtering for funding rate subscriptions
- Fix position reconciliation for mixed SPOT+SWAP configurations
diff --git a/crates/adapters/okx/src/websocket/client.rs b/crates/adapters/okx/src/websocket/client.rs
@@ -2372,13 +2372,15 @@ impl OKXWebSocketClient {
             }
         };
 
+        // For SPOT market orders, handle tgtCcy parameter
+        // https://www.okx.com/docs-v5/en/#order-book-trading-trade-post-place-order
+        // OKX API default behavior for SPOT market orders:
+        // - BUY orders default to tgtCcy=quote_ccy (sz represents quote currency amount)
+        // - SELL orders default to tgtCcy=base_ccy (sz represents base currency amount)
         if instrument_type == OKXInstrumentType::Spot && order_type == OrderType::Market {
-            // https://www.okx.com/docs-v5/en/#order-book-trading-trade-post-place-order
-            // OKX API default behavior for SPOT:
-            // - BUY orders default to tgtCcy=quote_ccy
-            // - SELL orders default to tgtCcy=base_ccy
             match quote_quantity {
                 Some(true) => {
+                    // Explicitly request quote currency sizing
                     builder.tgt_ccy(OKX_TARGET_CCY_QUOTE.to_string());
                 }
                 Some(false) => {
diff --git a/examples/live/okx/okx_data_tester.py b/examples/live/okx/okx_data_tester.py
@@ -38,33 +38,56 @@
 
 # Configuration - Change instrument_type to switch between trading modes
 instrument_type = OKXInstrumentType.SWAP  # SPOT, SWAP, FUTURES, OPTION
+token = "ETH"
 
 # Symbol mapping based on instrument type
 if instrument_type == OKXInstrumentType.SPOT:
-    symbol = "ETH-USDT"
+    symbol = f"{token}-USDT"
     contract_types: tuple[OKXContractType, ...] | None = None  # SPOT doesn't use contract types
     trade_size = Decimal("0.01")
 elif instrument_type == OKXInstrumentType.SWAP:
-    symbol = "ETH-USDT-SWAP"
-    contract_types = (OKXContractType.LINEAR, OKXContractType.INVERSE)
+    symbol = f"{token}-USDT-SWAP"
+    contract_types = (OKXContractType.LINEAR,)
     trade_size = Decimal("0.01")
 elif instrument_type == OKXInstrumentType.FUTURES:
     # Note: ETH-USD futures follow same pattern as BTC-USD
     # Format: ETH-USD-YYMMDD (e.g., ETH-USD-241227, ETH-USD-250131)
-    symbol = "ETH-USD-251226"  # ETH-USD futures expiring December 26, 2025
+    symbol = f"{token}-USD-251226"  # ETH-USD futures expiring December 26, 2025
     contract_types = (OKXContractType.INVERSE,)  # ETH-USD futures are inverse contracts
     trade_size = Decimal(1)
 elif instrument_type == OKXInstrumentType.OPTION:
-    symbol = "ETH-USD-251226-4000-C"  # Example: ETH-USD call option, strike $4000, exp 2025-12-26
+    symbol = (
+        f"{token}-USD-251226-4000-C"  # Example: ETH-USD call option, strike $4000, exp 2025-12-26
+    )
     contract_types = None  # OPTIONS don't use contract types in the same way
     trade_size = Decimal(1)
 else:
     raise ValueError(f"Unsupported instrument type: {instrument_type}")
 
+instrument_id = InstrumentId.from_str(f"{symbol}.{OKX}")
+
+# Additional instruments for testing (matching exec_tester setup)
+spot_instrument_id = InstrumentId.from_str(f"{token}-USDT.{OKX}")
+swap_instrument_id = InstrumentId.from_str(f"{token}-USDT-SWAP.{OKX}")
+
+instrument_types = (
+    OKXInstrumentType.SPOT,
+    OKXInstrumentType.SWAP,
+)
+
+instrument_families = (
+    # "BTC-USD",
+    # "ETH-USDT",
+)
+
 # Configure the trading node
 config_node = TradingNodeConfig(
     trader_id=TraderId("TESTER-001"),
-    logging=LoggingConfig(log_level="INFO", use_pyo3=True),
+    logging=LoggingConfig(
+        log_level="INFO",
+        log_level_file="DEBUG",
+        use_pyo3=True,
+    ),
     exec_engine=LiveExecEngineConfig(
         reconciliation=False,  # Not applicable
     ),
@@ -74,32 +97,38 @@
             api_secret=None,  # 'OKX_API_SECRET' env var
             api_passphrase=None,  # 'OKX_API_PASSPHRASE' env var
             base_url_http=None,  # Override with custom endpoint
-            instrument_provider=InstrumentProviderConfig(load_all=True),
-            instrument_types=(instrument_type,),  # Will load swap instruments
-            contract_types=contract_types,  # Will load linear contracts
+            instrument_provider=InstrumentProviderConfig(
+                load_all=False,
+                load_ids=frozenset([spot_instrument_id, swap_instrument_id]),
+            ),
+            instrument_types=instrument_types,
+            contract_types=contract_types,
             is_demo=False,  # If client uses the demo API
             http_timeout_secs=10,  # Set to reasonable duration
         ),
     },
     timeout_connection=20.0,
     timeout_disconnection=5.0,
-    timeout_post_stop=1.0,
+    timeout_post_stop=2.0,
 )
 
 # Instantiate the node with a configuration
 node = TradingNode(config=config_node)
 
 # Configure and initialize the tester
 config_tester = DataTesterConfig(
-    instrument_ids=[InstrumentId.from_str(f"{symbol}.OKX")],
-    bar_types=[BarType.from_str(f"{symbol}.OKX-1-MINUTE-LAST-EXTERNAL")],
+    instrument_ids=[spot_instrument_id, swap_instrument_id],
+    bar_types=[
+        BarType.from_str(f"{spot_instrument_id.value}-1-MINUTE-LAST-EXTERNAL"),
+        BarType.from_str(f"{swap_instrument_id.value}-1-MINUTE-LAST-EXTERNAL"),
+    ],
     # subscribe_book_deltas=True,
     # subscribe_book_depth=True,
     subscribe_book_at_interval=True,  # Only legacy Cython wrapped book (not PyO3)
     subscribe_quotes=True,
     subscribe_trades=True,
     subscribe_mark_prices=True,
-    subscribe_index_prices=True if instrument_type == OKXInstrumentType.SPOT else False,
+    subscribe_index_prices=False,  # Only for some derivatives
     subscribe_funding_rates=True,
     subscribe_bars=True,
     subscribe_instrument_status=False,
diff --git a/examples/live/okx/okx_exec_tester.py b/examples/live/okx/okx_exec_tester.py
@@ -41,26 +41,29 @@
 
 # Configuration - Change instrument_type to switch between trading modes
 instrument_type = OKXInstrumentType.SWAP  # SPOT, SWAP, FUTURES, OPTION
+token = "ETH"
 
 # Symbol mapping based on instrument type
 if instrument_type == OKXInstrumentType.SPOT:
-    symbol = "ETH-USDT"
+    symbol = f"{token}-USDT"
     contract_types: tuple[OKXContractType, ...] | None = None  # SPOT doesn't use contract types
-    order_qty = Decimal("0.005")
+    order_qty = Decimal("0.01")
     enable_sells = False
 elif instrument_type == OKXInstrumentType.SWAP:
-    symbol = "ETH-USDT-SWAP"
-    contract_types = (OKXContractType.LINEAR, OKXContractType.INVERSE)
+    symbol = f"{token}-USDT-SWAP"
+    contract_types = (OKXContractType.LINEAR,)
     order_qty = Decimal("0.01")
     enable_sells = True
 elif instrument_type == OKXInstrumentType.FUTURES:
     # Format: ETH-USD-YYMMDD (e.g., ETH-USD-241227, ETH-USD-250131)
-    symbol = "ETH-USD-251226"  # ETH-USD futures expiring 2025-12-26
+    symbol = f"{token}-USD-251226"  # ETH-USD futures expiring 2025-12-26
     contract_types = (OKXContractType.INVERSE,)  # ETH-USD futures are inverse contracts
     order_qty = Decimal(1)
     enable_sells = True
 elif instrument_type == OKXInstrumentType.OPTION:
-    symbol = "ETH-USD-251226-4000-C"  # Example: ETH-USD call option, strike 4000, exp 2025-12-26
+    symbol = (
+        f"{token}-USD-251226-4000-C"  # Example: ETH-USD call option, strike 4000, exp 2025-12-26
+    )
     contract_types = None  # Options don't use contract types in the same way
     order_qty = Decimal(1)
     enable_sells = True
@@ -69,11 +72,13 @@
 
 instrument_id = InstrumentId.from_str(f"{symbol}.{OKX}")
 
+# Additional instruments for reconciliation (matching wingman setup)
+spot_instrument_id = InstrumentId.from_str(f"{token}-USDT.{OKX}")
+swap_instrument_id = InstrumentId.from_str(f"{token}-USDT-SWAP.{OKX}")
+
 instrument_types = (
     OKXInstrumentType.SPOT,
     OKXInstrumentType.SWAP,
-    OKXInstrumentType.FUTURES,
-    # OKXInstrumentType.OPTION,
 )
 
 instrument_families = (
@@ -91,7 +96,7 @@
     ),
     exec_engine=LiveExecEngineConfig(
         reconciliation=True,
-        reconciliation_instrument_ids=[instrument_id],
+        reconciliation_instrument_ids=[spot_instrument_id, swap_instrument_id],
         # reconciliation_lookback_mins=60,
         open_check_interval_secs=5.0,
         open_check_open_only=True,
@@ -132,9 +137,11 @@
             api_secret=None,  # 'OKX_API_SECRET' env var
             api_passphrase=None,  # 'OKX_API_PASSPHRASE' env var
             base_url_http=None,  # Override with custom endpoint
-            instrument_provider=InstrumentProviderConfig(load_all=True),
+            instrument_provider=InstrumentProviderConfig(
+                load_all=False,
+                load_ids=frozenset([spot_instrument_id, swap_instrument_id]),
+            ),
             instrument_types=instrument_types,
-            instrument_families=instrument_families,
             contract_types=contract_types,
             is_demo=False,  # If client uses the demo API
             http_timeout_secs=10,  # Set to reasonable duration
@@ -147,9 +154,11 @@
             api_passphrase=None,  # 'OKX_API_PASSPHRASE' env var
             base_url_http=None,  # Override with custom endpoint
             base_url_ws=None,  # Override with custom endpoint
-            instrument_provider=InstrumentProviderConfig(load_all=True),
+            instrument_provider=InstrumentProviderConfig(
+                load_all=False,
+                load_ids=frozenset([spot_instrument_id, swap_instrument_id]),
+            ),
             instrument_types=instrument_types,
-            instrument_families=instrument_families,
             contract_types=contract_types,
             # margin_mode=OKXMarginMode.ISOLATED,
             use_spot_margin=False,
@@ -172,14 +181,14 @@
 # Configure your strategy
 config_tester = ExecTesterConfig(
     instrument_id=instrument_id,
-    external_order_claims=[instrument_id],
+    external_order_claims=[spot_instrument_id, swap_instrument_id],
     use_hyphens_in_client_order_ids=False,  # OKX doesn't allow hyphens in client order IDs
     # subscribe_quotes=False,
     # subscribe_trades=False,
     # subscribe_book=True,
     enable_buys=True,
     enable_sells=enable_sells,
-    # open_position_on_start_qty=order_qty,
+    open_position_on_start_qty=order_qty,
     open_position_time_in_force=TimeInForce.FOK,
     tob_offset_ticks=100,
     # stop_offset_ticks=1,
diff --git a/nautilus_trader/adapters/okx/data.py b/nautilus_trader/adapters/okx/data.py
@@ -58,6 +58,7 @@
 from nautilus_trader.model.enums import BookType
 from nautilus_trader.model.enums import book_type_to_str
 from nautilus_trader.model.identifiers import ClientId
+from nautilus_trader.model.instruments import CryptoPerpetual
 from nautilus_trader.model.instruments import Instrument
 
 
@@ -314,6 +315,20 @@ async def _subscribe_index_prices(self, command: SubscribeIndexPrices) -> None:
         await self._ws_client.subscribe_index_prices(pyo3_instrument_id)
 
     async def _subscribe_funding_rates(self, command: SubscribeFundingRates) -> None:
+        # Funding rates only apply to perpetual swaps
+        instrument = self._instrument_provider.find(command.instrument_id)
+        if instrument is None:
+            self._log.error(f"Cannot find instrument for {command.instrument_id}")
+            return
+
+        # Check if instrument is a perpetual swap
+        if not isinstance(instrument, CryptoPerpetual):
+            self._log.warning(
+                f"Funding rates not applicable for {command.instrument_id} "
+                f"(instrument type: {type(instrument).__name__}), skipping subscription",
+            )
+            return
+
         pyo3_instrument_id = nautilus_pyo3.InstrumentId.from_str(command.instrument_id.value)
         await self._ws_client.subscribe_funding_rates(pyo3_instrument_id)
 
@@ -362,6 +377,20 @@ async def _unsubscribe_index_prices(self, command: UnsubscribeIndexPrices) -> No
         await self._ws_client.unsubscribe_index_prices(pyo3_instrument_id)
 
     async def _unsubscribe_funding_rates(self, command: UnsubscribeFundingRates) -> None:
+        # Funding rates only apply to perpetual swaps
+        instrument = self._instrument_provider.find(command.instrument_id)
+        if instrument is None:
+            self._log.error(f"Cannot find instrument for {command.instrument_id}")
+            return
+
+        # Check if instrument is a perpetual swap
+        if not isinstance(instrument, CryptoPerpetual):
+            self._log.warning(
+                f"Funding rates not applicable for {command.instrument_id} "
+                f"(instrument type: {type(instrument).__name__}), skipping unsubscription",
+            )
+            return
+
         pyo3_instrument_id = nautilus_pyo3.InstrumentId.from_str(command.instrument_id.value)
         await self._ws_client.unsubscribe_funding_rates(pyo3_instrument_id)
 
diff --git a/nautilus_trader/adapters/okx/execution.py b/nautilus_trader/adapters/okx/execution.py
@@ -62,6 +62,7 @@
 from nautilus_trader.model.identifiers import ClientId
 from nautilus_trader.model.identifiers import ClientOrderId
 from nautilus_trader.model.identifiers import InstrumentId
+from nautilus_trader.model.instruments import CurrencyPair
 from nautilus_trader.model.orders import Order
 
 
@@ -647,13 +648,15 @@ async def generate_position_status_reports(  # noqa: C901 (too complex)
 
         try:
             if command.instrument_id:
-                # SPOT instruments in CASH account don't have positions - return FLAT
-                if self.account_type == AccountType.CASH:
-                    instrument = self._cache.instrument(command.instrument_id)
-                    if instrument is None:
-                        raise RuntimeError(
-                            f"Cannot create FLAT position report - instrument {command.instrument_id} not found in cache",
-                        )
+                # Check if this is a SPOT instrument (SPOT instruments don't have positions)
+                instrument = self._cache.instrument(command.instrument_id)
+                if instrument is None:
+                    raise RuntimeError(
+                        f"Cannot create position report - instrument {command.instrument_id} not found in cache",
+                    )
+
+                # SPOT instruments (CurrencyPair) don't have positions - return FLAT
+                if isinstance(instrument, CurrencyPair):
                     report = PositionStatusReport.create_flat(
                         account_id=self.account_id,
                         instrument_id=command.instrument_id,
diff --git a/nautilus_trader/adapters/okx/providers.py b/nautilus_trader/adapters/okx/providers.py
@@ -148,6 +148,13 @@ async def load_all_async(self, filters: dict | None = None) -> None:
         for instrument in instruments:
             self.add(instrument=instrument)
 
+            base_currency = instrument.get_base_currency()
+            if base_currency is not None:
+                self.add_currency(base_currency)
+
+            self.add_currency(instrument.quote_currency)
+            self.add_currency(instrument.get_settlement_currency())
+
         self._log.info(f"Loaded {len(self._instruments)} instruments")
 
     async def load_ids_async(  # noqa: C901 (too complex)
@@ -203,6 +210,13 @@ async def load_ids_async(  # noqa: C901 (too complex)
                 continue  # Filter instrument ID
             self.add(instrument=instrument)
 
+            base_currency = instrument.get_base_currency()
+            if base_currency is not None:
+                self.add_currency(base_currency)
+
+            self.add_currency(instrument.quote_currency)
+            self.add_currency(instrument.get_settlement_currency())
+
     async def load_async(self, instrument_id: InstrumentId, filters: dict | None = None) -> None:
         PyCondition.not_none(instrument_id, "instrument_id")
         await self.load_ids_async([instrument_id], filters)
