Struct IbkrClient 

pub struct IbkrClient { /* private fields */ }

Interactive Brokers execution client.

Clone Behavior

Cloning creates a shallow copy with shared Arc references to the underlying IB connection, contract registry, order ID map, and execution buffer. All clones share the same TWS/Gateway connection and state.

Implementations

impl IbkrClient

pub fn connect_sync(config: IbkrConfig) -> Result<Self, UnindexedClientError>

Connect to TWS/Gateway and initialize the client (sync, blocking).

Errors

Returns error if connection fails or contract resolution fails.

pub fn register_contract( &self, name: InstrumentNameExchange, contract: Contract, )

Register a contract for an instrument.

pub fn contract_registry(&self) -> &ContractRegistry

Get the contract registry.

pub fn pending_execution_count(&self) -> usize

Get the number of pending executions awaiting commission reports.

Useful for monitoring whether commission reports are being received. A growing count may indicate IB connection issues or delayed reports.

pub fn clear_stale_executions(&self, max_age: Duration) -> usize

Clear stale executions older than the given duration.

Returns the number of cleared entries.

Call this periodically to prevent unbounded memory growth if commission reports are delayed or lost. A reasonable interval is 5-10 minutes with a max_age of 1 hour.

pub fn clear_stale_order_ids(&self, max_age: Duration) -> usize

Clear order ID mappings older than the given duration.

Returns the number of cleared entries.

Why This Is Needed

IB does not guarantee event ordering between OrderStatus("Filled") and ExecutionData/CommissionReport. For fast-filling orders (especially market orders), execution data may arrive AFTER the filled status — or the filled status may not arrive at all. Removing mappings on terminal status would cause data loss.

Call this periodically alongside clear_stale_executions(). A reasonable interval is 5-10 minutes with a max_age of 1 hour.

pub fn clear_stale_pending_cancels(&self, max_age: Duration) -> usize

Clear pending cancel entries older than the given duration.

Returns the number of cleared entries.

Pending cancels are tracked to differentiate user-initiated cancellation from time-based expiration. If a cancel request is submitted but the order never receives terminal status (e.g., network disconnect), the entry would remain indefinitely. Call this alongside other stale cleanup methods.

pub fn disconnect(&self)

Disconnect from IB Gateway.

Signals the ibapi client to shut down and releases the client ID for reuse.

IbkrClient implements Clone and has no Drop impl: the underlying connection is released automatically when the last Arc<Client> reference is dropped. Calling disconnect() explicitly terminates the connection immediately for all clones sharing this client.

Any active account_stream() iterators will receive errors on their next iteration attempt.

This is idempotent — calling it multiple times is safe.

pub async fn open_bracket_order( &self, request: BracketOrderRequest, ) -> BracketOrderResult

Place a bracket order (entry + take-profit + stop-loss) with OCA linking.

A bracket order consists of three linked orders:

1. Entry: Limit order to enter the position
2. Take Profit: Limit order to exit at profit target (OCA-linked to SL)
3. Stop Loss: Stop order to exit at loss limit (OCA-linked to TP)

OCA (One-Cancels-All) Behavior

When either exit order fills, IB automatically cancels the other. This prevents the dangerous scenario where take-profit fills but stop-loss remains open, potentially opening an unintended opposing position.

All-or-Nothing Semantics

If any leg is rejected by IB (e.g., insufficient margin, invalid price), this method cancels all other legs and returns all three as Inactive. You will never receive a mix of active and inactive legs.

The same all-legs cancellation applies if any leg fails to report a terminal status within the placement timeout (an unknown/no-status outcome): leaving part of a bracket working while the rest is in an unknown state is unsafe, so all three legs are cancelled and an error is returned. This is intentionally stricter than single-order placement (open_order), where a no-status outcome retains the order and defers resolution to the account stream.

Cancellation Safety

This future registers order ID mappings before submitting to IB. If cancelled mid-flight, orders may still be submitted and mappings will leak. Avoid cancelling this future; use IB’s native order timeout via TimeInForce if timeout behavior is needed.

Example

let request = BracketOrderRequest {
    instrument: "AAPL".into(),
    strategy: StrategyId::new("my-strategy"),
    parent_cid: ClientOrderId::new("bracket-001"),
    side: Side::Buy,
    quantity: dec!(100),
    entry_price: dec!(150.00),
    take_profit_price: dec!(160.00),  // +$10 profit target
    stop_loss_price: dec!(145.00),    // -$5 stop loss
    time_in_force: TimeInForce::GoodUntilCancelled { post_only: false },
};
let result = client.open_bracket_order(request).await;

Trait Implementations

impl BracketOrderClient for IbkrClient

async fn open_bracket_order( &self, request: UnifiedBracketOrderRequest<ExchangeId, &InstrumentNameExchange>, ) -> UnifiedBracketOrderResult

Place a bracket order (entry + take-profit + stop-loss).

impl Clone for IbkrClient

fn clone(&self) -> IbkrClient

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for IbkrClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl ExecutionClient for IbkrClient

fn new(config: Self::Config) -> Self

Create a new IBKR client by connecting to TWS/Gateway.

Blocking

This method performs blocking TCP I/O and IB API handshake. If called from an async context, wrap in tokio::task::spawn_blocking or call from a dedicated thread.

Panics

Panics if connection fails. The ExecutionClient trait doesn’t allow new() to return Result. Use IbkrClient::connect_sync() directly for fallible construction.

async fn account_snapshot( &self, assets: &[AssetNameExchange], instruments: &[InstrumentNameExchange], ) -> Result<UnindexedAccountSnapshot, UnindexedClientError>

Fetch account snapshot (balances and positions).

Limitations

