Fix BitMEX instrument bootstrap for unknown types

- Deserialize instruments per-item; skip unknown rows with a warning
- Error if all rows fail to deserialize (venue schema change guard)
- Add `BitmexInstrumentState::Unknown` to tolerate new venue states
- Route legacy futures, spreads, and reference basket to parsers
- Rename `StockPerpetual` to `TradFiPerpetual`

Author: cjdsellers

RELEASES.md

@@ -7,6 +7,8 @@ Released on TBD (UTC).
 - Added Binance Futures funding-rate history support in Rust
 - Added Binance Futures ticker data support in Rust
 - Added Binance order-list submission in Rust
+- Added `BitmexInstrumentState::Unknown` to tolerate unrecognized venue states without bootstrap failure
+- Added BitMEX legacy futures, spreads, and reference basket instrument parsing
 - Added cache order index crash-recovery restore for Redis and Postgres adapters (Rust)
 - Added Hyperliquid builder attribution opt-out
 - Added Hyperliquid historical trade requests
@@ -36,6 +38,7 @@ Released on TBD (UTC).
 - Changed Redis cache account/order/position storage to event logs; clear old typed state (Rust)
 - Changed `SyntheticInstrument` fallible methods to return `SyntheticInstrumentError` instead of `anyhow::Error` (Rust)
 - Changed WebSocket and socket `reconnect_timeout_ms` to bound only connection establishment (Rust)
+- Renamed `BitmexInstrumentType::StockPerpetual` to `TradFiPerpetual` (covers equities, FX, and commodities)
 - Renamed Rust/PyO3 instrument `tick_scheme_name` to `tick_scheme`; Cython keeps `tick_scheme_name`
 
 ### Security
