Skip to main content

nautilus_interactive_brokers/common/
symbology.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Symbology for converting between Interactive Brokers contracts and Nautilus identifiers.
17
18use std::{collections::HashMap, str::FromStr, sync::LazyLock};
19
20use ibapi::contracts::{Contract, Currency, Exchange, OptionRight, SecurityType, Symbol};
21use jiff::{Timestamp, tz::Offset};
22use nautilus_model::identifiers::{
23    InstrumentId, Symbol as NautilusSymbol, Venue,
24    futures::{
25        FuturesYearDigits, format_futures_symbol, futures_month, futures_month_code,
26        parse_futures_symbol as parse_futures_code, resolve_futures_year,
27        resolve_futures_year_from_expiry,
28    },
29};
30
31use crate::{
32    common::enums::{IbOptionRight, IbSecurityType},
33    config::SymbologyMethod,
34};
35
36/// Converts between IB contracts and Nautilus instrument IDs using one configured method.
37#[derive(Debug, Clone, Copy, PartialEq, Eq)]
38pub struct Symbology {
39    method: SymbologyMethod,
40    futures_year_digits: FuturesYearDigits,
41    share_class_space: bool,
42}
43
44impl Symbology {
45    #[must_use]
46    pub const fn new(method: SymbologyMethod) -> Self {
47        Self {
48            method,
49            futures_year_digits: FuturesYearDigits::DEFAULT,
50            share_class_space: true,
51        }
52    }
53
54    /// Selects one- or two-digit years for futures instrument IDs.
55    #[must_use]
56    pub fn with_futures_year_digits(mut self, futures_year_digits: FuturesYearDigits) -> Self {
57        self.futures_year_digits = futures_year_digits;
58        self
59    }
60
61    /// Selects whether simplified stock IDs keep IB's share-class space (`BRK B`) or use a
62    /// hyphen (`BRK-B`).
63    #[must_use]
64    pub fn with_share_class_space(mut self, share_class_space: bool) -> Self {
65        self.share_class_space = share_class_space;
66        self
67    }
68
69    #[must_use]
70    pub const fn method(self) -> SymbologyMethod {
71        self.method
72    }
73
74    /// Converts an IB contract to a Nautilus instrument ID.
75    ///
76    /// # Errors
77    ///
78    /// Returns an error if the instrument ID cannot be constructed.
79    pub fn instrument_id(
80        self,
81        contract: &Contract,
82        venue: Option<Venue>,
83    ) -> anyhow::Result<InstrumentId> {
84        let instrument_id = match self.method {
85            SymbologyMethod::Simplified => contract_to_instrument_id_simplified(
86                contract,
87                venue,
88                self.futures_year_digits,
89                self.share_class_space,
90            ),
91            SymbologyMethod::Raw => {
92                contract_to_instrument_id_raw(contract, venue, self.futures_year_digits)
93            }
94        };
95
96        Ok(instrument_id)
97    }
98
99    /// Converts a Nautilus instrument ID to an IB contract.
100    ///
101    /// # Errors
102    ///
103    /// Returns an error if the identifier format is unsupported.
104    pub fn contract(
105        self,
106        instrument_id: InstrumentId,
107        exchange: Option<&str>,
108    ) -> anyhow::Result<Contract> {
109        self.contract_with_currency(instrument_id, exchange, None)
110    }
111
112    pub(crate) fn contract_with_currency(
113        self,
114        instrument_id: InstrumentId,
115        exchange: Option<&str>,
116        currency: Option<&str>,
117    ) -> anyhow::Result<Contract> {
118        if instrument_id.venue.as_str() == "OPRA" {
119            let symbol = instrument_id
120                .symbol
121                .as_str()
122                .strip_suffix("=OPT")
123                .unwrap_or(instrument_id.symbol.as_str());
124
125            if !is_canonical_occ_option_symbol(symbol) {
126                anyhow::bail!("Invalid OPRA option symbol: {symbol}");
127            }
128        }
129
130        let reference_year = i32::from(Offset::UTC.to_datetime(Timestamp::now()).year());
131        Ok(instrument_id_to_contract(
132            instrument_id,
133            exchange,
134            self.futures_year_digits,
135            reference_year,
136            currency,
137        ))
138    }
139}
140
141impl From<SymbologyMethod> for Symbology {
142    fn from(method: SymbologyMethod) -> Self {
143        Self::new(method)
144    }
145}
146
147fn ib_option_right_to_option_right(right: IbOptionRight) -> OptionRight {
148    match right {
149        IbOptionRight::Call => OptionRight::Call,
150        IbOptionRight::Put => OptionRight::Put,
151    }
152}
153
154/// Convert an IB Contract to an InstrumentId using simplified symbology.
155///
156/// This implements IB_SIMPLIFIED symbology: clean, readable symbols.
157/// For example:
158/// - STK: "AAPL" -> "AAPL.SMART"
159/// - CASH: "EUR.USD" -> "EUR/USD.IDEALPRO"
160/// - FUT: "ESM23" -> "ESM23.GLOBEX"
161/// - OPT: "AAPL230120C00150000" -> "AAPL230120C00150000.SMART"
162/// - IND: "SPX" -> "^SPX.SMART"
163fn contract_to_instrument_id_simplified(
164    contract: &Contract,
165    venue: Option<Venue>,
166    futures_year_digits: FuturesYearDigits,
167    share_class_space: bool,
168) -> InstrumentId {
169    let venue = venue.unwrap_or_else(|| {
170        // For Index and Future, use contract exchange when set (e.g. ESTX50 -> EUREX, FESX -> EUREX).
171        match contract.security_type {
172            SecurityType::Index => {
173                if !contract.exchange.as_str().is_empty() && contract.exchange.as_str() != "SMART" {
174                    Venue::from(contract.exchange.as_str())
175                } else {
176                    Venue::from("SMART")
177                }
178            }
179            SecurityType::Future => {
180                if !contract.exchange.as_str().is_empty() && contract.exchange.as_str() != "SMART" {
181                    Venue::from(contract.exchange.as_str())
182                } else {
183                    Venue::from("GLOBEX")
184                }
185            }
186            SecurityType::ForexPair => Venue::from("IDEALPRO"),
187            SecurityType::Crypto => derive_crypto_venue(contract),
188            SecurityType::Stock => Venue::from("SMART"),
189            SecurityType::Option | SecurityType::FuturesOption => {
190                if !contract.exchange.as_str().is_empty() && contract.exchange.as_str() != "SMART" {
191                    Venue::from(contract.exchange.as_str())
192                } else {
193                    Venue::from("SMART")
194                }
195            }
196            SecurityType::CFD => Venue::from("IBCFD"),
197            SecurityType::Commodity => Venue::from("IBCMDTY"),
198            SecurityType::Bond => Venue::from("SMART"),
199            _ => Venue::from("SMART"),
200        }
201    });
202
203    let symbol = match contract.security_type {
204        SecurityType::Stock => {
205            // STK: Use localSymbol, keeping a share-class space (BRK B) unless configured to
206            // use a hyphen (BRK-B); fallback to symbol
207            let symbol_str = if contract.local_symbol.is_empty() {
208                contract.symbol.as_str().to_string()
209            } else if share_class_space {
210                contract.local_symbol.as_str().to_string()
211            } else {
212                contract.local_symbol.as_str().replace(' ', "-")
213            };
214
215            NautilusSymbol::from(symbol_str.as_str())
216        }
217        SecurityType::Index => {
218            // IND: Prefix with ^
219            let base = if contract.local_symbol.is_empty() {
220                contract.symbol.as_str()
221            } else {
222                contract.local_symbol.as_str()
223            };
224
225            NautilusSymbol::from(format!("^{base}").as_str())
226        }
227        SecurityType::Option => {
228            // OPT: Preserve OCC 6-character root padding when present.
229            let symbol_str = if contract.local_symbol.is_empty() {
230                format!(
231                    "{} {} {} {}",
232                    contract.right.map_or("", |right| right.as_str()),
233                    contract.trading_class.as_str(),
234                    contract.last_trade_date_or_contract_month.as_str(),
235                    format_option_strike(contract.strike),
236                )
237            } else {
238                normalize_option_symbol(contract.local_symbol.as_str())
239            };
240
241            NautilusSymbol::from(symbol_str.as_str())
242        }
243        SecurityType::ForexPair | SecurityType::Crypto => {
244            // CASH/CRYPTO: Replace dots with slashes (e.g., "EUR.USD" -> "EUR/USD")
245            let symbol_str = if contract.local_symbol.is_empty() {
246                format!(
247                    "{}/{}",
248                    contract.symbol.as_str(),
249                    contract.currency.as_str()
250                )
251            } else {
252                contract.local_symbol.as_str().replace('.', "/")
253            };
254
255            NautilusSymbol::from(symbol_str.as_str())
256        }
257        SecurityType::Future => {
258            if futures_year_digits == FuturesYearDigits::Two {
259                match futures_symbol_from_contract(contract, futures_year_digits) {
260                    Ok(symbol) => {
261                        return InstrumentId::new(NautilusSymbol::from(symbol), venue);
262                    }
263                    Err(e) => tracing::warn!(
264                        "Falling back to legacy futures symbol for local symbol '{}': {e}",
265                        contract.local_symbol
266                    ),
267                }
268            }
269
270            // FUT: Use localSymbol if available; else symbol + trading_class + expiry (e.g. ESTX50 FESX 20240315).
271            if contract.local_symbol.is_empty() {
272                if !contract.trading_class.is_empty()
273                    && !contract.last_trade_date_or_contract_month.is_empty()
274                {
275                    let symbol_str = format!(
276                        "{} {} {}",
277                        contract.symbol.as_str(),
278                        contract.trading_class.as_str(),
279                        contract.last_trade_date_or_contract_month.as_str()
280                    );
281                    NautilusSymbol::from(symbol_str.as_str())
282                } else if !contract.last_trade_date_or_contract_month.is_empty() {
283                    let expiry = contract.last_trade_date_or_contract_month.as_str();
284                    let symbol_str = format!("{}{}", contract.symbol.as_str(), expiry);
285                    NautilusSymbol::from(symbol_str.as_str())
286                } else {
287                    NautilusSymbol::from(contract.symbol.as_str())
288                }
289            } else {
290                NautilusSymbol::from(contract.local_symbol.as_str())
291            }
292        }
293        SecurityType::FuturesOption => {
294            if futures_year_digits == FuturesYearDigits::Two {
295                match futures_symbol_from_contract(contract, futures_year_digits) {
296                    Ok(symbol) => {
297                        return InstrumentId::new(NautilusSymbol::from(symbol), venue);
298                    }
299                    Err(e) => tracing::warn!(
300                        "Falling back to legacy futures option symbol for local symbol '{}': {e}",
301                        contract.local_symbol
302                    ),
303                }
304            }
305
306            // FOP: Preserve IB local symbol spacing, matching Python simplified symbology.
307            if contract.local_symbol.is_empty() {
308                // Fallback construction
309                let expiry = contract.last_trade_date_or_contract_month.as_str();
310                let right = contract.right.map_or("P", |right| right.as_str());
311                let strike_str = format!("{}", contract.strike as i64);
312                let symbol_str = format!(
313                    "{}{} {}{}",
314                    contract.symbol.as_str(),
315                    expiry,
316                    right,
317                    strike_str
318                );
319                NautilusSymbol::from(symbol_str.as_str())
320            } else {
321                NautilusSymbol::from(contract.local_symbol.as_str())
322            }
323        }
324        SecurityType::CFD => {
325            // CFD: If localSymbol matches EUR.USD pattern, convert to EUR/USD, else use symbol with spaces as hyphens
326            if !contract.local_symbol.is_empty() && contract.local_symbol.contains('.') {
327                let cash_like = contract.local_symbol.as_str().replace('.', "/");
328                NautilusSymbol::from(cash_like.as_str())
329            } else {
330                let symbol_str = contract.symbol.as_str().replace(' ', "-");
331                NautilusSymbol::from(symbol_str.as_str())
332            }
333        }
334        SecurityType::Commodity => {
335            // CMDTY: Replace spaces with hyphens
336            let symbol_str = contract.symbol.as_str().replace(' ', "-");
337            NautilusSymbol::from(symbol_str.as_str())
338        }
339        SecurityType::Bond => {
340            // BOND: Use localSymbol or symbol
341            let symbol_str = if contract.local_symbol.is_empty() {
342                contract.symbol.as_str()
343            } else {
344                contract.local_symbol.as_str()
345            };
346
347            NautilusSymbol::from(symbol_str)
348        }
349        _ => {
350            // Default: use localSymbol or symbol
351            let symbol_str = if contract.local_symbol.is_empty() {
352                contract.symbol.as_str()
353            } else {
354                contract.local_symbol.as_str()
355            };
356
357            NautilusSymbol::from(symbol_str)
358        }
359    };
360
361    InstrumentId::new(symbol, venue)
362}
363
364/// Convert an IB Contract to an InstrumentId using raw symbology.
365///
366/// This implements IB_RAW symbology: preserves IB raw format with security type suffix.
367/// For example:
368/// - "AAPL=STK.SMART"
369/// - "EUR.USD=CASH.IDEALPRO"
370/// - "ESM23=FUT.GLOBEX"
371fn contract_to_instrument_id_raw(
372    contract: &Contract,
373    venue: Option<Venue>,
374    futures_year_digits: FuturesYearDigits,
375) -> InstrumentId {
376    let venue = venue.unwrap_or_else(|| match contract.security_type {
377        SecurityType::ForexPair => Venue::from("IDEALPRO"),
378        SecurityType::Crypto => derive_crypto_venue(contract),
379        SecurityType::Stock => Venue::from("SMART"),
380        SecurityType::Option => Venue::from("SMART"),
381        SecurityType::FuturesOption => Venue::from("SMART"),
382        SecurityType::Future => Venue::from("GLOBEX"),
383        SecurityType::Index => Venue::from("SMART"),
384        SecurityType::CFD => Venue::from("IBCFD"),
385        SecurityType::Commodity => Venue::from("IBCMDTY"),
386        SecurityType::Bond => Venue::from("SMART"),
387        _ => Venue::from("SMART"),
388    });
389
390    let local_symbol = if futures_year_digits == FuturesYearDigits::Two
391        && matches!(
392            contract.security_type,
393            SecurityType::Future | SecurityType::FuturesOption
394        ) {
395        match futures_symbol_from_contract(contract, futures_year_digits) {
396            Ok(symbol) => symbol,
397            Err(e) => {
398                tracing::warn!(
399                    "Falling back to legacy futures symbol for local symbol '{}': {e}",
400                    contract.local_symbol
401                );
402                legacy_raw_local_symbol(contract)
403            }
404        }
405    } else if contract.local_symbol.is_empty() {
406        contract.symbol.as_str().to_string()
407    } else {
408        contract.local_symbol.as_str().to_string()
409    };
410
411    let sec_type_str = IbSecurityType::try_from(&contract.security_type).map_or_else(
412        |_| "OTHER".to_string(),
413        |security_type| security_type.to_string(),
414    );
415
416    let symbol_str = format!("{local_symbol}={sec_type_str}");
417    let symbol = NautilusSymbol::from(symbol_str.as_str());
418    InstrumentId::new(symbol, venue)
419}
420
421fn legacy_raw_local_symbol(contract: &Contract) -> String {
422    if contract.local_symbol.is_empty() {
423        contract.symbol.as_str().to_string()
424    } else {
425        contract.local_symbol.as_str().to_string()
426    }
427}
428
429/// Venue to IB exchange mappings.
430/// Maps MIC venue codes to lists of IB exchange codes used by Interactive Brokers.
431pub static VENUE_MEMBERS: LazyLock<HashMap<&'static str, Vec<&'static str>>> =
432    LazyLock::new(|| {
433        let mut map = HashMap::new();
434        // ICE Endex
435        map.insert("NDEX", vec!["ENDEX"]);
436        // CME Group Exchanges
437        map.insert("XCME", vec!["CME"]);
438        map.insert("XCEC", vec!["CME"]);
439        map.insert("XFXS", vec!["CME"]);
440        // Chicago Board of Trade Segments
441        map.insert("XCBT", vec!["CBOT"]);
442        map.insert("CBCM", vec!["CBOT"]);
443        // New York Mercantile Exchange Segments
444        map.insert("XNYM", vec!["NYMEX"]);
445        map.insert("NYUM", vec!["NYMEX"]);
446        // ICE Futures US (formerly NYBOT)
447        map.insert("IFUS", vec!["NYBOT"]);
448        // GLBX, Name used by databento
449        map.insert("GLBX", vec!["CBOT", "CME", "NYBOT", "NYMEX"]);
450        // US Major Exchanges & Index Venues
451        map.insert("XNAS", vec!["NASDAQ"]);
452        map.insert("XNYS", vec!["NYSE"]);
453        map.insert("ARCX", vec!["ARCA"]);
454        map.insert("BATS", vec!["BATS"]);
455        map.insert("IEXG", vec!["IEX"]);
456        map.insert("XCBO", vec!["CBOE"]);
457        map.insert("XCBF", vec!["CFE"]);
458        // Canadian Exchanges
459        map.insert("XTSE", vec!["TSX"]);
460        // ICE Europe Exchanges
461        map.insert("IFEU", vec!["ICEEU", "ICEEUSOFT", "IPE"]);
462        // European Exchanges
463        map.insert("XLON", vec!["LSE"]);
464        map.insert("XPAR", vec!["SBF"]);
465        map.insert("XETR", vec!["IBIS"]);
466        map.insert("XEUR", vec!["DTB", "EUREX", "SOFFEX"]);
467        map.insert("XAMS", vec!["AEB"]);
468        map.insert("XBRU", vec!["EBS"]);
469        map.insert("XBRD", vec!["BELFOX"]);
470        map.insert("XLIS", vec!["BVLP"]);
471        map.insert("XDUB", vec!["IRE"]);
472        map.insert("XOSL", vec!["OSL"]);
473        map.insert("XSWX", vec!["EBS", "SIX", "SWX"]);
474        map.insert("XSVX", vec!["VRTX"]);
475        map.insert("XMIL", vec!["BIT", "BVME", "IDEM"]);
476        map.insert("XMAD", vec!["MDRD", "BME"]);
477        map.insert("DXEX", vec!["BATEEN"]);
478        map.insert("XWBO", vec!["WBAG"]);
479        map.insert("XBUD", vec!["BUX"]);
480        map.insert("XPRA", vec!["PRA"]);
481        map.insert("XWAR", vec!["WSE"]);
482        map.insert("XIST", vec!["ISE"]);
483        // Nasdaq Nordic Exchanges
484        map.insert("XSTO", vec!["SFB"]);
485        map.insert("XCSE", vec!["KFB"]);
486        map.insert("XHEL", vec!["HMB"]);
487        map.insert("XICE", vec!["ISB"]);
488        // Asia-Pacific Exchanges
489        map.insert("XASX", vec!["ASX"]);
490        map.insert("XHKG", vec!["SEHK"]);
491        map.insert("XHKF", vec!["HKFE"]);
492        map.insert("XSES", vec!["SGX"]);
493        map.insert("XOSE", vec!["OSE.JPN"]);
494        map.insert("XTKS", vec!["TSEJ", "TSE.JPN"]);
495        map.insert("XKRX", vec!["KSE", "KRX"]);
496        map.insert("XTAI", vec!["TASE", "TWSE"]);
497        map.insert("XSHG", vec!["SEHKNTL", "SSE"]);
498        map.insert("XSHE", vec!["SEHKSZSE"]);
499        map.insert("XNSE", vec!["NSE"]);
500        map.insert("XBOM", vec!["BSE"]);
501        // Other Derivatives Exchanges
502        map.insert("XSFE", vec!["SNFE"]);
503        map.insert("XMEX", vec!["MEXDER"]);
504        // African, Middle Eastern, South American Exchanges
505        map.insert("XJSE", vec!["JSE"]);
506        map.insert("XBOG", vec!["BVC"]);
507        map.insert("XTAE", vec!["TASE"]);
508        map.insert("BVMF", vec!["BVMF"]);
509        map
510    });
511
512/// Returns `true` if the contract is a cryptocurrency contract.
513///
514/// Centralizes the crypto check used to gate crypto-specific request handling
515/// (e.g. the `AGGTRADES` `whatToShow` rule - see
516/// [`crate::data::convert::price_type_to_ib_what_to_show_for_security`]).
517#[must_use]
518pub fn is_crypto_contract(contract: &Contract) -> bool {
519    matches!(contract.security_type, SecurityType::Crypto)
520}
521
522/// Derives the venue for a crypto contract.
523///
524/// IB routes crypto to multiple venues; both PAXOS and ZEROHASH are live (which one
525/// applies depends on the account/region). Uses the contract's actual exchange when
526/// set (e.g. ZEROHASH or PAXOS), falling back to PAXOS when it is unspecified.
527#[must_use]
528pub fn derive_crypto_venue(contract: &Contract) -> Venue {
529    if !contract.exchange.as_str().is_empty() && contract.exchange.as_str() != "SMART" {
530        Venue::from(contract.exchange.as_str())
531    } else {
532        Venue::from("PAXOS")
533    }
534}
535
536#[must_use]
537pub fn possible_exchanges_for_venue(venue: &str) -> Vec<String> {
538    if venue == "OPRA" {
539        return vec!["SMART".to_string()];
540    }
541
542    if let Some(exchanges) = VENUE_MEMBERS.get(venue) {
543        return exchanges
544            .iter()
545            .map(|exchange| (*exchange).to_string())
546            .collect();
547    }
548
549    vec![venue.to_string()]
550}
551
552/// Venue lists for different asset classes
553const VENUES_CASH: &[&str] = &["IDEALPRO"];
554// IB routes crypto to both PAXOS and ZEROHASH (which one applies depends on the
555// account/region); accept both.
556const VENUES_CRYPTO: &[&str] = &["PAXOS", "ZEROHASH"];
557const VENUES_OPT: &[&str] = &["SMART", "EUREX"];
558const VENUES_FUT: &[&str] = &[
559    "BELFOX",
560    "GLOBEX",
561    "CBOT",
562    "CFE",
563    "CME",
564    "COMEX",
565    "CBOE",
566    "DTB",
567    "EUREX",
568    "HKFE",
569    "ICE",
570    "ICEEU",
571    "ICEEUSOFT",
572    "IDEM",
573    "IPE",
574    "KCBT",
575    "MEXDER",
576    "MGE",
577    "NYBOT",
578    "NYMEX",
579    "OSE.JPN",
580    "SNFE",
581    "SOFFEX",
582    "VRTX",
583    "CMECRYPTO",
584    "NYMEXMETALS",
585    "NYMEXNG",
586    "NYMEXENERGY",
587    "CMEPRECIOUS",
588    "CMECURRENCY",
589    "CMEINDEX",
590    "CMEWEATHER",
591    "CMEINTEREST",
592    "CMEFLOOR",
593    "CBOTFLOOR",
594    "NYMEXFLOOR",
595    "NYBOTFLOOR",
596    "CFEFLOOR",
597    "CMEOPTIONS",
598    "CBOTOPTIONS",
599    "NYMEXOPTIONS",
600    "NYBOTOPTIONS",
601    "ECBOT",
602];
603const VENUES_CFD: &[&str] = &["IBCFD", "SMART"];
604const VENUES_CMDTY: &[&str] = &["IBCMDTY"];
605
606fn venue_matches(venue_str: &str, venues: &[&str]) -> bool {
607    venues.contains(&venue_str)
608        || VENUE_MEMBERS
609            .get(venue_str)
610            .is_some_and(|exchanges| exchanges.iter().any(|exchange| venues.contains(exchange)))
611}
612
613fn is_option_venue(venue: &str) -> bool {
614    venue == "OPRA" || venue_matches(venue, VENUES_OPT)
615}
616
617fn is_canonical_occ_option_symbol(symbol: &str) -> bool {
618    let bytes = symbol.as_bytes();
619    if bytes.len() != 21 || !symbol.is_ascii() {
620        return false;
621    }
622
623    let root = &bytes[..6];
624    let root_len = root.iter().position(|byte| *byte == b' ').unwrap_or(6);
625
626    root_len > 0
627        && root[..root_len].iter().all(u8::is_ascii_graphic)
628        && root[root_len..].iter().all(|byte| *byte == b' ')
629        && bytes[6..12].iter().all(u8::is_ascii_digit)
630        && matches!(bytes[12], b'C' | b'P')
631        && bytes[13..].iter().all(u8::is_ascii_digit)
632}
633
634/// Futures month codes mapping (F=Jan, G=Feb, H=Mar, J=Apr, K=May, M=Jun, N=Jul, Q=Aug, U=Sep, V=Oct, X=Nov, Z=Dec)
635/// This constant is kept for potential future use in more complex parsing scenarios.
636#[allow(dead_code)]
637const FUTURES_MONTH_CODES: &[(char, &str)] = &[
638    ('F', "01"),
639    ('G', "02"),
640    ('H', "03"),
641    ('J', "04"),
642    ('K', "05"),
643    ('M', "06"),
644    ('N', "07"),
645    ('Q', "08"),
646    ('U', "09"),
647    ('V', "10"),
648    ('X', "11"),
649    ('Z', "12"),
650];
651
652/// Returns the venue `symbol_to_mic_venue` maps the contract's symbol to, by prefix match.
653#[must_use]
654pub fn symbol_mic_venue(
655    contract: &Contract,
656    symbol_to_mic_venue: &std::collections::HashMap<String, String>,
657) -> Option<String> {
658    let symbol = contract.symbol.as_str();
659    symbol_to_mic_venue
660        .iter()
661        .find(|(symbol_prefix, _)| symbol.starts_with(symbol_prefix.as_str()))
662        .map(|(_, symbol_venue)| symbol_venue.clone())
663}
664
665/// Determine venue from contract using provider configuration.
666///
667/// This implements the same logic as Python's `determine_venue_from_contract`:
668/// 1. Check symbol-specific venue mapping first (prefix matching)
669/// 2. Use VENUE_MEMBERS mapping if convert_exchange_to_mic_venue is enabled
670/// 3. Fall back to exchange
671pub fn determine_venue_from_contract(
672    contract: &Contract,
673    symbol_to_mic_venue: &std::collections::HashMap<String, String>,
674    convert_exchange_to_mic_venue: bool,
675    valid_exchanges: Option<&str>,
676) -> String {
677    if matches!(contract.security_type, SecurityType::CFD) {
678        return "IBCFD".to_string();
679    }
680
681    if matches!(contract.security_type, SecurityType::Commodity) {
682        return "IBCMDTY".to_string();
683    }
684
685    if let Some(venue) = symbol_mic_venue(contract, symbol_to_mic_venue) {
686        return venue;
687    }
688
689    // Use the exchange from the contract (primaryExchange if exchange is SMART)
690    let mut exchange = if contract.exchange.as_str() == "SMART"
691        && !contract.primary_exchange.as_str().is_empty()
692        && contract.primary_exchange.as_str() != "SMART"
693    {
694        contract.primary_exchange.as_str().to_string()
695    } else {
696        contract.exchange.as_str().to_string()
697    };
698
699    if exchange == "SMART"
700        && let Some(valid_exchanges) = valid_exchanges
701    {
702        let parts: Vec<&str> = valid_exchanges
703            .split(',')
704            .map(str::trim)
705            .filter(|part| !part.is_empty())
706            .collect();
707
708        if let Some(chosen) = parts.iter().find(|part| **part != "SMART") {
709            exchange = (*chosen).to_string();
710        } else if let Some(first) = parts.first() {
711            exchange = (*first).to_string();
712        }
713    }
714
715    if convert_exchange_to_mic_venue && let Some(venue) = exchange_to_mic_venue(&exchange) {
716        return venue;
717    }
718
719    exchange
720}
721
722/// Convert an Interactive Brokers exchange code to a MIC venue when known.
723#[must_use]
724pub fn exchange_to_mic_venue(exchange: &str) -> Option<String> {
725    VENUE_MEMBERS.iter().find_map(|(venue_member, exchanges)| {
726        exchanges
727            .contains(&exchange)
728            .then(|| (*venue_member).to_string())
729    })
730}
731
732/// Convert a NautilusTrader `InstrumentId` to an Interactive Brokers `Contract`.
733///
734/// This function handles all instrument types:
735/// - Stocks (STK)
736/// - Options (OPT)
737/// - Futures (FUT, CONTFUT)
738/// - Futures Options (FOP)
739/// - Forex (CASH)
740/// - Crypto (CRYPTO)
741/// - CFDs (CFD)
742/// - Commodities (CMDTY)
743/// - Indices (IND)
744/// - Option Spreads (BAG) - requires contract details map
745fn instrument_id_to_contract(
746    instrument_id: InstrumentId,
747    exchange: Option<&str>,
748    futures_year_digits: FuturesYearDigits,
749    reference_year: i32,
750    currency: Option<&str>,
751) -> Contract {
752    let venue_str = instrument_id.venue.to_string();
753
754    let derived_exchange = if venue_str == "OPRA" {
755        "SMART"
756    } else {
757        VENUE_MEMBERS
758            .get(venue_str.as_str())
759            .and_then(|exchanges| exchanges.first().copied())
760            .or_else(|| {
761                if venue_matches(venue_str.as_str(), VENUES_CASH)
762                    || venue_matches(venue_str.as_str(), VENUES_CRYPTO)
763                    || venue_matches(venue_str.as_str(), VENUES_OPT)
764                    || venue_matches(venue_str.as_str(), VENUES_FUT)
765                {
766                    Some(venue_str.as_str())
767                } else {
768                    None
769                }
770            })
771            .unwrap_or("SMART")
772    };
773
774    let exchange_str = exchange.unwrap_or(derived_exchange);
775    let symbol_str = instrument_id.symbol.as_str();
776
777    if let Some(contract) = instrument_id_to_ib_contract_raw(
778        &instrument_id,
779        exchange,
780        futures_year_digits,
781        reference_year,
782        currency,
783    ) {
784        return contract;
785    }
786
787    // Handle spreads (BAG contracts) - requires contract details, so we skip for now
788    // This should be handled by the instrument provider which has access to contract details
789    // if symbol_str.contains(":") {
790    //     return create_bag_contract(instrument_id, exchange_str);
791    // }
792
793    // Handle Forex (CASH)
794    if venue_matches(venue_str.as_str(), VENUES_CASH)
795        && let Some(captures) = parse_cash_symbol(symbol_str)
796    {
797        return Contract {
798            symbol: Symbol::from(&captures.base),
799            security_type: SecurityType::ForexPair,
800            exchange: Exchange::from(exchange_str),
801            currency: Currency::from(&captures.quote),
802            local_symbol: format!("{}.{}", captures.base, captures.quote),
803            ..Default::default()
804        };
805    }
806
807    // Handle Crypto
808    if venue_matches(venue_str.as_str(), VENUES_CRYPTO)
809        && let Some(captures) = parse_crypto_symbol(symbol_str)
810    {
811        return Contract {
812            symbol: Symbol::from(&captures.base),
813            security_type: SecurityType::Crypto,
814            exchange: Exchange::from(exchange_str),
815            currency: Currency::from(&captures.quote),
816            local_symbol: format!("{}.{}", captures.base, captures.quote),
817            ..Default::default()
818        };
819    }
820
821    // Handle Options (OPT)
822    if is_option_venue(venue_str.as_str()) {
823        if venue_str == "OPRA" {
824            return Contract {
825                security_type: SecurityType::Option,
826                exchange: Exchange::from(exchange_str),
827                currency: Currency::from("USD"),
828                local_symbol: symbol_str.to_string(),
829                ..Default::default()
830            };
831        }
832
833        if let Some(opt) = parse_option_symbol(symbol_str) {
834            return Contract {
835                symbol: Symbol::from(&opt.symbol),
836                security_type: SecurityType::Option,
837                exchange: Exchange::from(exchange_str),
838                currency: Currency::from("USD"), // Will be resolved from contract details
839                local_symbol: opt.local_symbol,
840                last_trade_date_or_contract_month: opt.expiry,
841                strike: opt.strike_value,
842                right: Some(opt.right),
843                ..Default::default()
844            };
845        }
846
847        if let Some(opt) = parse_named_option_symbol(symbol_str) {
848            return Contract {
849                symbol: Symbol::from(&opt.trading_class),
850                security_type: SecurityType::Option,
851                exchange: Exchange::from(exchange_str),
852                currency: Currency::from("USD"),
853                trading_class: opt.trading_class,
854                last_trade_date_or_contract_month: opt.expiry,
855                strike: opt.strike_value,
856                right: Some(opt.right),
857                ..Default::default()
858            };
859        }
860    }
861
862    // Handle Futures and Futures Options
863    if venue_matches(venue_str.as_str(), VENUES_FUT) {
864        if let Some(fut) = parse_named_futures_symbol(symbol_str) {
865            return Contract {
866                symbol: Symbol::from(&fut.underlying),
867                security_type: SecurityType::Future,
868                exchange: Exchange::from(exchange_str),
869                currency: Currency::from("USD"),
870                trading_class: fut.trading_class,
871                last_trade_date_or_contract_month: fut.expiry,
872                ..Default::default()
873            };
874        }
875
876        // Check for continuous futures (underlying only, no expiry)
877        // IB uses FUT with no expiry date to represent continuous futures
878        if is_futures_underlying(symbol_str) {
879            return Contract {
880                symbol: Symbol::from(symbol_str),
881                security_type: SecurityType::ContinuousFuture,
882                exchange: Exchange::from(exchange_str),
883                currency: Currency::from("USD"), // Will be resolved from contract details
884                ..Default::default()
885            };
886        }
887
888        if futures_year_digits == FuturesYearDigits::Two
889            && let Some(contract) = futures_contract_from_symbol(
890                symbol_str,
891                SecurityType::FuturesOption,
892                exchange_str,
893                reference_year,
894                currency,
895            )
896        {
897            return contract;
898        }
899
900        // Check for Futures Options (FOP)
901        if validate_futures_option_symbol(symbol_str).is_some() {
902            return Contract {
903                security_type: SecurityType::FuturesOption,
904                exchange: Exchange::from(exchange_str),
905                currency: Currency::from("USD"),
906                local_symbol: symbol_str.to_string(),
907                ..Default::default()
908            };
909        }
910
911        if futures_year_digits == FuturesYearDigits::Two
912            && let Some(contract) = futures_contract_from_symbol(
913                symbol_str,
914                SecurityType::Future,
915                exchange_str,
916                reference_year,
917                currency,
918            )
919        {
920            return contract;
921        }
922
923        // Check for regular Futures (FUT)
924        if parse_futures_month_and_year(symbol_str).is_some() {
925            return Contract {
926                security_type: SecurityType::Future,
927                exchange: Exchange::from(exchange_str),
928                currency: Currency::from("USD"),
929                local_symbol: symbol_str.to_string(),
930                ..Default::default()
931            };
932        }
933    }
934
935    // Handle CFDs
936    if venue_matches(venue_str.as_str(), VENUES_CFD) {
937        if let Some(captures) =
938            parse_cash_symbol(symbol_str).or_else(|| parse_cfd_cash_symbol(symbol_str))
939        {
940            return Contract {
941                symbol: Symbol::from(&captures.base),
942                security_type: SecurityType::CFD,
943                exchange: Exchange::from("SMART"),
944                currency: Currency::from(&captures.quote),
945                local_symbol: format!("{}.{}", captures.base, captures.quote),
946                ..Default::default()
947            };
948        } else {
949            // CFD with space-separated symbol
950            let symbol_clean = symbol_str.replace('-', " ");
951
952            return Contract {
953                symbol: Symbol::from(&symbol_clean),
954                security_type: SecurityType::CFD,
955                exchange: Exchange::from("SMART"),
956                currency: Currency::from(""),
957                ..Default::default()
958            };
959        }
960    }
961
962    // Handle Commodities
963    if VENUES_CMDTY.contains(&venue_str.as_str()) {
964        let symbol_clean = symbol_str.replace('-', " ");
965
966        return Contract {
967            symbol: Symbol::from(&symbol_clean),
968            security_type: SecurityType::Commodity,
969            exchange: Exchange::from("SMART"),
970            currency: Currency::from(""),
971            ..Default::default()
972        };
973    }
974
975    // Handle Indices (symbols starting with ^)
976    if let Some(local_symbol) = symbol_str.strip_prefix('^') {
977        return Contract {
978            symbol: Symbol::from(local_symbol),
979            security_type: SecurityType::Index,
980            exchange: Exchange::from(exchange_str),
981            currency: Currency::from("USD"),
982            local_symbol: local_symbol.into(),
983            ..Default::default()
984        };
985    }
986
987    // Default to Stock (STK)
988    let symbol_clean = symbol_str.replace('-', " ");
989
990    Contract {
991        symbol: Symbol::from(&symbol_clean),
992        security_type: SecurityType::Stock,
993        exchange: Exchange::from("SMART"),
994        currency: Currency::from(""), // Will be resolved from contract details
995        primary_exchange: Exchange::from(exchange_str),
996        ..Default::default()
997    }
998}
999
1000fn instrument_id_to_ib_contract_raw(
1001    instrument_id: &InstrumentId,
1002    exchange: Option<&str>,
1003    futures_year_digits: FuturesYearDigits,
1004    reference_year: i32,
1005    currency: Option<&str>,
1006) -> Option<Contract> {
1007    let (local_symbol, sec_type_code) = instrument_id.symbol.as_str().rsplit_once('=')?;
1008
1009    let venue_exchange = instrument_id.venue.as_str().replace('/', ".");
1010    let security_type = IbSecurityType::from_str(sec_type_code)
1011        .ok()
1012        .map(IbSecurityType::ibapi_security_type)?;
1013
1014    let default_exchange =
1015        if security_type == SecurityType::Option && instrument_id.venue.as_str() == "OPRA" {
1016            "SMART"
1017        } else {
1018            venue_exchange.as_str()
1019        };
1020
1021    let exchange_str = exchange.unwrap_or(default_exchange);
1022
1023    if futures_year_digits == FuturesYearDigits::Two
1024        && matches!(
1025            security_type,
1026            SecurityType::Future | SecurityType::FuturesOption
1027        )
1028        && let Some(contract) = futures_contract_from_symbol(
1029            local_symbol,
1030            security_type.clone(),
1031            exchange_str,
1032            reference_year,
1033            currency,
1034        )
1035    {
1036        return Some(contract);
1037    }
1038
1039    let contract = match security_type {
1040        SecurityType::Stock => Contract {
1041            security_type,
1042            exchange: Exchange::from("SMART"),
1043            primary_exchange: Exchange::from(exchange_str),
1044            local_symbol: local_symbol.to_string(),
1045            ..Default::default()
1046        },
1047        SecurityType::CFD | SecurityType::Commodity => Contract {
1048            security_type,
1049            exchange: Exchange::from("SMART"),
1050            currency: Currency::from(""),
1051            local_symbol: local_symbol.to_string(),
1052            ..Default::default()
1053        },
1054        SecurityType::Index => Contract {
1055            security_type,
1056            exchange: Exchange::from(exchange_str),
1057            local_symbol: local_symbol.to_string(),
1058            ..Default::default()
1059        },
1060        _ => Contract {
1061            security_type,
1062            exchange: Exchange::from(exchange_str),
1063            local_symbol: local_symbol.to_string(),
1064            ..Default::default()
1065        },
1066    };
1067
1068    Some(contract)
1069}
1070
1071/// Currency pair captures
1072struct CurrencyPair {
1073    base: String,
1074    quote: String,
1075}
1076
1077/// Parse cash/forex symbol like "EUR/USD"
1078fn parse_cash_symbol(symbol: &str) -> Option<CurrencyPair> {
1079    if let Some((base, quote)) = symbol.split_once('/')
1080        && base.len() == 3
1081        && quote.len() == 3
1082    {
1083        return Some(CurrencyPair {
1084            base: base.to_string(),
1085            quote: quote.to_string(),
1086        });
1087    }
1088
1089    None
1090}
1091
1092/// Parse crypto symbol like "BTC/USD".
1093fn parse_crypto_symbol(symbol: &str) -> Option<CurrencyPair> {
1094    if let Some((base, quote)) = symbol.split_once('/')
1095        && !base.is_empty()
1096        && base.chars().all(|ch| ch.is_ascii_uppercase())
1097        && quote.len() == 3
1098        && quote.chars().all(|ch| ch.is_ascii_uppercase())
1099    {
1100        return Some(CurrencyPair {
1101            base: base.to_string(),
1102            quote: quote.to_string(),
1103        });
1104    }
1105
1106    None
1107}
1108
1109/// Parse CFD cash symbol like "EUR.USD"
1110fn parse_cfd_cash_symbol(symbol: &str) -> Option<CurrencyPair> {
1111    if let Some((base, quote)) = symbol.split_once('.')
1112        && base.len() == 3
1113        && quote.len() == 3
1114    {
1115        return Some(CurrencyPair {
1116            base: base.to_string(),
1117            quote: quote.to_string(),
1118        });
1119    }
1120
1121    None
1122}
1123
1124/// Option symbol captures
1125struct OptionSymbol {
1126    symbol: String,
1127    expiry: String,
1128    right: OptionRight,
1129    local_symbol: String,
1130    strike_value: f64,
1131}
1132
1133/// Parse option symbol like "AAPL230120C00150000" (6-char symbol, 6-char expiry YYMMDD, 1-char right, 8-char strike)
1134fn parse_option_symbol(symbol: &str) -> Option<OptionSymbol> {
1135    // Pattern: SYMBOL + YYMMDD + C/P + STRIKE (8 digits, could have decimal)
1136    // Minimum: 6 (symbol) + 6 (date) + 1 (right) + 8 (strike) = 21 chars
1137    if symbol.len() < 21 {
1138        return None;
1139    }
1140
1141    // Try to match: 6-char symbol, 6-char date, 1-char right (C/P), remainder is strike
1142    let symbol_part = symbol[..6.min(symbol.len())].trim();
1143    let remaining = &symbol[6.min(symbol.len())..];
1144
1145    if remaining.len() < 15 {
1146        return None;
1147    }
1148
1149    let expiry = &remaining[..6];
1150    let right_char = remaining.chars().nth(6)?;
1151    let right = IbOptionRight::from_str(&right_char.to_string()).ok()?;
1152
1153    let strike_str = &remaining[7..];
1154    if strike_str.len() < 8 {
1155        return None;
1156    }
1157
1158    // Strike is typically 8 digits with possible decimal
1159    let strike_value = if strike_str.contains('.') {
1160        strike_str.parse().ok()?
1161    } else {
1162        // 8-digit integer strike, divide by 1000 for typical option strikes
1163        let strike_int: i32 = strike_str.parse().ok()?;
1164        strike_int as f64 / 1000.0
1165    };
1166
1167    Some(OptionSymbol {
1168        symbol: symbol_part.to_string(),
1169        expiry: expiry.to_string(),
1170        right: ib_option_right_to_option_right(right),
1171        local_symbol: symbol.to_string(),
1172        strike_value,
1173    })
1174}
1175
1176/// Named option symbol captures for formats like "C OESX 20260213 4775".
1177struct NamedOptionSymbol {
1178    trading_class: String,
1179    expiry: String,
1180    right: OptionRight,
1181    strike_value: f64,
1182}
1183
1184/// Named futures symbol captures for formats like "ESTX50 FESX 20240315".
1185struct NamedFuturesSymbol {
1186    underlying: String,
1187    trading_class: String,
1188    expiry: String,
1189}
1190
1191fn parse_named_futures_symbol(symbol: &str) -> Option<NamedFuturesSymbol> {
1192    let parts: Vec<&str> = symbol.split_whitespace().collect();
1193    if parts.len() != 3 {
1194        return None;
1195    }
1196
1197    let expiry = parts[2];
1198    if expiry.len() != 8 || !expiry.chars().all(|c| c.is_ascii_digit()) {
1199        return None;
1200    }
1201
1202    Some(NamedFuturesSymbol {
1203        underlying: parts[0].to_string(),
1204        trading_class: parts[1].to_string(),
1205        expiry: expiry.to_string(),
1206    })
1207}
1208
1209fn parse_named_option_symbol(symbol: &str) -> Option<NamedOptionSymbol> {
1210    let parts: Vec<&str> = symbol.split_whitespace().collect();
1211    if !(parts.len() == 4 || parts.len() == 5) {
1212        return None;
1213    }
1214
1215    let right = IbOptionRight::from_str(parts[0]).ok()?;
1216
1217    let expiry = parts[2];
1218    if expiry.len() != 8 || !expiry.chars().all(|c| c.is_ascii_digit()) {
1219        return None;
1220    }
1221
1222    Some(NamedOptionSymbol {
1223        trading_class: parts[1].to_string(),
1224        expiry: expiry.to_string(),
1225        right: ib_option_right_to_option_right(right),
1226        strike_value: parts[3].parse::<f64>().ok()?,
1227    })
1228}
1229
1230fn normalize_option_symbol(local_symbol: &str) -> String {
1231    if local_symbol.len() >= 15 {
1232        let (root, suffix) = local_symbol.split_at(local_symbol.len() - 15);
1233        let is_occ_suffix = suffix[..6].chars().all(|c| c.is_ascii_digit())
1234            && matches!(suffix.chars().nth(6), Some('C' | 'P'))
1235            && suffix[7..].chars().all(|c| c.is_ascii_digit());
1236
1237        if !root.is_empty() && root.len() <= 6 && is_occ_suffix {
1238            return format!("{:<6}{}", root.trim_end(), suffix);
1239        }
1240    }
1241
1242    local_symbol.to_string()
1243}
1244
1245fn format_option_strike(strike: f64) -> String {
1246    if strike.fract() == 0.0 {
1247        format!("{strike:.0}")
1248    } else {
1249        format!("{strike}")
1250    }
1251}
1252
1253fn futures_symbol_from_contract(
1254    contract: &Contract,
1255    futures_year_digits: FuturesYearDigits,
1256) -> anyhow::Result<String> {
1257    let futures_year_digits = u8::from(futures_year_digits);
1258    let expiry = contract.last_trade_date_or_contract_month.as_str();
1259    let year = expiry
1260        .get(..4)
1261        .filter(|value| value.bytes().all(|b| b.is_ascii_digit()))
1262        .and_then(|value| value.parse::<i32>().ok())
1263        .ok_or_else(|| anyhow::anyhow!("Invalid futures contract month '{expiry}'"))?;
1264
1265    let (futures_symbol, suffix) = if contract.security_type == SecurityType::FuturesOption {
1266        contract
1267            .local_symbol
1268            .split_once(' ')
1269            .map(|(symbol, suffix)| (symbol, Some(suffix)))
1270            .ok_or_else(|| {
1271                anyhow::anyhow!(
1272                    "Invalid futures option local symbol '{}'",
1273                    contract.local_symbol
1274                )
1275            })?
1276    } else if contract.local_symbol.is_empty() {
1277        let month = expiry
1278            .get(4..6)
1279            .and_then(|value| value.parse::<u8>().ok())
1280            .and_then(futures_month_code)
1281            .ok_or_else(|| anyhow::anyhow!("Invalid futures contract month '{expiry}'"))?;
1282
1283        let formatted =
1284            format_futures_symbol(contract.symbol.as_str(), month, year, futures_year_digits)
1285                .ok_or_else(|| {
1286                    anyhow::anyhow!("Invalid futures year digit count {futures_year_digits}")
1287                })?;
1288
1289        return Ok(formatted);
1290    } else {
1291        (contract.local_symbol.as_str(), None)
1292    };
1293
1294    let parsed = parse_futures_code(futures_symbol)
1295        .ok_or_else(|| anyhow::anyhow!("Invalid futures local symbol '{futures_symbol}'"))?;
1296    let year = resolve_futures_year_from_expiry(parsed.year_digits, year)
1297        .ok_or_else(|| anyhow::anyhow!("Invalid futures year digits '{}'", parsed.year_digits))?;
1298
1299    let formatted =
1300        format_futures_symbol(parsed.root, parsed.month_code, year, futures_year_digits)
1301            .ok_or_else(|| {
1302                anyhow::anyhow!("Invalid futures year digit count {futures_year_digits}")
1303            })?;
1304
1305    Ok(suffix.map_or(formatted.clone(), |suffix| format!("{formatted} {suffix}")))
1306}
1307
1308fn futures_contract_from_symbol(
1309    symbol: &str,
1310    security_type: SecurityType,
1311    exchange: &str,
1312    reference_year: i32,
1313    currency: Option<&str>,
1314) -> Option<Contract> {
1315    let (futures_symbol, suffix) = if security_type == SecurityType::FuturesOption {
1316        validate_futures_option_symbol(symbol)?;
1317        let (futures_symbol, suffix) = symbol.split_once(' ')?;
1318        (futures_symbol, Some(suffix))
1319    } else {
1320        (symbol, None)
1321    };
1322
1323    let parsed = parse_futures_code(futures_symbol)?;
1324    let year = resolve_futures_year(parsed.year_digits, reference_year)?;
1325    let month = futures_month(parsed.month_code)?;
1326
1327    let currency = currency.unwrap_or_else(|| {
1328        log::warn!("Falling back to USD for unresolved IB futures contract {symbol} on {exchange}");
1329        "USD"
1330    });
1331
1332    let native = format_futures_symbol(parsed.root, parsed.month_code, year, 1)?;
1333    let local_symbol = suffix.map_or_else(|| native.clone(), |suffix| format!("{native} {suffix}"));
1334
1335    let mut contract = Contract {
1336        local_symbol,
1337        security_type,
1338        exchange: Exchange::from(exchange),
1339        currency: Currency::from(currency),
1340        ..Default::default()
1341    };
1342
1343    if contract.security_type == SecurityType::Future {
1344        contract.trading_class = parsed.root.to_string();
1345        contract.last_trade_date_or_contract_month = format!("{year:04}{month:02}");
1346    }
1347
1348    Some(contract)
1349}
1350
1351fn is_futures_underlying(symbol: &str) -> bool {
1352    symbol.len() <= 3 && symbol.chars().all(char::is_alphabetic)
1353}
1354
1355fn parse_futures_month_and_year(symbol: &str) -> Option<(usize, char, String)> {
1356    let parsed = parse_futures_code(symbol)?;
1357    Some((
1358        parsed.root.len(),
1359        parsed.month_code,
1360        parsed.year_digits.to_string(),
1361    ))
1362}
1363
1364fn validate_futures_option_symbol(symbol: &str) -> Option<()> {
1365    let (futures_symbol, rest) = symbol.split_once(' ')?;
1366    parse_futures_month_and_year(futures_symbol)?;
1367
1368    let right_char = rest.chars().next()?;
1369    IbOptionRight::from_str(&right_char.to_string()).ok()?;
1370
1371    let strike_str = &rest[1..];
1372    strike_str.parse::<f64>().ok()?;
1373
1374    Some(())
1375}
1376
1377#[cfg(test)]
1378mod tests {
1379    use ibapi::contracts::{Contract, Currency, Exchange, OptionRight, SecurityType, Symbol};
1380    use nautilus_model::identifiers::{
1381        InstrumentId, Symbol as NautilusSymbol, Venue, futures::FuturesYearDigits,
1382    };
1383    use rstest::rstest;
1384
1385    use super::{
1386        Symbology, exchange_to_mic_venue, instrument_id_to_contract, possible_exchanges_for_venue,
1387    };
1388    use crate::config::SymbologyMethod;
1389
1390    #[rstest]
1391    fn test_ib_contract_to_instrument_id_simplified_normalizes_occ_option_root() {
1392        let contract = Contract {
1393            symbol: Symbol::from("SPXW"),
1394            security_type: SecurityType::Option,
1395            exchange: Exchange::from("SMART"),
1396            currency: Currency::from("USD"),
1397            local_symbol: "SPXW260313P06630000".to_string(),
1398            last_trade_date_or_contract_month: "260313".to_string(),
1399            right: Some(OptionRight::Put),
1400            strike: 6630.0,
1401            ..Default::default()
1402        };
1403
1404        let instrument_id = Symbology::new(SymbologyMethod::Simplified)
1405            .instrument_id(&contract, None)
1406            .unwrap();
1407
1408        assert_eq!(
1409            instrument_id,
1410            InstrumentId::from("SPXW  260313P06630000.SMART")
1411        );
1412    }
1413
1414    #[rstest]
1415    fn test_ib_contract_to_instrument_id_simplified_formats_named_option_without_local_symbol() {
1416        let contract = Contract {
1417            symbol: Symbol::from("OESX"),
1418            security_type: SecurityType::Option,
1419            exchange: Exchange::from("EUREX"),
1420            currency: Currency::from("EUR"),
1421            trading_class: "OESX".to_string(),
1422            local_symbol: String::new(),
1423            last_trade_date_or_contract_month: "20260213".to_string(),
1424            right: Some(OptionRight::Call),
1425            strike: 4775.0,
1426            ..Default::default()
1427        };
1428
1429        let instrument_id = Symbology::new(SymbologyMethod::Simplified)
1430            .instrument_id(&contract, None)
1431            .unwrap();
1432
1433        assert_eq!(
1434            instrument_id,
1435            InstrumentId::from("C OESX 20260213 4775.EUREX")
1436        );
1437    }
1438
1439    #[rstest]
1440    fn test_ib_contract_to_instrument_id_simplified_preserves_fop_spacing() {
1441        let contract = Contract {
1442            symbol: Symbol::from("EX2"),
1443            security_type: SecurityType::FuturesOption,
1444            exchange: Exchange::from("NYBOT"),
1445            currency: Currency::from("USD"),
1446            local_symbol: "EX2G3 P4080".to_string(),
1447            ..Default::default()
1448        };
1449
1450        let instrument_id = Symbology::new(SymbologyMethod::Simplified)
1451            .instrument_id(&contract, None)
1452            .unwrap();
1453
1454        assert_eq!(instrument_id, InstrumentId::from("EX2G3 P4080.NYBOT"));
1455    }
1456
1457    #[rstest]
1458    #[case(SecurityType::Future, "ESZ6", "ESZ6.XCME")]
1459    #[case(SecurityType::FuturesOption, "ESZ6 P5000", "ESZ6 P5000.XCME")]
1460    fn test_ib_contract_to_instrument_id_keeps_the_local_symbol_year(
1461        #[case] security_type: SecurityType,
1462        #[case] local_symbol: &str,
1463        #[case] expected: &str,
1464    ) {
1465        let contract = Contract {
1466            symbol: Symbol::from("ES"),
1467            security_type,
1468            exchange: Exchange::from("CME"),
1469            currency: Currency::from("USD"),
1470            local_symbol: local_symbol.to_string(),
1471            last_trade_date_or_contract_month: "202612".to_string(),
1472            ..Default::default()
1473        };
1474
1475        let instrument_id = Symbology::new(SymbologyMethod::Simplified)
1476            .with_futures_year_digits(FuturesYearDigits::One)
1477            .instrument_id(&contract, Some(Venue::from("XCME")))
1478            .unwrap();
1479
1480        assert_eq!(instrument_id, InstrumentId::from(expected));
1481    }
1482
1483    #[rstest]
1484    #[case(SecurityType::Future, "CLF6", "20251219", "CLF6.XNYM")]
1485    #[case(SecurityType::Future, "ESZ6", "20261218", "ESZ6.XNYM")]
1486    #[case(
1487        SecurityType::FuturesOption,
1488        "CLF6 P7000",
1489        "20251216",
1490        "CLF6 P7000.XNYM"
1491    )]
1492    fn test_local_symbol_year_is_not_rewritten_from_last_trade_date(
1493        #[case] security_type: SecurityType,
1494        #[case] local_symbol: &str,
1495        #[case] last_trade_date: &str,
1496        #[case] expected: &str,
1497    ) {
1498        let contract = Contract {
1499            symbol: Symbol::from("CL"),
1500            security_type,
1501            exchange: Exchange::from("NYMEX"),
1502            currency: Currency::from("USD"),
1503            local_symbol: local_symbol.to_string(),
1504            last_trade_date_or_contract_month: last_trade_date.to_string(),
1505            ..Default::default()
1506        };
1507
1508        let instrument_id = Symbology::new(SymbologyMethod::Simplified)
1509            .with_futures_year_digits(FuturesYearDigits::One)
1510            .instrument_id(&contract, Some(Venue::from("XNYM")))
1511            .unwrap();
1512
1513        assert_eq!(instrument_id, InstrumentId::from(expected));
1514    }
1515
1516    #[rstest]
1517    fn test_non_grammar_local_symbol_is_emitted_verbatim() {
1518        let contract = Contract {
1519            symbol: Symbol::from("ZC"),
1520            security_type: SecurityType::Future,
1521            exchange: Exchange::from("CBOT"),
1522            currency: Currency::from("USD"),
1523            local_symbol: "ZC   DEC 26".to_string(),
1524            last_trade_date_or_contract_month: "20261214".to_string(),
1525            ..Default::default()
1526        };
1527
1528        let simplified = Symbology::new(SymbologyMethod::Simplified)
1529            .instrument_id(&contract, Some(Venue::from("XCBT")))
1530            .unwrap();
1531        let raw = Symbology::new(SymbologyMethod::Raw)
1532            .instrument_id(&contract, Some(Venue::from("XCBT")))
1533            .unwrap();
1534
1535        assert_eq!(simplified, InstrumentId::from("ZC   DEC 26.XCBT"));
1536        assert_eq!(raw, InstrumentId::from("ZC   DEC 26=FUT.XCBT"));
1537    }
1538
1539    #[rstest]
1540    fn test_fop_without_local_symbol_falls_back_to_contract_fields() {
1541        let contract = Contract {
1542            symbol: Symbol::from("ES"),
1543            security_type: SecurityType::FuturesOption,
1544            exchange: Exchange::from("CME"),
1545            currency: Currency::from("USD"),
1546            local_symbol: String::new(),
1547            last_trade_date_or_contract_month: "20261218".to_string(),
1548            right: Some(OptionRight::Put),
1549            strike: 5000.0,
1550            ..Default::default()
1551        };
1552
1553        let instrument_id = Symbology::new(SymbologyMethod::Simplified)
1554            .instrument_id(&contract, Some(Venue::from("XCME")))
1555            .unwrap();
1556
1557        assert_eq!(instrument_id, InstrumentId::from("ES20261218 P5000.XCME"));
1558    }
1559
1560    #[rstest]
1561    #[case("ESZ6", SecurityType::Future)]
1562    #[case("ESZ26", SecurityType::Future)]
1563    #[case("ESZ2026", SecurityType::Future)]
1564    #[case("ESZ26 P5000", SecurityType::FuturesOption)]
1565    fn test_futures_id_keeps_its_symbol_as_the_contract_local_symbol_outbound(
1566        #[case] symbol: &str,
1567        #[case] security_type: SecurityType,
1568    ) {
1569        let instrument_id = InstrumentId::new(NautilusSymbol::from(symbol), Venue::from("XCME"));
1570
1571        let contract = Symbology::new(SymbologyMethod::Simplified)
1572            .with_futures_year_digits(FuturesYearDigits::One)
1573            .contract(instrument_id, None)
1574            .unwrap();
1575
1576        assert_eq!(contract.security_type, security_type);
1577        assert_eq!(contract.local_symbol.as_str(), symbol);
1578        assert_eq!(contract.exchange.as_str(), "CME");
1579        assert_eq!(contract.currency.as_str(), "USD");
1580        assert!(contract.symbol.as_str().is_empty());
1581        assert!(contract.trading_class.is_empty());
1582        assert!(contract.last_trade_date_or_contract_month.is_empty());
1583        assert_eq!(contract.right, None);
1584        assert_eq!(contract.strike, 0.0);
1585    }
1586
1587    #[rstest]
1588    fn test_instrument_id_to_ib_contract_parses_named_option_symbol() {
1589        let instrument_id = InstrumentId::from("C OESX 20260213 4775.EUREX");
1590
1591        let contract = Symbology::new(SymbologyMethod::Simplified)
1592            .contract(instrument_id, None)
1593            .unwrap();
1594
1595        assert_eq!(contract.security_type, SecurityType::Option);
1596        assert_eq!(contract.exchange.as_str(), "EUREX");
1597        assert_eq!(contract.symbol.as_str(), "OESX");
1598        assert_eq!(contract.trading_class.as_str(), "OESX");
1599        assert_eq!(
1600            contract.last_trade_date_or_contract_month.as_str(),
1601            "20260213"
1602        );
1603        assert_eq!(contract.right.map(|right| right.as_str()), Some("C"));
1604        assert_eq!(contract.strike, 4775.0);
1605    }
1606
1607    #[rstest]
1608    fn test_instrument_id_to_ib_contract_preserves_occ_local_symbol() {
1609        let instrument_id = InstrumentId::from("AAPL  230217P00155000.SMART");
1610
1611        let contract = Symbology::new(SymbologyMethod::Simplified)
1612            .contract(instrument_id, None)
1613            .unwrap();
1614
1615        assert_eq!(contract.security_type, SecurityType::Option);
1616        assert_eq!(contract.exchange.as_str(), "SMART");
1617        assert_eq!(contract.symbol.as_str(), "AAPL");
1618        assert_eq!(contract.local_symbol.as_str(), "AAPL  230217P00155000");
1619        assert_eq!(
1620            contract.last_trade_date_or_contract_month.as_str(),
1621            "230217"
1622        );
1623        assert_eq!(contract.right.map(|right| right.as_str()), Some("P"));
1624        assert_eq!(contract.strike, 155.0);
1625    }
1626
1627    #[rstest]
1628    fn test_possible_exchanges_for_opra_routes_to_smart() {
1629        assert_eq!(
1630            possible_exchanges_for_venue("OPRA"),
1631            vec!["SMART".to_string()]
1632        );
1633    }
1634
1635    #[rstest]
1636    fn test_opra_occ_option_default_contract_routes_to_smart() {
1637        let instrument_id = InstrumentId::from("SPY   240319P00511000.OPRA");
1638
1639        let contract = Symbology::new(SymbologyMethod::Simplified)
1640            .contract(instrument_id, None)
1641            .unwrap();
1642
1643        assert_eq!(contract.security_type, SecurityType::Option);
1644        assert_eq!(contract.exchange.as_str(), "SMART");
1645        assert!(contract.symbol.as_str().is_empty());
1646        assert_eq!(contract.currency.as_str(), "USD");
1647        assert_eq!(contract.local_symbol.as_str(), "SPY   240319P00511000");
1648        assert!(contract.last_trade_date_or_contract_month.is_empty());
1649        assert!(contract.right.is_none());
1650        assert_eq!(contract.strike, 0.0);
1651    }
1652
1653    #[rstest]
1654    fn test_opra_occ_option_qualification_contract_uses_opt_smart() {
1655        let instrument_id = InstrumentId::from("SPY   240319P00511000.OPRA");
1656        let exchanges = possible_exchanges_for_venue(instrument_id.venue.as_str());
1657
1658        assert_eq!(exchanges, vec!["SMART".to_string()]);
1659
1660        let contract = Symbology::new(SymbologyMethod::Simplified)
1661            .contract(instrument_id, exchanges.first().map(String::as_str))
1662            .unwrap();
1663
1664        assert_eq!(contract.security_type, SecurityType::Option);
1665        assert_eq!(contract.exchange.as_str(), "SMART");
1666        assert!(contract.symbol.as_str().is_empty());
1667        assert_eq!(contract.currency.as_str(), "USD");
1668        assert_eq!(contract.local_symbol.as_str(), "SPY   240319P00511000");
1669        assert!(contract.last_trade_date_or_contract_month.is_empty());
1670        assert!(contract.right.is_none());
1671        assert_eq!(contract.strike, 0.0);
1672    }
1673
1674    #[rstest]
1675    fn test_opra_raw_option_default_contract_routes_to_smart() {
1676        let instrument_id = InstrumentId::from("SPY   240319P00511000=OPT.OPRA");
1677
1678        let contract = Symbology::new(SymbologyMethod::Raw)
1679            .contract(instrument_id, None)
1680            .unwrap();
1681
1682        assert_eq!(contract.security_type, SecurityType::Option);
1683        assert_eq!(contract.exchange.as_str(), "SMART");
1684        assert_eq!(contract.local_symbol.as_str(), "SPY   240319P00511000");
1685    }
1686
1687    #[rstest]
1688    #[case("SPY   240319P00511000.OPRA")]
1689    #[case("SPY   240319P00511000=OPT.OPRA")]
1690    fn test_opra_option_respects_exchange_override(#[case] value: &str) {
1691        let instrument_id = InstrumentId::from(value);
1692
1693        let method = if value.contains("=OPT") {
1694            SymbologyMethod::Raw
1695        } else {
1696            SymbologyMethod::Simplified
1697        };
1698
1699        let contract = Symbology::new(method)
1700            .contract(instrument_id, Some("CBOE"))
1701            .unwrap();
1702
1703        assert_eq!(contract.security_type, SecurityType::Option);
1704        assert_eq!(contract.exchange.as_str(), "CBOE");
1705    }
1706
1707    #[rstest]
1708    #[case("AAPL.OPRA")]
1709    #[case("SPY   abcdefP00511000.OPRA")]
1710    #[case("P SPY 20240319 511.OPRA")]
1711    fn test_invalid_opra_occ_option_returns_error(#[case] value: &str) {
1712        let instrument_id = InstrumentId::from(value);
1713
1714        let result = Symbology::new(SymbologyMethod::Simplified).contract(instrument_id, None);
1715
1716        assert!(result.is_err());
1717    }
1718
1719    #[rstest]
1720    fn test_opra_route_does_not_create_reverse_smart_mapping() {
1721        assert_eq!(exchange_to_mic_venue("SMART"), None);
1722    }
1723
1724    #[rstest]
1725    fn test_instrument_id_to_ib_contract_parses_named_futures_symbol() {
1726        let instrument_id = InstrumentId::from("ESTX50 FESX 20240315.EUREX");
1727
1728        let contract = Symbology::new(SymbologyMethod::Simplified)
1729            .contract(instrument_id, None)
1730            .unwrap();
1731
1732        assert_eq!(contract.security_type, SecurityType::Future);
1733        assert_eq!(contract.exchange.as_str(), "EUREX");
1734        assert_eq!(contract.symbol.as_str(), "ESTX50");
1735        assert_eq!(contract.trading_class.as_str(), "FESX");
1736        assert_eq!(
1737            contract.last_trade_date_or_contract_month.as_str(),
1738            "20240315"
1739        );
1740    }
1741
1742    #[rstest]
1743    fn test_instrument_id_to_ib_contract_maps_xcbt_to_cbot_exchange() {
1744        let instrument_id = InstrumentId::from("YMM6.XCBT");
1745
1746        let contract = Symbology::new(SymbologyMethod::Simplified)
1747            .with_futures_year_digits(FuturesYearDigits::One)
1748            .contract(instrument_id, None)
1749            .unwrap();
1750
1751        assert_eq!(contract.security_type, SecurityType::Future);
1752        assert_eq!(contract.exchange.as_str(), "CBOT");
1753        assert_eq!(contract.local_symbol.as_str(), "YMM6");
1754        assert!(contract.symbol.as_str().is_empty());
1755        assert!(contract.last_trade_date_or_contract_month.is_empty());
1756    }
1757
1758    #[rstest]
1759    fn test_instrument_id_to_ib_contract_maps_mic_future_to_member_exchange() {
1760        let instrument_id = InstrumentId::from("OESXH6.XEUR");
1761
1762        let contract = Symbology::new(SymbologyMethod::Simplified)
1763            .with_futures_year_digits(FuturesYearDigits::One)
1764            .contract(instrument_id, None)
1765            .unwrap();
1766
1767        assert_eq!(contract.security_type, SecurityType::Future);
1768        assert_eq!(contract.exchange.as_str(), "DTB");
1769        assert_eq!(contract.local_symbol.as_str(), "OESXH6");
1770        assert!(contract.symbol.as_str().is_empty());
1771        assert!(contract.last_trade_date_or_contract_month.is_empty());
1772    }
1773
1774    #[rstest]
1775    fn test_instrument_id_to_ib_contract_parses_futures_option_with_month_code_in_symbol() {
1776        let instrument_id = InstrumentId::from("YMM6 C45000.XCBT");
1777
1778        let contract = Symbology::new(SymbologyMethod::Simplified)
1779            .with_futures_year_digits(FuturesYearDigits::One)
1780            .contract(instrument_id, None)
1781            .unwrap();
1782
1783        assert_eq!(contract.security_type, SecurityType::FuturesOption);
1784        assert_eq!(contract.exchange.as_str(), "CBOT");
1785        assert_eq!(contract.local_symbol.as_str(), "YMM6 C45000");
1786        assert!(contract.symbol.as_str().is_empty());
1787        assert!(contract.last_trade_date_or_contract_month.is_empty());
1788        assert_eq!(contract.right, None);
1789        assert_eq!(contract.strike, 0.0);
1790    }
1791
1792    #[rstest]
1793    fn test_instrument_id_to_ib_contract_parses_ibcfd_cash_symbol() {
1794        let instrument_id = InstrumentId::from("EUR/USD.IBCFD");
1795
1796        let contract = Symbology::new(SymbologyMethod::Simplified)
1797            .contract(instrument_id, None)
1798            .unwrap();
1799
1800        assert_eq!(contract.security_type, SecurityType::CFD);
1801        assert_eq!(contract.exchange.as_str(), "SMART");
1802        assert_eq!(contract.symbol.as_str(), "EUR");
1803        assert_eq!(contract.currency.as_str(), "USD");
1804        assert_eq!(contract.local_symbol.as_str(), "EUR.USD");
1805    }
1806
1807    #[rstest]
1808    #[case(
1809        SymbologyMethod::Simplified,
1810        SecurityType::CFD,
1811        "IBDE30",
1812        "EUR",
1813        "IBDE30.IBCFD"
1814    )]
1815    #[case(
1816        SymbologyMethod::Raw,
1817        SecurityType::CFD,
1818        "IBDE30",
1819        "EUR",
1820        "IBDE30=CFD.IBCFD"
1821    )]
1822    #[case(
1823        SymbologyMethod::Simplified,
1824        SecurityType::Commodity,
1825        "XAUUSD",
1826        "GBP",
1827        "XAUUSD.IBCMDTY"
1828    )]
1829    #[case(
1830        SymbologyMethod::Raw,
1831        SecurityType::Commodity,
1832        "XAUUSD",
1833        "GBP",
1834        "XAUUSD=CMDTY.IBCMDTY"
1835    )]
1836    fn test_non_cash_pseudo_venue_round_trip_defers_currency_to_contract_details(
1837        #[case] method: SymbologyMethod,
1838        #[case] security_type: SecurityType,
1839        #[case] symbol: &str,
1840        #[case] currency: &str,
1841        #[case] expected_instrument_id: &str,
1842    ) {
1843        let contract = Contract {
1844            symbol: Symbol::from(symbol),
1845            security_type: security_type.clone(),
1846            exchange: Exchange::from("SMART"),
1847            currency: Currency::from(currency),
1848            local_symbol: symbol.to_string(),
1849            ..Default::default()
1850        };
1851
1852        let symbology = Symbology::new(method);
1853
1854        let instrument_id = symbology.instrument_id(&contract, None).unwrap();
1855        let unresolved = symbology.contract(instrument_id, None).unwrap();
1856        let round_trip_id = symbology.instrument_id(&unresolved, None).unwrap();
1857
1858        assert_eq!(instrument_id, InstrumentId::from(expected_instrument_id));
1859        assert_eq!(unresolved.security_type, security_type);
1860        assert_eq!(unresolved.exchange.as_str(), "SMART");
1861        assert!(unresolved.currency.as_str().is_empty());
1862        assert_eq!(round_trip_id, instrument_id);
1863    }
1864
1865    #[rstest]
1866    fn test_instrument_id_to_ib_contract_parses_long_crypto_symbol() {
1867        let instrument_id = InstrumentId::from("DOGE/USD.PAXOS");
1868
1869        let contract = Symbology::new(SymbologyMethod::Simplified)
1870            .contract(instrument_id, None)
1871            .unwrap();
1872
1873        assert_eq!(contract.security_type, SecurityType::Crypto);
1874        assert_eq!(contract.exchange.as_str(), "PAXOS");
1875        assert_eq!(contract.symbol.as_str(), "DOGE");
1876        assert_eq!(contract.currency.as_str(), "USD");
1877        assert_eq!(contract.local_symbol.as_str(), "DOGE.USD");
1878    }
1879
1880    #[rstest]
1881    fn test_instrument_id_to_ib_contract_parses_zerohash_crypto_symbol() {
1882        // ZEROHASH is one of IB's crypto venues (alongside PAXOS).
1883        let instrument_id = InstrumentId::from("BTC/USD.ZEROHASH");
1884
1885        let contract = Symbology::new(SymbologyMethod::Simplified)
1886            .contract(instrument_id, None)
1887            .unwrap();
1888
1889        assert_eq!(contract.security_type, SecurityType::Crypto);
1890        assert_eq!(contract.exchange.as_str(), "ZEROHASH");
1891        assert_eq!(contract.symbol.as_str(), "BTC");
1892        assert_eq!(contract.currency.as_str(), "USD");
1893        assert_eq!(contract.local_symbol.as_str(), "BTC.USD");
1894    }
1895
1896    #[rstest]
1897    fn test_ib_contract_to_instrument_id_simplified_derives_zerohash_crypto_venue() {
1898        // Contract -> InstrumentId derives the venue from the ZEROHASH exchange.
1899        let contract = Contract {
1900            symbol: Symbol::from("BTC"),
1901            security_type: SecurityType::Crypto,
1902            exchange: Exchange::from("ZEROHASH"),
1903            currency: Currency::from("USD"),
1904            local_symbol: "BTC.USD".to_string(),
1905            ..Default::default()
1906        };
1907
1908        let instrument_id = Symbology::new(SymbologyMethod::Simplified)
1909            .instrument_id(&contract, None)
1910            .unwrap();
1911
1912        assert_eq!(instrument_id, InstrumentId::from("BTC/USD.ZEROHASH"));
1913    }
1914
1915    #[rstest]
1916    fn test_ib_contract_to_instrument_id_simplified_falls_back_to_paxos_crypto_venue() {
1917        // Contract -> InstrumentId falls back to PAXOS when no exchange is set,
1918        // preserving backwards compatibility.
1919        let contract = Contract {
1920            symbol: Symbol::from("DOGE"),
1921            security_type: SecurityType::Crypto,
1922            currency: Currency::from("USD"),
1923            local_symbol: "DOGE.USD".to_string(),
1924            ..Default::default()
1925        };
1926
1927        let instrument_id = Symbology::new(SymbologyMethod::Simplified)
1928            .instrument_id(&contract, None)
1929            .unwrap();
1930
1931        assert_eq!(instrument_id, InstrumentId::from("DOGE/USD.PAXOS"));
1932    }
1933
1934    #[rstest]
1935    fn test_instrument_id_to_ib_contract_parses_paxos_crypto_symbol() {
1936        // PAXOS remains a live IB crypto venue alongside ZEROHASH.
1937        let instrument_id = InstrumentId::from("BTC/USD.PAXOS");
1938
1939        let contract = Symbology::new(SymbologyMethod::Simplified)
1940            .contract(instrument_id, None)
1941            .unwrap();
1942
1943        assert_eq!(contract.security_type, SecurityType::Crypto);
1944        assert_eq!(contract.exchange.as_str(), "PAXOS");
1945        assert_eq!(contract.symbol.as_str(), "BTC");
1946        assert_eq!(contract.currency.as_str(), "USD");
1947        assert_eq!(contract.local_symbol.as_str(), "BTC.USD");
1948    }
1949
1950    #[rstest]
1951    fn test_ib_contract_to_instrument_id_simplified_derives_paxos_crypto_venue() {
1952        // A PAXOS contract derives the PAXOS venue from its exchange (not via the
1953        // fallback), proving both venues are honored when explicitly set.
1954        let contract = Contract {
1955            symbol: Symbol::from("BTC"),
1956            security_type: SecurityType::Crypto,
1957            exchange: Exchange::from("PAXOS"),
1958            currency: Currency::from("USD"),
1959            local_symbol: "BTC.USD".to_string(),
1960            ..Default::default()
1961        };
1962
1963        let instrument_id = Symbology::new(SymbologyMethod::Simplified)
1964            .instrument_id(&contract, None)
1965            .unwrap();
1966
1967        assert_eq!(instrument_id, InstrumentId::from("BTC/USD.PAXOS"));
1968    }
1969
1970    #[rstest]
1971    fn test_instrument_id_to_ib_contract_uses_contfut_for_underlying() {
1972        let instrument_id = InstrumentId::from("ES.XCME");
1973
1974        let contract = Symbology::new(SymbologyMethod::Simplified)
1975            .contract(instrument_id, None)
1976            .unwrap();
1977
1978        assert_eq!(contract.security_type, SecurityType::ContinuousFuture);
1979        assert_eq!(contract.exchange.as_str(), "CME");
1980        assert_eq!(contract.symbol.as_str(), "ES");
1981    }
1982
1983    #[rstest]
1984    fn test_instrument_id_to_ib_contract_parses_raw_stock_symbol() {
1985        let instrument_id = InstrumentId::from("AAPL=STK.NASDAQ");
1986
1987        let contract = Symbology::new(SymbologyMethod::Simplified)
1988            .contract(instrument_id, None)
1989            .unwrap();
1990
1991        assert_eq!(contract.security_type, SecurityType::Stock);
1992        assert_eq!(contract.exchange.as_str(), "SMART");
1993        assert_eq!(contract.primary_exchange.as_str(), "NASDAQ");
1994        assert_eq!(contract.local_symbol.as_str(), "AAPL");
1995        assert!(contract.symbol.as_str().is_empty());
1996    }
1997
1998    #[rstest]
1999    fn test_instrument_id_to_ib_contract_parses_raw_forex_symbol() {
2000        let instrument_id = InstrumentId::from("EUR.USD=CASH.IDEALPRO");
2001
2002        let contract = Symbology::new(SymbologyMethod::Simplified)
2003            .contract(instrument_id, None)
2004            .unwrap();
2005
2006        assert_eq!(contract.security_type, SecurityType::ForexPair);
2007        assert_eq!(contract.exchange.as_str(), "IDEALPRO");
2008        assert_eq!(contract.local_symbol.as_str(), "EUR.USD");
2009        assert!(contract.symbol.as_str().is_empty());
2010    }
2011
2012    #[rstest]
2013    fn test_instrument_id_to_ib_contract_raw_respects_exchange_override() {
2014        let instrument_id = InstrumentId::from("YMM6=FUT.XCBT");
2015
2016        let contract = Symbology::new(SymbologyMethod::Simplified)
2017            .with_futures_year_digits(FuturesYearDigits::One)
2018            .contract(instrument_id, Some("CBOT"))
2019            .unwrap();
2020
2021        assert_eq!(contract.security_type, SecurityType::Future);
2022        assert_eq!(contract.exchange.as_str(), "CBOT");
2023        assert_eq!(contract.local_symbol.as_str(), "YMM6");
2024        assert!(contract.symbol.as_str().is_empty());
2025        assert!(contract.last_trade_date_or_contract_month.is_empty());
2026    }
2027
2028    fn share_class_stock() -> Contract {
2029        Contract {
2030            symbol: Symbol::from("BRK B"),
2031            security_type: SecurityType::Stock,
2032            exchange: Exchange::from("SMART"),
2033            primary_exchange: Exchange::from("NYSE"),
2034            currency: Currency::from("USD"),
2035            local_symbol: "BRK B".to_string(),
2036            ..Default::default()
2037        }
2038    }
2039
2040    #[rstest]
2041    #[case(true, "BRK B.NYSE")]
2042    #[case(false, "BRK-B.NYSE")]
2043    fn test_ib_contract_to_instrument_id_simplified_names_share_class(
2044        #[case] share_class_space: bool,
2045        #[case] expected: &str,
2046    ) {
2047        let instrument_id = Symbology::new(SymbologyMethod::Simplified)
2048            .with_share_class_space(share_class_space)
2049            .instrument_id(&share_class_stock(), Some(Venue::from("NYSE")))
2050            .unwrap();
2051
2052        assert_eq!(instrument_id, InstrumentId::from(expected));
2053    }
2054
2055    #[rstest]
2056    #[case("BRK B.NYSE")]
2057    #[case("BRK-B.NYSE")]
2058    fn test_instrument_id_to_ib_contract_simplified_spells_share_class_with_space(
2059        #[case] instrument_id: &str,
2060    ) {
2061        let contract = Symbology::new(SymbologyMethod::Simplified)
2062            .contract(InstrumentId::from(instrument_id), Some("NYSE"))
2063            .unwrap();
2064
2065        assert_eq!(contract.security_type, SecurityType::Stock);
2066        assert_eq!(contract.symbol.as_str(), "BRK B");
2067        assert_eq!(contract.primary_exchange.as_str(), "NYSE");
2068    }
2069
2070    #[rstest]
2071    fn test_instrument_id_to_ib_contract_default_stock_omits_local_symbol_and_currency() {
2072        let instrument_id = InstrumentId::from("IUSA.IBIS");
2073
2074        let contract = Symbology::new(SymbologyMethod::Simplified)
2075            .contract(instrument_id, Some("IBIS"))
2076            .unwrap();
2077
2078        assert_eq!(contract.security_type, SecurityType::Stock);
2079        assert_eq!(contract.symbol.as_str(), "IUSA");
2080        assert_eq!(contract.exchange.as_str(), "SMART");
2081        assert_eq!(contract.primary_exchange.as_str(), "IBIS");
2082        assert!(contract.currency.as_str().is_empty());
2083        assert!(contract.local_symbol.is_empty());
2084    }
2085
2086    #[rstest]
2087    #[case("ESZ6", "20261218", "ESZ26.XCME")]
2088    #[case("ESZ9", "20291221", "ESZ29.XCME")]
2089    #[case("ESH0", "20200320", "ESH20.XCME")]
2090    #[case("ESH0", "20300315", "ESH30.XCME")]
2091    #[case("CLF6", "20251219", "CLF26.XCME")]
2092    #[case("CLF0", "20291219", "CLF30.XCME")]
2093    #[case("SR3Z6", "20270316", "SR3Z26.XCME")]
2094    #[case("SR3Z9", "20300319", "SR3Z29.XCME")]
2095    fn test_default_futures_year_matches_definition(
2096        #[case] symbol: &str,
2097        #[case] expiry: &str,
2098        #[case] expected: InstrumentId,
2099    ) {
2100        let contract = Contract {
2101            symbol: Symbol::from("ROOT"),
2102            security_type: SecurityType::Future,
2103            local_symbol: symbol.to_string(),
2104            last_trade_date_or_contract_month: expiry.to_string(),
2105            ..Default::default()
2106        };
2107
2108        let id = Symbology::new(SymbologyMethod::Simplified)
2109            .instrument_id(&contract, Some(Venue::from("XCME")))
2110            .unwrap();
2111        assert_eq!(id, expected);
2112    }
2113
2114    #[rstest]
2115    #[case(SymbologyMethod::Simplified, "CLF30.XNYM")]
2116    #[case(SymbologyMethod::Raw, "CLF30=FUT.XNYM")]
2117    fn test_two_digit_futures_request_uses_root_and_contract_month(
2118        #[case] method: SymbologyMethod,
2119        #[case] instrument_id: InstrumentId,
2120    ) {
2121        let contract = instrument_id_to_contract(
2122            instrument_id,
2123            Some("NYMEX"),
2124            FuturesYearDigits::Two,
2125            2029,
2126            Some("USD"),
2127        );
2128        assert_eq!(contract.symbol.as_str(), "");
2129        assert_eq!(contract.trading_class, "CL");
2130        assert_eq!(contract.security_type, SecurityType::Future);
2131        assert_eq!(contract.exchange.as_str(), "NYMEX");
2132        assert_eq!(contract.currency.as_str(), "USD");
2133        assert_eq!(contract.last_trade_date_or_contract_month, "203001");
2134        assert_eq!(contract.local_symbol, "CLF0");
2135        assert_eq!(contract.right, None);
2136        assert_eq!(contract.strike, 0.0);
2137
2138        let inbound = Symbology::new(method)
2139            .instrument_id(
2140                &Contract {
2141                    local_symbol: "CLF0".to_string(),
2142                    last_trade_date_or_contract_month: "20291219".to_string(),
2143                    ..contract
2144                },
2145                Some(Venue::from("XNYM")),
2146            )
2147            .unwrap();
2148
2149        assert_eq!(inbound, instrument_id);
2150    }
2151
2152    #[rstest]
2153    #[case("6EH26.XCME", "6EH6", "6E", SecurityType::Future, "202603", None, 0.0)]
2154    #[case(
2155        "VXH26=FUT.CFE",
2156        "VXH6",
2157        "VX",
2158        SecurityType::Future,
2159        "202603",
2160        None,
2161        0.0
2162    )]
2163    #[case(
2164        "EW1F26 P5000.XCME",
2165        "EW1F6 P5000",
2166        "",
2167        SecurityType::FuturesOption,
2168        "",
2169        None,
2170        0.0
2171    )]
2172    fn test_two_digit_lookup_preserves_native_symbols(
2173        #[case] id: InstrumentId,
2174        #[case] native: &str,
2175        #[case] trading_class: &str,
2176        #[case] kind: SecurityType,
2177        #[case] month: &str,
2178        #[case] right: Option<OptionRight>,
2179        #[case] strike: f64,
2180    ) {
2181        let contract =
2182            instrument_id_to_contract(id, Some("CME"), FuturesYearDigits::Two, 2026, Some("USD"));
2183        assert_eq!(contract.symbol.as_str(), "");
2184        assert_eq!(contract.local_symbol, native);
2185        assert_eq!(contract.trading_class, trading_class);
2186        assert_eq!(contract.security_type, kind);
2187        assert_eq!(contract.exchange.as_str(), "CME");
2188        assert_eq!(contract.currency.as_str(), "USD");
2189        assert_eq!(contract.last_trade_date_or_contract_month, month);
2190        assert_eq!(contract.right, right);
2191        assert_eq!(contract.strike, strike);
2192    }
2193}