• The orders field in each InstrumentAccountSnapshot is always empty. IB’s positions endpoint returns position data only, not open orders. Use fetch_open_orders() or account_stream() for order state.

• Position quantity and average cost from IB are not carried in the returned InstrumentAccountSnapshot. The struct only indicates which instruments have positions, not the position sizes. This is a limitation of the InstrumentAccountSnapshot type, not the IB API.

Known Issue: ibapi Decode Errors

You may see log errors like "error decoding message: error occurred: unexpected message: Error". This is an upstream ibapi limitation where IB Error messages (type 4) on subscription channels aren’t properly routed — they’re logged but don’t affect functionality.

Timeout

Uses 5-second timeout between position updates. If IB stalls mid-stream (e.g., due to the ibapi PositionEnd routing bug), returns partial results after 5s of inactivity rather than blocking indefinitely.

For accounts with no positions, this method waits the full 5-second timeout before returning an empty position list.

async fn account_stream( &self, _assets: &[AssetNameExchange], _instruments: &[InstrumentNameExchange], ) -> Result<Self::AccountStream, UnindexedClientError>

Stream account events (order updates, fills, commissions).

Thread Lifecycle

Spawns a background thread to read from the blocking IB subscription. The thread terminates when:

• The returned BoxStream is dropped (channel closes)
• The IB subscription ends (disconnect)

Important: If IB is stalled (no events flowing), the thread blocks on the iterator. Dropping the stream signals termination, but the thread won’t observe it until the next IB event arrives. For graceful shutdown during stalls, the caller should disconnect the IB connection.

Duplicate Events

Orders submitted via open_order() will emit OrderSnapshot events on this stream in addition to the response from open_order() itself. This is inherent to IB’s API — both the per-order subscription and the global order update stream receive the same OrderStatus events. Callers should deduplicate if needed.

Filter Parameters

The assets and instruments parameters are currently ignored. IB’s order_update_stream() returns events for all orders on the account. Callers subscribing for a specific instrument will receive events for all instruments.

async fn cancel_order( &self, request: OrderRequestCancel<ExchangeId, &InstrumentNameExchange>, ) -> Option<UnindexedOrderResponseCancel>

Cancel an order.

Async Cancel Semantics

Returns Ok(Cancelled) when the cancel request is submitted, not when the order is confirmed cancelled. The actual cancellation confirmation comes via account_stream as an OrderStatus::Cancelled event.

The order ID mapping is retained until terminal status is received via account_stream, ensuring fill events arriving between cancel request and confirmation are not lost.

async fn open_order( &self, request: OrderRequestOpen<ExchangeId, &InstrumentNameExchange>, ) -> Option<Order<ExchangeId, InstrumentNameExchange, UnindexedOrderState>>

Submit an order to IB.

Cancellation Safety

This future registers the order ID mapping before submitting to IB. If the future is cancelled (e.g., via tokio::select! timeout) after registration but before completion:

• The order may still be submitted to IB
• The order ID mapping will leak (not cleaned up)
• Subsequent fills will be processed via account_stream

Callers should avoid cancelling this future mid-flight. If timeout behavior is needed, prefer setting IB’s native order timeout via TimeInForce instead.

async fn fetch_balances( &self, assets: &[AssetNameExchange], ) -> Result<Vec<AssetBalance<AssetNameExchange>>, UnindexedClientError>

Fetch account balances.

Limitations

The time_exchange field in returned balances uses Utc::now(), not the actual IB server timestamp. IB’s account summary endpoint does not provide timestamps per balance update.

async fn fetch_open_orders( &self, instruments: &[InstrumentNameExchange], ) -> Result<Vec<Order<ExchangeId, InstrumentNameExchange, Open>>, UnindexedClientError>

Fetch open orders.

Limitations

• The filled_qty in returned orders is set to zero. IB’s open orders endpoint returns order definitions, not fill status. For accurate filled quantities, use account_stream which provides OrderStatus events with fill progress.
• The time_in_force defaults to GoodUntilCancelled. IB’s open orders endpoint does not return the original TIF setting.
• This method blocks on IB’s subscription until IB sends an end-of-data marker. If IB is stalled, this will block indefinitely.

async fn fetch_trades( &self, time_since: DateTime<Utc>, instruments: &[InstrumentNameExchange], ) -> Result<Vec<Trade<AssetNameExchange, InstrumentNameExchange>>, UnindexedClientError>

Fetch historical trades (executions).

Limitations

• IB only returns executions from the current trading day. The time_since parameter is applied client-side to filter within that day. For historical executions beyond today, use IB’s Flex Query or Activity Statements.
• Fees are always zero. IB’s executions endpoint doesn’t include commission data. For trades with accurate fees, use account_stream() which pairs ExecutionData with CommissionReport events.
• This method blocks on IB’s executions subscription until IB sends an end-of-data marker. If IB is stalled, this will block indefinitely.

const EXCHANGE: ExchangeId = ExchangeId::Ibkr

type Config = IbkrConfig

type AccountStream = Pin<Box<dyn Stream<Item = AccountEvent<ExchangeId, AssetNameExchange, InstrumentNameExchange>> + Send>>

fn cancel_orders<'a>( &self, requests: impl IntoIterator<Item = OrderRequestCancel<ExchangeId, &'a InstrumentNameExchange>>, ) -> impl Stream<Item = Option<UnindexedOrderResponseCancel>> + Send

fn open_orders<'a>( &self, requests: impl IntoIterator<Item = OrderRequestOpen<ExchangeId, &'a InstrumentNameExchange>>, ) -> impl Stream<Item = Option<Order<ExchangeId, InstrumentNameExchange, UnindexedOrderState>>> + Send