Skip to main content

nautilus_interactive_brokers/historical/
client.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//! Historical data client for Interactive Brokers.
17
18use std::{fmt::Debug, str::FromStr, sync::Arc};
19
20use anyhow::Context;
21use ibapi::{
22    client::Client,
23    contracts::{Contract, SecurityType},
24    market_data::{IgnoreSize, TradingHours, historical},
25    prelude::{StreamExt, SubscriptionItemStreamExt},
26};
27use jiff::Timestamp;
28use nautilus_core::UnixNanos;
29use nautilus_model::{
30    data::{Bar, BarSpecification, BarType, Data, QuoteTick},
31    enums::{AggregationSource, BarAggregation, PriceType},
32    identifiers::InstrumentId,
33    instruments::{Instrument, any::InstrumentAny},
34    types::Quantity,
35};
36
37use crate::{
38    common::{
39        enums::IbHistoricalTickType,
40        shared_client::{self, SharedClientHandle},
41        symbology::is_crypto_contract,
42    },
43    config::{InteractiveBrokersDataClientConfig, MarketDataType},
44    data::{
45        convert::{
46            IbPriceConverter, bar_request_range, bar_type_to_ib_bar_size,
47            extend_historical_tick_batch, historical_tick_request_end, ib_bar_to_nautilus_bar,
48            ib_timestamp_to_unix_nanos, jiff_to_ib_datetime,
49            price_type_to_ib_what_to_show_for_security, retain_historical_ticks_in_range,
50        },
51        parse::parse_trade_tick,
52    },
53    providers::instruments::InteractiveBrokersInstrumentProvider,
54};
55
56const HISTORICAL_TICK_DEFAULT_LIMIT: usize = 10_000;
57
58/// Historical data client for Interactive Brokers.
59///
60/// This client provides methods for requesting historical bars and ticks
61/// for backtesting and research purposes.
62#[cfg_attr(
63    feature = "python",
64    pyo3::pyclass(
65        module = "nautilus_trader.adapters.interactive_brokers",
66        subclass,
67        from_py_object
68    )
69)]
70#[cfg_attr(
71    feature = "python",
72    pyo3_stub_gen::derive::gen_stub_pyclass(
73        module = "nautilus_trader.adapters.interactive_brokers"
74    )
75)]
76pub struct HistoricalInteractiveBrokersClient {
77    /// IB API client.
78    ib_client: Arc<Client>,
79    /// Instrument provider.
80    instrument_provider: Arc<InteractiveBrokersInstrumentProvider>,
81    /// Shared client handle, when this client owns the connection lifecycle.
82    _shared_client: Option<Arc<SharedClientHandle>>,
83}
84
85impl Clone for HistoricalInteractiveBrokersClient {
86    fn clone(&self) -> Self {
87        Self {
88            ib_client: Arc::clone(&self.ib_client),
89            instrument_provider: Arc::clone(&self.instrument_provider),
90            _shared_client: self._shared_client.clone(),
91        }
92    }
93}
94
95impl Debug for HistoricalInteractiveBrokersClient {
96    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
97        f.debug_struct(stringify!(HistoricalInteractiveBrokersClient))
98            .field("ib_client", &"<Client>")
99            .field("instrument_provider", &"<InstrumentProvider>")
100            .finish()
101    }
102}
103
104impl HistoricalInteractiveBrokersClient {
105    /// Create a new historical data client.
106    pub fn new(
107        ib_client: Arc<Client>,
108        instrument_provider: Arc<InteractiveBrokersInstrumentProvider>,
109    ) -> Self {
110        Self {
111            ib_client,
112            instrument_provider,
113            _shared_client: None,
114        }
115    }
116
117    /// Connect to Interactive Brokers and create a historical data client.
118    ///
119    /// This initializes an instrument provider from `config.instrument_provider` and acquires the
120    /// shared IB client for the configured host, port, and client ID.
121    ///
122    /// # Errors
123    ///
124    /// Returns an error if configuration validation, provider initialization, or the IB connection fails.
125    pub async fn connect(config: InteractiveBrokersDataClientConfig) -> anyhow::Result<Self> {
126        config.validate()?;
127
128        let instrument_provider = Arc::new(InteractiveBrokersInstrumentProvider::new(
129            config.instrument_provider.clone(),
130        )?);
131        let shared_client = shared_client::get_or_connect(
132            &config.host,
133            config.port,
134            config.client_id,
135            config.connection_timeout,
136            config.max_reconnect_attempts,
137        )
138        .await?;
139        let client = shared_client.as_arc();
140
141        if config.market_data_type != MarketDataType::Realtime {
142            let market_data_type: ibapi::market_data::MarketDataType =
143                config.market_data_type.into();
144            client.switch_market_data_type(market_data_type).await?;
145        }
146
147        instrument_provider
148            .initialize_with_client(client.as_ref())
149            .await?;
150
151        Ok(Self::from_shared_client(shared_client, instrument_provider))
152    }
153
154    pub(crate) fn from_shared_client(
155        shared_client: SharedClientHandle,
156        instrument_provider: Arc<InteractiveBrokersInstrumentProvider>,
157    ) -> Self {
158        let ib_client = Arc::clone(shared_client.as_arc());
159
160        Self {
161            ib_client,
162            instrument_provider,
163            _shared_client: Some(Arc::new(shared_client)),
164        }
165    }
166
167    /// Connect a historical data client with a supplied provider using the shared IB client registry.
168    ///
169    /// This keeps standalone Rust callers from needing to acquire `common::shared_client`
170    /// directly before requesting instruments or historical data.
171    ///
172    /// # Errors
173    ///
174    /// Returns an error if configuration validation fails, the shared client cannot connect, or
175    /// the instrument provider cannot initialize.
176    pub async fn connect_with_provider(
177        instrument_provider: InteractiveBrokersInstrumentProvider,
178        config: InteractiveBrokersDataClientConfig,
179    ) -> anyhow::Result<Self> {
180        config.validate()?;
181
182        let shared_client = shared_client::get_or_connect(
183            &config.host,
184            config.port,
185            config.client_id,
186            config.connection_timeout,
187            config.max_reconnect_attempts,
188        )
189        .await?;
190        let client = shared_client.as_arc();
191
192        if config.market_data_type != MarketDataType::Realtime {
193            let market_data_type: ibapi::market_data::MarketDataType =
194                config.market_data_type.into();
195            client.switch_market_data_type(market_data_type).await?;
196        }
197
198        instrument_provider
199            .initialize_with_client(client.as_ref())
200            .await?;
201
202        Ok(Self::from_shared_client(
203            shared_client,
204            Arc::new(instrument_provider),
205        ))
206    }
207
208    /// Request historical bars.
209    ///
210    /// # Continuous futures
211    ///
212    /// Continuous futures (`CONTFUT`) reject an explicit end date/time with IB
213    /// error 10339. For these contracts the end date is dropped and only the
214    /// first duration segment is requested, anchored to the current time, so
215    /// the returned bars may fall outside `[start_date_time, end_date_time]`.
216    /// A warning is logged when the requested end date/time is in the past or
217    /// the range spans more than one duration segment.
218    ///
219    /// # Errors
220    ///
221    /// Returns an error if the request fails.
222    #[allow(clippy::too_many_arguments)]
223    pub async fn request_bars(
224        &self,
225        bar_specifications: Vec<&str>,
226        end_date_time: Timestamp,
227        start_date_time: Option<Timestamp>,
228        duration: Option<&str>,
229        contracts: Option<Vec<Contract>>,
230        instrument_ids: Option<Vec<InstrumentId>>,
231        use_rth: bool,
232        timeout: u64,
233    ) -> anyhow::Result<Vec<Bar>> {
234        // Validate inputs
235        if start_date_time.is_some() && duration.is_some() {
236            anyhow::bail!("Either start_date_time or duration should be provided, not both");
237        }
238
239        if let Some(start) = start_date_time
240            && start >= end_date_time
241        {
242            anyhow::bail!("Start date must be before end date");
243        }
244
245        let duration = duration
246            .map(str::parse::<historical::Duration>)
247            .transpose()
248            .with_context(|| {
249                format!(
250                    "duration must be in format: 'int S|D|W|M|Y', was '{}'",
251                    duration.unwrap_or_default()
252                )
253            })?;
254
255        let contracts = contracts.unwrap_or_default();
256        let instrument_ids = instrument_ids.unwrap_or_default();
257
258        if contracts.is_empty() && instrument_ids.is_empty() {
259            anyhow::bail!("Either contracts or instrument_ids must be provided");
260        }
261
262        // Convert instrument IDs to contracts using instrument provider
263        let mut all_contracts = contracts;
264
265        for instrument_id in instrument_ids {
266            // Try to find instrument in provider first
267            if self.instrument_provider.find(&instrument_id).is_none() {
268                // Auto-fetch if not cached
269                if let Err(e) = self
270                    .instrument_provider
271                    .fetch_contract_details(&self.ib_client, instrument_id, false, None)
272                    .await
273                {
274                    tracing::warn!(
275                        "Failed to auto-fetch contract details for {}: {}",
276                        instrument_id,
277                        e
278                    );
279                }
280            }
281
282            // Try to convert instrument ID to contract
283            if let Ok(contract) = self
284                .instrument_provider
285                .resolve_contract_for_instrument_async(&self.ib_client, instrument_id)
286                .await
287            {
288                all_contracts.push(contract);
289            } else {
290                tracing::warn!(
291                    "Failed to convert instrument_id {} to IB contract, skipping",
292                    instrument_id
293                );
294            }
295        }
296
297        // Auto-fetch contracts if not cached (by contract ID)
298        for contract in &all_contracts {
299            if let Some(instrument_id) = self
300                .instrument_provider
301                .get_instrument_id_by_contract_id(contract.contract_id)
302                && self.instrument_provider.find(&instrument_id).is_none()
303                && let Err(e) = self
304                    .instrument_provider
305                    .fetch_contract_details(&self.ib_client, instrument_id, false, None)
306                    .await
307            {
308                tracing::warn!(
309                    "Failed to auto-fetch contract details for contract ID {}: {}",
310                    contract.contract_id,
311                    e
312                );
313            }
314        }
315
316        if all_contracts.is_empty() {
317            anyhow::bail!("No valid contracts found after conversion");
318        }
319
320        let trading_hours = if use_rth {
321            TradingHours::Regular
322        } else {
323            TradingHours::Extended
324        };
325
326        let mut all_bars = Vec::new();
327
328        for contract in all_contracts {
329            for bar_spec_str in &bar_specifications {
330                // Parse bar spec (e.g., "1-HOUR-LAST")
331                let parts: Vec<&str> = bar_spec_str.split('-').collect();
332                if parts.len() != 3 {
333                    anyhow::bail!("Invalid bar specification format: {bar_spec_str}");
334                }
335
336                let step = parts[0].parse::<usize>()?;
337                let aggregation = parts[1].to_lowercase();
338                let price_type = parts[2].to_uppercase();
339                let price_type = PriceType::from_str(&price_type)
340                    .with_context(|| format!("Invalid bar price type: {}", parts[2]))?;
341
342                let bar_spec = match aggregation.as_str() {
343                    "second" => BarSpecification::new(step, BarAggregation::Second, price_type),
344                    "minute" => BarSpecification::new(step, BarAggregation::Minute, price_type),
345                    "hour" => BarSpecification::new(step, BarAggregation::Hour, price_type),
346                    "day" => BarSpecification::new(step, BarAggregation::Day, price_type),
347                    "week" => BarSpecification::new(step, BarAggregation::Week, price_type),
348                    _ => anyhow::bail!("Unsupported aggregation: {aggregation}"),
349                };
350
351                let instrument_id = self.resolve_instrument_id(&contract).await?;
352                let bar_type_with_id =
353                    BarType::new(instrument_id, bar_spec, AggregationSource::External);
354
355                // Convert bar type to IB parameters. Crypto trade-price bars must
356                // request AGGTRADES, not TRADES (TWS rejects TRADES for crypto,
357                // error 10299) - same rule as the live data client's historical path.
358                let ib_bar_size = bar_type_to_ib_bar_size(&bar_type_with_id)?;
359                let is_crypto = is_crypto_contract(&contract);
360                let ib_what_to_show =
361                    price_type_to_ib_what_to_show_for_security(bar_spec.price_type, is_crypto);
362
363                // Omit the end date for continuous futures (IB error 10339).
364                let is_continuous_future = contract.security_type == SecurityType::ContinuousFuture;
365                let range = bar_request_range(
366                    start_date_time,
367                    Some(end_date_time),
368                    duration,
369                    is_continuous_future,
370                );
371
372                if let Some(range) = range {
373                    let instrument =
374                        self.instrument_provider
375                            .find(&instrument_id)
376                            .with_context(|| {
377                                format!("Instrument {instrument_id} is missing from the provider")
378                            })?;
379
380                    let prices = IbPriceConverter::for_instrument(
381                        &instrument,
382                        self.instrument_provider.get_price_magnifier(&instrument_id),
383                    );
384                    let size_precision = instrument.size_precision();
385
386                    for bar_request in range.requests(&bar_spec) {
387                        tracing::debug!("Requesting historical bars over {bar_request:?}");
388
389                        let request = bar_request
390                            .apply(self.ib_client.historical_data(&contract, ib_bar_size))
391                            .what_to_show(ib_what_to_show)
392                            .trading_hours(trading_hours);
393
394                        let historical_data = tokio::time::timeout(
395                            std::time::Duration::from_secs(timeout),
396                            request.fetch(),
397                        )
398                        .await
399                        .context(format!(
400                            "Historical data request timed out after {timeout} seconds"
401                        ))??;
402
403                        // Create new bar_type with correct instrument_id
404                        for ib_bar in &historical_data.bars {
405                            let nautilus_bar = ib_bar_to_nautilus_bar(
406                                ib_bar,
407                                bar_type_with_id,
408                                prices,
409                                size_precision,
410                            )?;
411
412                            if range.contains(nautilus_bar.ts_event) {
413                                all_bars.push(nautilus_bar);
414                            }
415                        }
416
417                        tracing::debug!("Retrieved {} bars in batch", historical_data.bars.len());
418                    }
419                }
420            }
421        }
422
423        // Sort by timestamp
424        all_bars.sort_by_key(|b| b.ts_event);
425
426        Ok(all_bars)
427    }
428
429    /// Request historical ticks with pagination support.
430    ///
431    /// # Errors
432    ///
433    /// Returns an error if the request fails.
434    #[allow(clippy::too_many_arguments)]
435    pub async fn request_ticks(
436        &self,
437        tick_type: IbHistoricalTickType,
438        start_date_time: Timestamp,
439        end_date_time: Timestamp,
440        contracts: Option<Vec<Contract>>,
441        instrument_ids: Option<Vec<InstrumentId>>,
442        use_rth: bool,
443        timeout: u64,
444        limit: usize,
445    ) -> anyhow::Result<Vec<Data>> {
446        if start_date_time >= end_date_time {
447            anyhow::bail!("Start date must be before end date");
448        }
449
450        let limit = Some(if limit > 0 {
451            limit
452        } else {
453            HISTORICAL_TICK_DEFAULT_LIMIT
454        });
455
456        if end_date_time.duration_since(start_date_time) > jiff::SignedDuration::from_hours(24) {
457            tracing::warn!(
458                "Requesting tick data for more than 1 day may take a long time, particularly for liquid instruments"
459            );
460        }
461
462        let contracts = contracts.unwrap_or_default();
463        let instrument_ids = instrument_ids.unwrap_or_default();
464
465        if contracts.is_empty() && instrument_ids.is_empty() {
466            anyhow::bail!("Either contracts or instrument_ids must be provided");
467        }
468
469        let trading_hours = if use_rth {
470            TradingHours::Regular
471        } else {
472            TradingHours::Extended
473        };
474
475        // Convert instrument IDs to contracts and auto-fetch if not cached
476        let mut all_contracts = contracts;
477
478        for instrument_id in instrument_ids {
479            // Auto-fetch if not cached
480            if self.instrument_provider.find(&instrument_id).is_none()
481                && let Err(e) = self
482                    .instrument_provider
483                    .fetch_contract_details(&self.ib_client, instrument_id, false, None)
484                    .await
485            {
486                tracing::warn!(
487                    "Failed to auto-fetch contract details for {}: {}",
488                    instrument_id,
489                    e
490                );
491            }
492
493            if let Ok(contract) = self
494                .instrument_provider
495                .resolve_contract_for_instrument_async(&self.ib_client, instrument_id)
496                .await
497            {
498                all_contracts.push(contract);
499            } else {
500                tracing::warn!(
501                    "Failed to convert instrument_id {} to IB contract, skipping",
502                    instrument_id
503                );
504            }
505        }
506
507        // Auto-fetch contracts if not cached
508        for contract in &all_contracts {
509            if let Some(instrument_id) = self
510                .instrument_provider
511                .get_instrument_id_by_contract_id(contract.contract_id)
512                && self.instrument_provider.find(&instrument_id).is_none()
513                && let Err(e) = self
514                    .instrument_provider
515                    .fetch_contract_details(&self.ib_client, instrument_id, false, None)
516                    .await
517            {
518                tracing::warn!(
519                    "Failed to auto-fetch contract details for contract ID {}: {}",
520                    contract.contract_id,
521                    e
522                );
523            }
524        }
525
526        if all_contracts.is_empty() {
527            anyhow::bail!("No valid contracts found after conversion");
528        }
529
530        let mut all_ticks = Vec::new();
531
532        for contract in all_contracts {
533            let instrument_id = self.resolve_instrument_id(&contract).await?;
534
535            let instrument = self
536                .instrument_provider
537                .find(&instrument_id)
538                .with_context(|| {
539                    format!("Instrument {instrument_id} is missing from the provider")
540                })?;
541
542            let prices = IbPriceConverter::for_instrument(
543                &instrument,
544                self.instrument_provider.get_price_magnifier(&instrument_id),
545            );
546            let size_precision = instrument.size_precision();
547            let mut contract_ticks = Vec::new();
548
549            // Pagination loop for ticks (similar to Python _handle_timestamp_iteration)
550            let mut current_end_date = Some(historical_tick_request_end(end_date_time));
551            let current_start_date = Some(start_date_time);
552            let start_date_time_ns = UnixNanos::from(
553                u64::try_from(start_date_time.as_nanosecond())
554                    .context("Historical tick start date precedes the Unix epoch")?,
555            );
556            let end_date_time_ns = UnixNanos::from(
557                u64::try_from(end_date_time.as_nanosecond())
558                    .context("Historical tick end date precedes the Unix epoch")?,
559            );
560
561            match tick_type {
562                IbHistoricalTickType::Trades => {
563                    while let Some(request_end) = current_end_date {
564                        // Make request for this batch
565                        let subscription = tokio::time::timeout(
566                            std::time::Duration::from_secs(timeout),
567                            self.ib_client
568                                .historical_ticks(&contract, 1000)
569                                .ending(jiff_to_ib_datetime(&request_end))
570                                .trading_hours(trading_hours)
571                                .trade(),
572                        )
573                        .await
574                        .context(format!(
575                            "Historical trades request timed out after {timeout} seconds"
576                        ))??;
577
578                        let mut subscription = subscription.filter_data();
579                        let mut batch_ticks = Vec::new();
580
581                        while let Some(tick_result) = subscription.next().await {
582                            let tick = match tick_result {
583                                Ok(tick) => tick,
584                                Err(e) => {
585                                    tracing::warn!("Historical trade ticks stream error: {e:?}");
586                                    continue;
587                                }
588                            };
589
590                            let ts_event = ib_timestamp_to_unix_nanos(&tick.timestamp);
591
592                            if ts_event < start_date_time_ns || ts_event > end_date_time_ns {
593                                continue;
594                            }
595
596                            let ts_init = ts_event;
597
598                            let Some(raw_size) = tick.size else {
599                                tracing::warn!(
600                                    "Skipping historical trade tick with no size for {}",
601                                    instrument_id
602                                );
603                                continue;
604                            };
605
606                            if raw_size == 0.0 {
607                                tracing::warn!(
608                                    "Skipping historical trade tick with zero size for {instrument_id}"
609                                );
610                                continue;
611                            }
612
613                            let trade_tick = parse_trade_tick(
614                                instrument_id,
615                                tick.price,
616                                raw_size,
617                                prices,
618                                size_precision,
619                                ts_event,
620                                ts_init,
621                                None,
622                            )
623                            .with_context(|| {
624                                format!("Invalid historical trade tick for {instrument_id}")
625                            })?;
626
627                            batch_ticks.push(Data::Trade(trade_tick));
628                        }
629
630                        if !extend_historical_tick_batch(
631                            &mut contract_ticks,
632                            batch_ticks,
633                            current_start_date,
634                            &mut current_end_date,
635                            Some(start_date_time_ns),
636                            Some(end_date_time_ns),
637                            limit,
638                            data_ts_event,
639                        ) {
640                            break;
641                        }
642                    }
643                }
644                IbHistoricalTickType::BidAsk => {
645                    while let Some(request_end) = current_end_date {
646                        // Make request for this batch
647                        let subscription = tokio::time::timeout(
648                            std::time::Duration::from_secs(timeout),
649                            self.ib_client
650                                .historical_ticks(&contract, 1000)
651                                .ending(jiff_to_ib_datetime(&request_end))
652                                .trading_hours(trading_hours)
653                                .bid_ask(IgnoreSize::No),
654                        )
655                        .await
656                        .context(format!(
657                            "Historical bid/ask ticks request timed out after {timeout} seconds"
658                        ))??;
659
660                        let mut subscription = subscription.filter_data();
661                        let mut batch_ticks = Vec::new();
662
663                        while let Some(tick_result) = subscription.next().await {
664                            let tick = match tick_result {
665                                Ok(tick) => tick,
666                                Err(e) => {
667                                    tracing::warn!("Historical bid/ask ticks stream error: {e:?}");
668                                    continue;
669                                }
670                            };
671
672                            let ts_event = ib_timestamp_to_unix_nanos(&tick.timestamp);
673
674                            if ts_event < start_date_time_ns || ts_event > end_date_time_ns {
675                                continue;
676                            }
677
678                            let ts_init = ts_event;
679
680                            let raw_bid_price = tick.price_bid;
681
682                            let bid_price = prices
683                                .bid_price(raw_bid_price)
684                                .with_context(|| {
685                                    format!(
686                                        "Invalid historical bid price {raw_bid_price} for {instrument_id}"
687                                    )
688                                })?;
689
690                            let (Some(raw_bid_size), Some(raw_ask_size)) =
691                                (tick.size_bid, tick.size_ask)
692                            else {
693                                tracing::warn!(
694                                    "Skipping historical quote tick with an absent size for {}",
695                                    instrument_id
696                                );
697                                continue;
698                            };
699
700                            let bid_size = Quantity::new_checked(raw_bid_size, size_precision)
701                                .with_context(|| {
702                                    format!(
703                                        "Invalid historical bid size {raw_bid_size} for {instrument_id}"
704                                    )
705                                })?;
706
707                            let raw_ask_price = tick.price_ask;
708
709                            let ask_price = prices
710                                .ask_price(raw_ask_price)
711                                .with_context(|| {
712                                    format!(
713                                        "Invalid historical ask price {raw_ask_price} for {instrument_id}"
714                                    )
715                                })?;
716
717                            let ask_size = Quantity::new_checked(raw_ask_size, size_precision)
718                                .with_context(|| {
719                                    format!(
720                                        "Invalid historical ask size {raw_ask_size} for {instrument_id}"
721                                    )
722                                })?;
723
724                            let quote_tick = QuoteTick::new(
725                                instrument_id,
726                                bid_price,
727                                ask_price,
728                                bid_size,
729                                ask_size,
730                                ts_event,
731                                ts_init,
732                            );
733
734                            batch_ticks.push(Data::Quote(quote_tick));
735                        }
736
737                        if !extend_historical_tick_batch(
738                            &mut contract_ticks,
739                            batch_ticks,
740                            current_start_date,
741                            &mut current_end_date,
742                            Some(start_date_time_ns),
743                            Some(end_date_time_ns),
744                            limit,
745                            data_ts_event,
746                        ) {
747                            break;
748                        }
749                    }
750                }
751            }
752
753            retain_historical_ticks_in_range(
754                &mut contract_ticks,
755                Some(start_date_time_ns),
756                Some(end_date_time_ns),
757                data_ts_event,
758            );
759            contract_ticks.sort_by_key(data_ts_event);
760            if let Some(limit) = limit
761                && contract_ticks.len() > limit
762            {
763                contract_ticks = contract_ticks.split_off(contract_ticks.len() - limit);
764            }
765
766            all_ticks.extend(contract_ticks);
767        }
768
769        // Sort by timestamp
770        all_ticks.sort_by_key(data_ts_event);
771
772        Ok(all_ticks)
773    }
774
775    /// Request instruments given instrument IDs or contracts.
776    ///
777    /// This method uses the instrument provider to load and return instruments.
778    ///
779    /// # Returns
780    ///
781    /// Returns a list of instruments.
782    ///
783    /// # Errors
784    ///
785    /// Returns an error if loading fails.
786    pub async fn request_instruments(
787        &self,
788        instrument_ids: Option<Vec<InstrumentId>>,
789        contracts: Option<Vec<Contract>>,
790    ) -> anyhow::Result<Vec<InstrumentAny>> {
791        let instrument_ids = instrument_ids.unwrap_or_default();
792        let contracts = contracts.unwrap_or_default();
793
794        if instrument_ids.is_empty() && contracts.is_empty() {
795            anyhow::bail!("Either instrument_ids or contracts must be provided");
796        }
797
798        let loaded_ids = self
799            .instrument_provider
800            .load_ids_with_return_async(&self.ib_client, instrument_ids, None)
801            .await?;
802        let mut loaded_instruments = self.instrument_provider.find_all(&loaded_ids);
803
804        // Load instruments from contracts (equivalent to Python's _fetch_instruments_if_not_cached)
805        for contract in contracts {
806            match self
807                .instrument_provider
808                .get_instrument(&self.ib_client, &contract)
809                .await
810            {
811                Ok(Some(instrument)) => {
812                    if !loaded_instruments.iter().any(|i| i.id() == instrument.id()) {
813                        loaded_instruments.push(instrument);
814                    }
815
816                    continue;
817                }
818                Ok(None) => {}
819                Err(e) => {
820                    tracing::warn!(
821                        "Failed to fetch contract details from original contract {:?}: {}",
822                        contract,
823                        e
824                    );
825                }
826            }
827
828            // Try to find instrument by contract ID first
829            let instrument_id = if let Some(cached_id) = self
830                .instrument_provider
831                .get_instrument_id_by_contract_id(contract.contract_id)
832            {
833                Some(cached_id)
834            } else {
835                // Convert contract to instrument ID using provider's venue determination
836                // This matches Python's logic: venue = instrument_provider.determine_venue_from_contract(contract)
837                let venue = self.instrument_provider.determine_venue(&contract, None);
838                self.instrument_provider
839                    .instrument_id_from_contract(&contract, venue)
840                    .ok()
841            };
842
843            if let Some(instrument_id) = instrument_id {
844                // Check if already loaded (skip if already in results)
845                if loaded_instruments.iter().any(|i| i.id() == instrument_id) {
846                    continue;
847                }
848
849                // Fetch if not cached (matching Python: if not self._client._cache.instrument(instrument_id))
850                if self.instrument_provider.find(&instrument_id).is_none() {
851                    tracing::debug!("Fetching Instrument for: {}", instrument_id);
852
853                    if let Err(e) = self
854                        .instrument_provider
855                        .fetch_contract_details(&self.ib_client, instrument_id, false, None)
856                        .await
857                    {
858                        tracing::warn!(
859                            "Failed to fetch contract details for {}: {}",
860                            instrument_id,
861                            e
862                        );
863                        continue;
864                    }
865                }
866
867                if let Some(instrument) = self.instrument_provider.find(&instrument_id) {
868                    loaded_instruments.push(instrument);
869                }
870            } else {
871                // Fallback: try using get_instrument which handles BAG contracts
872                if let Ok(Some(instrument)) = self
873                    .instrument_provider
874                    .get_instrument(&self.ib_client, &contract)
875                    .await
876                    && !loaded_instruments.iter().any(|i| i.id() == instrument.id())
877                {
878                    loaded_instruments.push(instrument);
879                }
880            }
881        }
882
883        tracing::debug!("Loaded {} instruments", loaded_instruments.len());
884
885        Ok(loaded_instruments)
886    }
887
888    async fn resolve_instrument_id(&self, contract: &Contract) -> anyhow::Result<InstrumentId> {
889        if let Some(instrument_id) = self
890            .instrument_provider
891            .get_instrument_id_by_contract_id(contract.contract_id)
892        {
893            return Ok(instrument_id);
894        }
895
896        let venue = self.instrument_provider.determine_venue(contract, None);
897        let parsed = self
898            .instrument_provider
899            .instrument_id_from_contract(contract, venue)
900            .ok();
901
902        if let Some(instrument_id) = parsed {
903            return Ok(instrument_id);
904        }
905
906        if let Ok(Some(instrument)) = self
907            .instrument_provider
908            .get_instrument(&self.ib_client, contract)
909            .await
910        {
911            return Ok(instrument.id());
912        }
913
914        anyhow::bail!(
915            "Failed to resolve instrument ID for contract {}:{}:{}",
916            contract.symbol,
917            contract.security_type,
918            contract.exchange
919        );
920    }
921}
922
923fn data_ts_event(data: &Data) -> UnixNanos {
924    match data {
925        Data::Trade(tick) => tick.ts_event,
926        Data::Quote(tick) => tick.ts_event,
927        _ => UnixNanos::default(),
928    }
929}
930
931#[cfg(test)]
932mod tests {
933    use nautilus_common::config::ConfigError;
934    use rstest::rstest;
935
936    use super::*;
937    use crate::config::InteractiveBrokersInstrumentProviderConfig;
938
939    #[rstest]
940    #[case::config(false)]
941    #[case::supplied_config(true)]
942    #[tokio::test]
943    async fn test_historical_connect_rejects_duplicates_before_connection(#[case] supplied: bool) {
944        let duplicate_provider: InteractiveBrokersInstrumentProviderConfig =
945            serde_json::from_value(serde_json::json!({
946                "load_contracts": [{"conId": 265598}, {"conId": 265598}]
947            }))
948            .unwrap();
949
950        let config = InteractiveBrokersDataClientConfig {
951            host: "127.0.0.1".to_string(),
952            port: 1,
953            connection_timeout: 1,
954            instrument_provider: duplicate_provider,
955            ..Default::default()
956        };
957
958        let result = if supplied {
959            let provider = InteractiveBrokersInstrumentProvider::new(Default::default()).unwrap();
960
961            HistoricalInteractiveBrokersClient::connect_with_provider(provider, config).await
962        } else {
963            HistoricalInteractiveBrokersClient::connect(config).await
964        };
965
966        let error = result.expect_err("duplicate config must fail before gateway connection");
967        assert_eq!(
968            error.downcast_ref::<ConfigError>(),
969            Some(&ConfigError::duplicate("load_contracts", None))
970        );
971    }
972}