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() ends with StreamTerminated within about a second.

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.

Failure Semantics

If any leg is rejected by IB (e.g., insufficient margin, invalid price), or cannot be sent, this method cancels every leg already sent and returns the legs as Inactive, except for legs of unknown fate (below).

The same all-legs cancellation applies if any leg fails to report a status within the placement timeout, or the transport drops while waiting (an unknown/no-status outcome): leaving part of a bracket working while the rest is in an unknown state is unsafe, so every leg is cancelled and an error is returned.

Legs of Unknown Fate

Cancelling does not settle a leg whose fate is unknown: a leg that reported no status, or whose rollback cancel could not be sent (ibapi refuses sends while its transport is down), may still be live or held at TWS. Such a leg comes back Open with zero fill and keeps its order-id mapping, as a no-status single order does, so the account stream can report how it ends. The other legs come back Inactive with the error. A leg IB rejected is settled even if its cancel was refused. So a failed bracket can return a mix of Open and Inactive legs, and every leg can be Open when none reported a status: an all-Open result is then indistinguishable from success, and the failure shows only in the log and on the account stream. Treat an Open leg as working until the account stream or ExecutionClient::fetch_open_orders says otherwise.

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) -> Self

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 a position per registered instrument IB reports.

Positions

Each instrument IB reports a position in, and that is registered (and in instruments, when that is not empty), gets an InstrumentAccountSnapshot. Its position is PositionReport::Open, carrying:

• quantity: IB’s signed position, negative when short, in shares for a stock and in contracts for a future or an option. ibapi 4.2.0 hands it over as an f64, converted with Decimal::try_from, which rounds to the float’s precision of about 15 significant digits (0.1 stays 0.1) rather than keeping its exact binary expansion.
• entry_price: IB’s average cost divided by the contract multiplier, so a future or an option is quoted as its orders are priced. It includes commissions. None when IB sends no average cost, or no multiplier for a contract other than a stock or a forex pair.
• time_exchange: the time of the call, since IB does not timestamp positions.

unrealized_pnl and the margin fields are None: IB’s positions subscription does not carry them.

A zero quantity, which IB reports for a position closed today, is PositionReport::Flat. So is each instrument in instruments that is registered with its contract ID but that IB did not list, provided IB marked the end of its listing (PositionEnd) during the read. Without that marker such instruments are left out, with a warning, since the listing may be incomplete: IB can start the read with a stale listing, and only an end marker after the last report counts. IB’s positions request carries no request ID, so one case cannot be caught: a stale end marker on its own, followed by a current listing that does not start within the read’s 5-second quiet period. It reads as the listing of an account holding nothing, and the requested instruments are reported flat. A requested instrument registered without a contract ID, or whose ID was registered again under another name, cannot be matched to IB’s reports and is left out too.

IB can report the same position more than once during the read, as it changes. The latest report for each account is used.

Several accounts. IB reports positions per account, and this client does not select one. When more than one account holds the same instrument, the first account to report a non-zero quantity is kept and the others are dropped with a warning; they are never summed. A consumer comparing the reported quantity with its own, as the rustrade engine’s position drift check does, therefore compares against that one account. Which account comes first depends on the order IB reports them in, so a caller holding the same instrument in several accounts should not rely on it.

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.

Errors

UnindexedClientError::Internal if a position quantity does not convert to a Decimal, or if the positions subscription fails.

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

IB’s positions request is a live subscription that keeps streaming after the initial set, so the read ends once 5 seconds pass without a position update. Every call therefore takes at least 5 seconds, including for an account with no positions. If IB stalls mid-stream, the positions received so far are returned rather than blocking indefinitely.

Known Issue: Errors After a Connection Drop on ibapi 4.2.0

After each connection drop, the next two calls fail with UnindexedClientError::Internal. The third succeeds. See the module’s Known Issues.

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

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

Thread Lifecycle

Spawns two background threads: ibkr-order-stream reads the blocking IB subscription, and ibkr-fill-recovery watches for gaps in event delivery (see below). The watcher exits within about a second of the returned BoxStream being dropped or the stream ending. The reader exits when:

• The returned BoxStream is dropped (channel closes), or the stream has ended, and the next IB event arrives
• The IB subscription ends

Important: If IB is stalled (no events flowing), the reader thread blocks on the iterator. Dropping the stream signals termination, but the thread won’t observe it until the next IB event arrives. Disconnecting does not release it either: ibapi does not end the order-update subscription when the client shuts down (wboayue/rust-ibapi#871), so after a shutdown the thread stays blocked until the process exits.

Reconnects and Fill Recovery

ibapi reconnects its socket to TWS/Gateway by itself, and this stream stays open across that: a transient drop produces neither an error nor StreamTerminated. TWS does not resend what it sent while the socket was down, and TWS losing its own link to IB’s servers (notice 1100) opens the same kind of gap. Once delivery is restored, this stream asks TWS for the day’s executions and emits the ones from the gap as Trade events. The gap is taken to start up to a poll interval before the drop was noticed, minus a lookback margin. Trades the stream already delivered are not emitted twice.

Order lifecycle events are not recovered. An order that was cancelled, expired or rejected during the gap is not reported here. Reconcile with ExecutionClient::fetch_open_orders after a reconnect, minding its known issue on ibapi 4.2.0. The log line Recovered IBKR fills after a gap in event delivery marks one.

While TWS reports its link to IB’s servers lost (1100), nothing marks the gap on this stream until the link is restored and the recovered fills arrive.

The stream ends with StreamTerminated when:

• recovery fails three times for a reason other than the transport dropping again, rather than stay open with a gap;
• the client shuts down for good, because ibapi gave up reconnecting or IbkrClient::disconnect was called. ibapi never ends the order update subscription itself, so this is detected from its notice stream, which it does close.

After either, the reader thread stays blocked on the subscription, and holds ibapi’s single order-update slot, until TWS sends another event. Calling account_stream again on the same client fails meanwhile. After a shutdown, TWS sends nothing more, so replace the client.

Shutdown is detected only while this stream is open. Called on a client that has already shut down, this method still returns a stream, which never ends. After a stream ends with a shutdown, replace the client rather than resubscribe on it.

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.

Trade events are delivered once each. Executions that answer an executions request, such as ExecutionClient::fetch_trades, are not reported here as fills.

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.

Known Issue: Stale Results on ibapi 4.2.0

The result may not be this call’s answer. See the module’s Known Issues.

• Order updates received since the previous call are read as part of the result. It can hold the same order more than once, and orders that have since filled or been cancelled, reported as open.
• After the first connection drop, the next three calls fail with UnindexedClientError::Internal, and every call after them returns the reply to the call three before it. Each later drop adds three more calls of lag, and three more failures, which come once the replies already queued have been read. Retrying does not catch up.

Do not treat the result as authoritative open-order state on 4.2.0. The order events from ExecutionClient::account_stream are unaffected.

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

const SUPPORTED_KINDS: &'static [InstrumentKindDiscriminant]

The InstrumentKindDiscriminants this client can trade.

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