@@ -57,6 +60,7 @@ Released on TBD (UTC).
 - Fixed Binance Futures node panic on `BNFCR` Credits Trading Mode balances
 - Fixed Binance Spot expired order handling
 - Fixed Binance Spot/Futures WebSocket connection pool race (#4244), thanks @filipmacek
+- Fixed BitMEX instrument bootstrap aborting on any row deserialize failure (#4283), thanks for reporting @seungpyoson
 - Fixed blocking Python HTTP functions holding the GIL for the full request duration
 - Fixed Blockchain snapshot bootstrap checks
 - Fixed Blockchain pool-event replay to require durable timestamps before checkpoints
@@ -78,6 +82,7 @@ Released on TBD (UTC).
 - Fixed `HttpClient` rejecting invalid response header keys instead of silently dropping them (Rust)
 - Fixed Hyperliquid bracket trigger-child statuses and atomic market fills orphaning orders at submission (#4160), thanks @sonnymai
 - Fixed Hyperliquid cancel-replace fill stranding on a dropped `ACCEPTED` (#4270), thanks for reporting @AlphaTraderK
+- Fixed `Instrument` rejecting negative `min_price`, preventing spread instruments from loading in Python
 - Fixed Interactive Brokers reconnect startup handling (#4210), thanks @faysou
 - Fixed Interactive Brokers to use `permId` for stable order identity (#4276), thanks @faysou
 - Fixed Kraken spot WebSocket dead-connection detection with an idle timeout (#4275), thanks @folknor

crates/adapters/bitmex/src/common/enums.rs

@@ -640,10 +640,10 @@ pub enum BitmexInstrumentType {
     #[serde(rename = "FFICSX")]
     PredictionMarket,
 
-    /// Stock-based Perpetual Contracts (e.g., SPY, equity derivatives).
-    /// CFI code FFSCSX - financial future on stocks, cash settled.
+    /// TradFi Perpetual Contracts (equities, FX, and commodities).
+    /// CFI code FFSCSX - financial future on non-crypto underlyings, cash settled.
     #[serde(rename = "FFSCSX")]
-    StockPerpetual,
+    TradFiPerpetual,
 
     /// Perpetual Contracts (crypto).
     #[serde(rename = "FFWCSX")]
@@ -828,6 +828,9 @@ pub enum BitmexInstrumentState {
     Settled,
     /// Instrument is delisted.
     Delisted,
+    /// Unrecognized instrument state received from the venue.
+    #[serde(other)]
+    Unknown,
 }
 
 impl From<&BitmexInstrumentState> for MarketStatusAction {
@@ -838,6 +841,7 @@ impl From<&BitmexInstrumentState> for MarketStatusAction {
             BitmexInstrumentState::Settled => Self::Close,
             BitmexInstrumentState::Unlisted => Self::NotAvailableForTrading,
             BitmexInstrumentState::Delisted => Self::NotAvailableForTrading,
+            BitmexInstrumentState::Unknown => Self::NotAvailableForTrading,
         }
     }
 }
@@ -991,7 +995,7 @@ mod tests {
             r#""FFWCSF""#
         );
         assert_eq!(
-            serde_json::to_string(&BitmexInstrumentType::StockPerpetual).unwrap(),
+            serde_json::to_string(&BitmexInstrumentType::TradFiPerpetual).unwrap(),
             r#""FFSCSX""#
         );
         assert_eq!(
@@ -1085,7 +1089,7 @@ mod tests {
         );
         assert_eq!(
             serde_json::from_str::<BitmexInstrumentType>(r#""FFSCSX""#).unwrap(),
-            BitmexInstrumentType::StockPerpetual
+            BitmexInstrumentType::TradFiPerpetual
         );
         assert_eq!(
             serde_json::from_str::<BitmexInstrumentType>(r#""IFXXXP""#).unwrap(),
@@ -1323,10 +1327,20 @@ mod tests {
         BitmexInstrumentState::Delisted,
         MarketStatusAction::NotAvailableForTrading
     )]
+    #[case(
+        BitmexInstrumentState::Unknown,
+        MarketStatusAction::NotAvailableForTrading
+    )]
     fn test_bitmex_instrument_state_to_market_status_action(
         #[case] state: BitmexInstrumentState,
         #[case] expected: MarketStatusAction,
     ) {
         assert_eq!(MarketStatusAction::from(&state), expected);
     }
+
+    #[rstest]
+    fn test_bitmex_instrument_state_unknown_deserializes_from_unrecognized_string() {
+        let state: BitmexInstrumentState = serde_json::from_str(r#""SomeFutureState""#).unwrap();
+        assert_eq!(state, BitmexInstrumentState::Unknown);
+    }
 }

crates/adapters/bitmex/src/http/client.rs

@@ -512,9 +512,13 @@ impl BitmexRawHttpClient {
 
     /// Get all instruments.
     ///
+    /// Instruments that cannot be deserialized (e.g. unknown fields for new BitMEX
+    /// instrument types) are skipped with a warning rather than failing the whole
+    /// response.
+    ///
     /// # Errors
     ///
-    /// Returns an error if the request fails, the response cannot be parsed, or the API returns an error.
+    /// Returns an error if the HTTP request fails or the response is not a JSON array.
     pub async fn get_instruments(
         &self,
         active_only: bool,
@@ -524,8 +528,29 @@ impl BitmexRawHttpClient {
         } else {
             "/instrument"
         };
-        self.send_request::<_, ()>(Method::GET, path, None, None, false)
-            .await
+        let raw: Vec<serde_json::Value> = self
+            .send_request::<_, ()>(Method::GET, path, None, None, false)
+            .await?;
+
+        let raw_len = raw.len();
+        let mut instruments = Vec::with_capacity(raw_len);
+
+        for value in raw {
+            match serde_json::from_value::<BitmexInstrument>(value) {
+                Ok(inst) => instruments.push(inst),
+                Err(e) => {
+                    log::warn!("Skipping instrument that could not be deserialized: {e}");
+                }
+            }
+        }
+
+        if raw_len > 0 && instruments.is_empty() {
+            return Err(BitmexHttpError::JsonError(format!(
+                "All {raw_len} instrument(s) failed to deserialize; venue schema may have changed"
+            )));
+        }
+
+        Ok(instruments)
     }
 
     /// Requests the current server time from BitMEX.

crates/adapters/bitmex/src/http/parse.rs

@@ -101,7 +101,8 @@ pub fn parse_instrument_any(
         BitmexInstrumentState::Open | BitmexInstrumentState::Closed => {}
         state @ (BitmexInstrumentState::Unlisted
         | BitmexInstrumentState::Settled
-        | BitmexInstrumentState::Delisted) => {
+        | BitmexInstrumentState::Delisted
+        | BitmexInstrumentState::Unknown) => {
             return InstrumentParseResult::Inactive { symbol, state };
         }
     }
@@ -134,7 +135,7 @@ pub fn parse_instrument_any(
                 error: e.to_string(),
             },
         },
-        BitmexInstrumentType::FuturesSpread => {
+        BitmexInstrumentType::FuturesSpread | BitmexInstrumentType::FuturesSpreads => {
             match parse_crypto_futures_spread_instrument(instrument, ts_init) {
                 Ok(inst) => InstrumentParseResult::Ok(Box::new(inst)),
                 Err(e) => InstrumentParseResult::Failed {
@@ -144,8 +145,10 @@ pub fn parse_instrument_any(
                 },
             }
         }
-        BitmexInstrumentType::PredictionMarket => {
-            // Prediction markets work similarly to futures (bounded 0-100, cash settled)
+        BitmexInstrumentType::PredictionMarket
+        | BitmexInstrumentType::LegacyFutures
+        | BitmexInstrumentType::LegacyFuturesN => {
+            // Prediction markets and legacy futures share the futures field structure
             match parse_futures_instrument(instrument, ts_init) {
                 Ok(inst) => InstrumentParseResult::Ok(Box::new(inst)),
                 Err(e) => InstrumentParseResult::Failed {
@@ -159,11 +162,12 @@ pub fn parse_instrument_any(
         | BitmexInstrumentType::CryptoIndex
         | BitmexInstrumentType::FxIndex
         | BitmexInstrumentType::LendingIndex
+        | BitmexInstrumentType::ReferenceBasket
         | BitmexInstrumentType::VolatilityIndex
         | BitmexInstrumentType::StockIndex
         | BitmexInstrumentType::YieldIndex => {
-            // Parse index instruments as perpetuals for cache purposes
-            // They need to be in cache for WebSocket price updates
+            // Parse index and reference basket instruments for cache purposes;
+            // they are needed for WebSocket price updates
             match parse_index_instrument(instrument, ts_init) {
                 Ok(inst) => InstrumentParseResult::Ok(Box::new(inst)),
                 Err(e) => InstrumentParseResult::Failed {
@@ -174,15 +178,14 @@ pub fn parse_instrument_any(
             }
         }
 
-        // Explicitly list unsupported types for clarity
-        BitmexInstrumentType::StockPerpetual
+        // TradFi perpetuals (FFSCSX) parse correctly but CryptoPerpetual carries
+        // AssetClass::Cryptocurrency, which misclassifies equity/FX/commodity perps.
+        // Keep unsupported until a PerpetualContract parse path is wired up.
+        // Options require a strike price field not yet present in BitmexInstrument.
+        BitmexInstrumentType::TradFiPerpetual
         | BitmexInstrumentType::CallOption
         | BitmexInstrumentType::PutOption
         | BitmexInstrumentType::SwapRate
-        | BitmexInstrumentType::ReferenceBasket
-        | BitmexInstrumentType::LegacyFutures
-        | BitmexInstrumentType::LegacyFuturesN
-        | BitmexInstrumentType::FuturesSpreads
         | BitmexInstrumentType::Other => InstrumentParseResult::Unsupported {
             symbol,
             instrument_type,
@@ -1199,6 +1202,20 @@ mod tests {
         );
     }
 
+    #[rstest]
+    fn test_parse_instrument_any_skips_unknown_instrument_state() {
+        let json_data = load_test_json("http_get_instrument_xbtusd.json");
+        let mut instrument: BitmexInstrument = serde_json::from_str(&json_data).unwrap();
+        instrument.state = BitmexInstrumentState::Unknown;
+
+        let result = parse_instrument_any(&instrument, UnixNanos::default());
+
+        assert!(
+            matches!(result, InstrumentParseResult::Inactive { .. }),
+            "expected Inactive for unknown state, was {result:?}"
+        );
+    }
+
     #[rstest]
     fn test_parse_instrument_any_parses_active_crypto_futures_spread() {
         let json_data = load_test_json("http_get_instrument_xbtm26_xbtu26_spread.json");