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