ibkr

func (AccountBaseCurrencyProvenance) Proven ¶ added in v2.7.0

func (p AccountBaseCurrencyProvenance) Proven() bool

Proven reports whether a broker field established the base currency. Only these two provenances stand as evidence. Any consumer that publishes, stores, or trades on a base-currency label must gate on this rather than on a non-empty currency string: RawAccountSummary.Currency is the legacy numeric-row fallback and can name a currency nothing established.

func (*Connection) BrokerIDNamespaceReady ¶

func (c *Connection) BrokerIDNamespaceReady() bool

BrokerIDNamespaceReady reports whether nextValidId established the shared request/order correlation frontier for the current socket.

func (*Connection) BrokerSessionEpoch ¶

func (c *Connection) BrokerSessionEpoch() uint64

BrokerSessionEpoch identifies the current socket generation. It advances before each connection attempt so request collectors can reject callbacks from an older socket even when the Connection object itself is reused.

func (*Connection) CancelAccountSummary ¶

func (c *Connection) CancelAccountSummary(reqID int) error

CancelAccountSummary cancels the account-summary request identified by reqID.

func (*Connection) CancelHistoricalData ¶

func (c *Connection) CancelHistoricalData(ctx context.Context, reqID int) error

CancelHistoricalData cancels an active historical request and honors ctx while waiting for rate-limiter admission.

func (*Connection) CancelMarketData ¶

func (c *Connection) CancelMarketData(reqID int) error

CancelMarketData cancels the market-data subscription identified by reqID.

func (*Connection) CancelOrder ¶

func (c *Connection) CancelOrder(orderID int) error

CancelOrder sends a cancelOrder request for an existing order ID. The default build returns ErrTradingDisabled; the "trading" build enables the raw write but does not grant application cancel authority. A nil error means the frame was written, not that IBKR confirmed cancellation.

func (*Connection) CancelPaperOrder ¶

func (c *Connection) CancelPaperOrder(gate PaperOrderGate, orderID int) error

CancelPaperOrder validates gate against the connection and sends a paper cancelOrder request in either build mode. The gate is connection evidence, not application cancel authority. A nil error means the frame was written, not that IBKR confirmed cancellation.

func (*Connection) CancelPnL ¶

func (c *Connection) CancelPnL(reqID int) error

CancelPnL requests cancellation of the reqPnL stream identified by reqID. It returns nil when the connection is already down because socket closure also terminates the stream.

func (*Connection) CancelPnLSingle ¶

func (c *Connection) CancelPnLSingle(reqID int) error

CancelPnLSingle requests cancellation of the reqPnLSingle stream identified by reqID. It returns nil when the connection is already down.

func (*Connection) Connect ¶

func (c *Connection) Connect(ctx context.Context) error

Connect establishes and handshakes a TWS or IB Gateway connection using the configured client ID. Context cancellation bounds the connection attempt.

func (*Connection) Disconnect ¶

func (c *Connection) Disconnect() error

Disconnect closes the protocol session and stops its background work. It is safe to call more than once.

func (*Connection) ExerciseOptions ¶

func (c *Connection) ExerciseOptions(req OptionExerciseRequest) error

ExerciseOptions validates and sends an IBKR option exercise or lapse instruction. It can change a position if IBKR accepts it. A nil error means only that the frame was accepted for the socket write; the method does not wait for broker acknowledgement or finality. In the default build it returns ErrTradingDisabled before validation or transmission. The "trading" build tag enables this low-level wire method but does not grant submit authority.

func (*Connection) GetAccountCode ¶

func (c *Connection) GetAccountCode() string

GetAccountCode returns the last known managed account code.

func (*Connection) GetAccountSummary ¶

func (c *Connection) GetAccountSummary() map[string]string

GetAccountSummary returns a detached copy of the current account-summary cache.

func (*Connection) GetAccountValue ¶

func (c *Connection) GetAccountValue(key string) (string, bool)

GetAccountValue returns the cached account value for key, if present.

func (*Connection) GetConnectionInfo ¶

func (c *Connection) GetConnectionInfo() map[string]any

GetConnectionInfo returns a snapshot of connection diagnostics. The returned map is detached from the connection's internal state.

func (*Connection) GetNextOrderID ¶

func (c *Connection) GetNextOrderID() int

GetNextOrderID reserves the next broker order ID after TWS has supplied a nextValidId for the current socket. Request and order IDs share one local monotonic namespace because msgErrMsg/msg-204 multiplex both kinds through one integer field. Zero means nextValidId has not arrived or the signed 32-bit broker namespace is exhausted; callers must not send an order then.

func (*Connection) GetNextRequestID ¶

func (c *Connection) GetNextRequestID() int

GetNextRequestID reserves and returns the next connection-local request ID. Request and order IDs deliberately share one monotonic frontier so a delayed broker error can never be reinterpreted as a later order event. Zero means the signed 32-bit broker namespace is exhausted.

func (*Connection) GetPosition ¶

func (c *Connection) GetPosition(key string) (*RawPosition, bool)

GetPosition returns the cached position for key, if present.

func (*Connection) GetPositions ¶

func (c *Connection) GetPositions() map[string]*RawPosition

GetPositions returns a detached map containing the current position cache.

func (*Connection) GetPositionsSnapshot ¶

func (c *Connection) GetPositionsSnapshot() map[string]*RawPosition

GetPositionsSnapshot returns the most recent complete reqPositions result. It is isolated from the streaming reqAccountUpdates projection; nil means no one-shot generation has completed in this connection.

func (*Connection) GetPositionsWithPortfolioHealth ¶

func (c *Connection) GetPositionsWithPortfolioHealth() (map[string]*RawPosition, PortfolioStreamHealth)

GetPositionsWithPortfolioHealth captures the cached portfolio rows and the stream receipts under one lock order. The returned map and health value are detached copies.

func (*Connection) HasCompetingLiveSession ¶

func (c *Connection) HasCompetingLiveSession() bool

HasCompetingLiveSession returns true if IBKR reported code 10197 for this connection.

func (*Connection) IsConnected ¶

func (c *Connection) IsConnected() bool

IsConnected reports whether the protocol session is connected.

func (*Connection) IsWhatIfOrderID ¶

func (c *Connection) IsWhatIfOrderID(orderID int) bool

IsWhatIfOrderID reports whether orderID is currently reserved for broker WhatIf evaluation callbacks rather than a working broker order.

func (*Connection) MarketDataType ¶

func (c *Connection) MarketDataType(reqID int) int

MarketDataType returns the current market data type for a reqID. 1=RealTime, 2=Frozen, 3=Delayed, 4=DelayedFrozen. 0 if unknown.

func (*Connection) PlaceOrder ¶

func (c *Connection) PlaceOrder(order *IBKROrder) error

PlaceOrder sends a placeOrder request using the v45+ wire format. The default build returns ErrTradingDisabled; the "trading" build enables the raw write but does not grant application submit authority. A nil error means the frame was written, not that IBKR accepted or finalized the order.

func (*Connection) PlacePaperOrder ¶

func (c *Connection) PlacePaperOrder(gate PaperOrderGate, order *IBKROrder) error

PlacePaperOrder validates gate against the connection and sends a paper placeOrder request in either build mode. The gate is connection evidence, not application submit authority. A nil error means the frame was written, not that IBKR accepted or finalized the order.

func (*Connection) PortfolioProjectionGeneration ¶

func (c *Connection) PortfolioProjectionGeneration() uint64

PortfolioProjectionGeneration returns the current structural portfolio generation. Price, mark, and P&L-only updates do not advance it.

func (*Connection) PreviewOrderWhatIf ¶

func (c *Connection) PreviewOrderWhatIf(ctx context.Context, order *IBKROrder) (OrderWhatIfResult, error)

PreviewOrderWhatIf sends a broker WhatIf order preview and waits for the matching openOrder or error callback. It is available in both build modes: the encoded request has WhatIf and Transmit set true for broker evaluation, but does not create a working order. Preview evidence never grants submit authority; unrestricted PlaceOrder and CancelOrder remain build-tag guarded.

The method mutates order by applying defaults and IDs and by setting WhatIf and Transmit. Local validation or encoding failures are returned as errors. A disconnected connection, send failure, or ctx completion instead returns a result with Status OrderWhatIfStatusUnavailable and a nil error. Accepted and rejected results reflect callback classification, not order finality.

func (*Connection) PrewarmOptionChain ¶

func (c *Connection) PrewarmOptionChain(
	ctx context.Context,
	symbol string,
	expiries []string,
	tradingClass string,
	timeout time.Duration,
) []PrewarmOptionChainResult

PrewarmOptionChain bulk-resolves an option chain by issuing one partial- Contract reqContractDetails per expiration — no Strike, no Right — and streaming the returned contractData frames into optionContractCache. This is the technique TWS uses internally to populate a chain instantly: IBKR's reqContractDetails returns every listed strike × C/P for a given (Symbol, SecType=OPT, Expiry, TradingClass) tuple in one burst.

Compared to per-leg resolution (the cold path each leg-fetcher takes via resolveOptionContract), this drops the gateway round-trip count from 2×strikes×expirations (typical: ~1600) to len(expiries) (typical: 6), and sidesteps the IBKR per-account reqContractDetails throttle that otherwise aborts the gamma fan-out at the first ~50 attempts.

Fan-out: each expiry runs in its own goroutine, gated by a small semaphore (4) to avoid bursting the gateway. Failures are localised — one timed-out expiry doesn't fail the others. tradingClass is load-bearing for SPY/SPX (separates SPY from SPYW weeklies); the caller is expected to know it (e.g. via the secDefOptParams response).

Returns one result per expiry (Cached count + Elapsed + per-expiry Err). The caller decides whether partial success is acceptable.

func (*Connection) RegisterHandler ¶

func (c *Connection) RegisterHandler(msgID int, handler func([]string)) uint64

RegisterHandler adds a handler for msgID and returns the identifier accepted by Connection.UnregisterHandler. A nil handler is ignored and returns zero.

func (*Connection) RegisterHandlerAtEpoch ¶

func (c *Connection) RegisterHandlerAtEpoch(msgID int, handler func([]string, uint64)) uint64

RegisterHandlerAtEpoch adds a handler that receives the socket epoch that read each frame. Connector installs its fixed handler set before starting the Connection reader; dynamic handlers must likewise register before the request that can produce their response.

func (*Connection) RequestAccountSummary ¶

func (c *Connection) RequestAccountSummary(reqID int, tags string) error

RequestAccountSummary starts an account-summary request for reqID. An empty tags string requests the package's default set of account values.

func (*Connection) RequestAccountSummaryForAccount ¶

func (c *Connection) RequestAccountSummaryForAccount(reqID int, tags, expectedAccount string) error

RequestAccountSummaryForAccount starts one account-bound summary read. TWS still receives group "All" because account codes are not account-group names; every returned row is checked against expectedAccount before it can enter the per-request snapshot.

func (*Connection) RequestAccountUpdates ¶

func (c *Connection) RequestAccountUpdates(account string) error

RequestAccountUpdates subscribes to streaming account and portfolio updates for account.

func (*Connection) RequestAllOpenOrders ¶

func (c *Connection) RequestAllOpenOrders() error

RequestAllOpenOrders sends reqAllOpenOrders to the gateway. Results arrive asynchronously as openOrder and orderStatus callbacks followed by openOrderEnd; a nil error means only that the request frame was accepted for the socket write. This read request is available in both build modes.

func (*Connection) RequestContractDetails ¶

func (c *Connection) RequestContractDetails(contract Contract) (int, error)

RequestContractDetails sends a request to retrieve contract details for a contract. Returns the reqID used for the request.

func (*Connection) RequestCurrentTime ¶

func (c *Connection) RequestCurrentTime() error

RequestCurrentTime asks the gateway for its current time. The connection uses this request as a heartbeat.

func (*Connection) RequestHistoricalData ¶

func (c *Connection) RequestHistoricalData(ctx context.Context, contract Contract, endDateTime, duration, barSize, whatToShow string, useRTH bool, includeExpired bool, formatDate int, keepUpToDate bool, beforeSend func(int)) (int, error)

RequestHistoricalData submits an HMDS request for historical data and honors ctx while waiting for rate-limiter admission. The beforeSend callback is invoked after the reqID is allocated but before the message is sent, allowing callers to register tracking state safely. The parameter list past whatToShow mirrors the reqHistoricalData wire message field-for-field (useRTH, includeExpired, formatDate, keepUpToDate).

func (*Connection) RequestMarketData ¶

func (c *Connection) RequestMarketData(ctx context.Context, symbol string) (int, error)

RequestMarketData subscribes to market data for a symbol. ctx must be non-nil and bounds the wait for market-data slot admission. Pass context.Background when the caller does not need cancellation.

func (*Connection) RequestMarketDataWithContract ¶

func (c *Connection) RequestMarketDataWithContract(ctx context.Context, contract Contract, genericTicks string, snapshot bool, regulatorySnap bool) (int, error)

RequestMarketDataWithContract issues reqMktData for contract. ctx must be non-nil and bounds the wait for market-data slot admission. Pass context.Background when the caller does not need cancellation.

func (*Connection) RequestMarketDataWithPrimary ¶

func (c *Connection) RequestMarketDataWithPrimary(ctx context.Context, symbol string, primaryExchange string) (int, error)

RequestMarketDataWithPrimary subscribes to market data with an explicit primary-exchange hint. ctx must be non-nil and bounds the wait for market-data slot admission. Pass context.Background when the caller does not need cancellation.

func (*Connection) RequestOptionsMarketData ¶

func (c *Connection) RequestOptionsMarketData(ctx context.Context, symbol string, expiry string, strike float64, right string) (int, error)

RequestOptionsMarketData subscribes to market data for an option contract. ctx cancellation aborts the contract-resolution round trip, which would otherwise block up to 5 s × N exchange attempts even if the caller has already given up.

func (*Connection) RequestPnL ¶

func (c *Connection) RequestPnL(reqID int, account, modelCode string) error

RequestPnL starts a reqPnL stream for account using reqID. modelCode is empty for accounts without a Financial Advisor model. The caller owns reqID, response handling, and cancellation; Connector.SubscribeAccountPnL provides those lifecycle and caching responsibilities.

func (*Connection) RequestPnLSingle ¶

func (c *Connection) RequestPnLSingle(reqID int, account, modelCode string, conID int) error

RequestPnLSingle starts a reqPnLSingle stream for conID on account using reqID. modelCode is empty for accounts without a Financial Advisor model. The caller owns request-ID correlation, response handling, and cancellation; Connector.SubscribePositionDailyPnL provides those responsibilities.

func (*Connection) RequestPositions ¶

func (c *Connection) RequestPositions() error

RequestPositions requests current positions via the one-shot reqPositions wire path. Library-callable; the daemon prefers the streaming portfolio path through Connector.CachedPositions backed by RequestAccountUpdates (no reqPositions round-trip on the read path — see doc.go). Kept here so downstream callers that bypass Connector can still drive the alternate path. Pairs with WaitForPositionsEnd.

func (*Connection) RequestSecDefOptParams ¶

func (c *Connection) RequestSecDefOptParams(underlyingSymbol, futFopExchange, underlyingSecType string, underlyingConId int, beforeSend func(int)) (int, error)

RequestSecDefOptParams issues msg 78 (reqSecDefOptParams) to enumerate the option chain (expirations + strikes) for an underlying. The IBKR wire format (verified against ibapi.client.EClient.reqSecDefOptParams) has no version field — six total fields: msgID, reqID, underlyingSymbol, futFopExchange (empty for STK options), underlyingSecType, underlyingConId. The beforeSend callback runs after the reqID is allocated but before the message hits the wire so callers can register their per-request handler atomically.

func (*Connection) ServerVersion ¶

func (c *Connection) ServerVersion() int

ServerVersion returns the protocol version negotiated with TWS or IB Gateway. It returns zero before a handshake completes.

func (*Connection) SetMarketDataType ¶

func (c *Connection) SetMarketDataType(dataType int) error

SetMarketDataType sets the market data type (live, delayed, etc.)

func (*Connection) SetOnConnect ¶

func (c *Connection) SetOnConnect(fn func())

SetOnConnect replaces the callback invoked after a successful connection.

func (*Connection) SetOnDisconnect ¶

func (c *Connection) SetOnDisconnect(fn func(error))

SetOnDisconnect replaces the callback invoked after a connection is lost.

func (*Connection) SetPacketLogger ¶

func (c *Connection) SetPacketLogger(logger PacketLogger)

SetPacketLogger installs a packet logger invoked for every outbound frame. Passing nil disables logging. Frames may contain account IDs, order references, and order details; callers must protect the sink as sensitive data and use it only for short-lived debugging.

func (*Connection) SetSystemNoticeHandlerAtEpochWithPostAction ¶

func (c *Connection) SetSystemNoticeHandlerAtEpochWithPostAction(handler func(note *systemNotification, alias reqAliasEntry, epoch uint64) func())

SetSystemNoticeHandlerAtEpochWithPostAction is the Connector-facing form. The returned one-shot action runs only after Connection releases its inbound generation lease. This lets a current notice mark state atomically while deferring any outbound recovery frame until reconnect can no longer deadlock behind the reader. Its parameter types are unexported, so callers outside this package can only pass nil; the next major version unexports it.

func (*Connection) Status ¶

func (c *Connection) Status() ConnectionStatus

Status returns the current connection lifecycle state.

func (*Connection) UnregisterHandler ¶

func (c *Connection) UnregisterHandler(msgID int, handlerID uint64)

UnregisterHandler removes a previously registered handler for a message type.

func (*Connection) UsingTLS ¶

func (c *Connection) UsingTLS() bool

UsingTLS reports whether the established session negotiated TLS. When EnableTLSFallback flips the configured value, this exposes the actual mode.

func (*Connection) WaitForAccountSummaryEnd ¶

func (c *Connection) WaitForAccountSummaryEnd(timeout time.Duration) error

WaitForAccountSummaryEnd waits until an account-summary request completes or timeout elapses.

func (*Connection) WaitForPositionsEnd ¶

func (c *Connection) WaitForPositionsEnd(timeout time.Duration) error

WaitForPositionsEnd waits for the matching msgPositionEnd frame after a RequestPositions call. Library-callable companion to RequestPositions (daemon uses the streaming path; see RequestPositions for details).

func (ConnectionStatus) String ¶

func (s ConnectionStatus) String() string

String returns the uppercase name of s, or "UNKNOWN" for an unrecognized value.

func (*Connector) AccountDailyPnL ¶

func (c *Connector) AccountDailyPnL() (AccountDailyPnL, bool)

AccountDailyPnL returns the most recently received account Daily P&L snapshot. ok is false until Connector.SubscribeAccountPnL is active and a frame has been received. The method neither blocks nor issues wire traffic. Handlers replace snapshots rather than mutating their pointed-to values, so the returned shallow copy remains stable.

func (*Connector) AccountID ¶

func (c *Connector) AccountID() string

AccountID returns the account code most recently received from IBKR's managedAccounts frame. It returns an empty string before that frame is observed or when the connector has no connection.

func (*Connector) AccountSummaryRaw ¶

func (c *Connector) AccountSummaryRaw() map[string]string

AccountSummaryRaw returns a defensive copy of the connector's current raw account-summary cache. The map uses IBKR keys: bare tags for base-currency values and `<tag>_<currency>` for currency-specific values.

It is empty when no connection or observations are available, and also whenever the cache cannot be attributed to the session's expected account — the same admissibility rule CachedAccountSummary applies, because it is the same unstamped map. Emptiness alone does not describe connection state. The method is safe to call concurrently with streaming cache updates.

func (*Connector) ActiveDailyPnLSubscriptions ¶

func (c *Connector) ActiveDailyPnLSubscriptions() int

ActiveDailyPnLSubscriptions reports the number of tracked per-contract reqPnLSingle streams. It does not include the account-level reqPnL stream.

func (*Connector) BackendLinkStatus ¶ added in v2.8.2

func (c *Connector) BackendLinkStatus() (down bool, changedAt time.Time)

BackendLinkStatus reports the current TWS-to-IBKR upstream-link latch. It is intentionally separate from IsConnected/IsReady, which describe the local API socket and handshake. A code-1100 notice sets Down until a current session observes code 1101 or 1102.

func (*Connector) BeginDelayedMarketDataFallback ¶ added in v2.8.2

func (c *Connector) BeginDelayedMarketDataFallback(ctx context.Context, symbol string) (func(), error)

BeginDelayedMarketDataFallback temporarily changes subsequent market-data requests to IBKR delayed mode and force-refreshes symbol's rejected shared subscription. It is intentionally narrow: callers must have already observed a typed entitlement rejection and must release the returned lease after the bounded retry. Entitlement observations remain in-memory only.

IBKR returns live data even when type 3 was requested if the account is entitled to it. Otherwise it returns delayed ticks and names them through the per-request marketDataType notice. The lease restores the daemon's frozen-aware type-2 default unless this exact connection has since reported a competing live session, in which case delayed mode remains binding.

func (*Connector) CachedAccountSummary ¶

func (c *Connector) CachedAccountSummary() *RawAccountSummary

CachedAccountSummary returns a caller-owned typed snapshot of the connector's streaming account-summary cache, labeled with the account it belongs to. It does not issue gateway traffic and returns nil until at least one core account value has been observed, or whenever the cache is not admissible for the session's expected account. The method is safe to call concurrently with streaming cache updates.

func (*Connector) CachedPositions ¶

func (c *Connector) CachedPositions() ([]*RawPosition, error)

CachedPositions returns the latest filtered portfolio cache without issuing a positions request. The returned slice is detached, but its RawPosition pointers refer to cached rows and must be treated as read-only. Zero-quantity rows and stock placeholders with ConID zero are omitted. A disconnected Connector returns nil, nil; freshness is not implied by a non-empty result.

func (*Connector) CachedPositionsWithHealth ¶

func (c *Connector) CachedPositionsWithHealth() ([]*RawPosition, PortfolioStreamHealth, error)

CachedPositionsWithHealth returns the same read-only cached rows as Connector.CachedPositions together with the latest stream completion and heartbeat receipts. It performs no positions snapshot request; a typed account-scope conflict may trigger the throttled stream resubscribe behind the read. A disconnected Connector returns nil rows, zero health, and a nil error.

func (*Connector) CancelOptionIV ¶

func (c *Connector) CancelOptionIV(reqID int)

CancelOptionIV cancels an option-IV subscription previously returned by SubscribeOptionIV. Idempotent: zero reqID or an unknown reqID is a no-op. Best-effort on the wire — a failed CancelMarketData is logged but not returned, since the typical caller is a deferred cleanup.

Use this instead of UnsubscribeMarketData(symbol) for option-IV subscriptions: SubscribeOptionIV does not install a subscriptions[symbol] entry, so the symbol-scoped unsubscribe either no-ops or — worse — tears down an unrelated streaming-quote subscription for the same underlier.

func (*Connector) CancelOrder ¶

func (c *Connector) CancelOrder(orderID int) error

CancelOrder sends a cancellation for broker orderID. Default builds return ErrTradingDisabled. A successful return means the cancellation frame was sent, not that the broker confirmed the order cancelled.

func (*Connector) CancelOrderForSession ¶

func (c *Connector) CancelOrderForSession(binding ConnectorSessionBinding, orderID int) error

CancelOrderForSession sends a cancellation only on the exact Connector socket generation named by binding.

func (*Connector) CancelOrderForSessionGuarded ¶

func (c *Connector) CancelOrderForSessionGuarded(ctx context.Context, binding ConnectorSessionBinding, orderID int, guard func() error) error

CancelOrderForSessionGuarded carries caller cancellation and a final authority guard to the exact cancel frame.

func (*Connector) CancelPaperOrder ¶

func (c *Connector) CancelPaperOrder(gate PaperOrderGate, orderID int) error

CancelPaperOrder validates gate against the configured connection and sends a cancellation for broker orderID in a paper account. A successful return means the frame was sent, not that the broker confirmed cancellation.

func (*Connector) CancelPaperOrderForSession ¶

func (c *Connector) CancelPaperOrderForSession(binding ConnectorSessionBinding, gate PaperOrderGate, orderID int) error

CancelPaperOrderForSession validates gate and sends a paper cancellation only on the exact Connector socket generation named by binding.

func (*Connector) CancelPaperOrderForSessionGuarded ¶

func (c *Connector) CancelPaperOrderForSessionGuarded(ctx context.Context, binding ConnectorSessionBinding, gate PaperOrderGate, orderID int, guard func() error) error

CancelPaperOrderForSessionGuarded is the paper-gated counterpart to CancelOrderForSessionGuarded.

func (*Connector) CaptureBrokerEvidence ¶

func (c *Connector) CaptureBrokerEvidence() (BrokerEvidenceBinding, bool)

CaptureBrokerEvidence returns one stable broker-evidence frontier. False means the Connector is not a ready current session.

func (*Connector) CaptureHistoricalSession ¶

func (c *Connector) CaptureHistoricalSession() (HistoricalSessionBinding, bool)

CaptureHistoricalSession is the historical-data compatibility spelling for Connector.CaptureSession.

func (*Connector) CapturePortfolioProjectionForBoundSession ¶

func (c *Connector) CapturePortfolioProjectionForBoundSession(binding ConnectorSessionBinding) (PortfolioProjectionBinding, bool)

CapturePortfolioProjectionForBoundSession snapshots the structural portfolio authority without acquiring publicationBarrier or evidenceBarrier. It is only valid from a protected order wire guard while the transport owns publicationBarrier for reading and evidenceBarrier exclusively. Keeping this variant lock-free preserves the publication-then-evidence lock order.

func (*Connector) CapturePortfolioProjectionForSession ¶

func (c *Connector) CapturePortfolioProjectionForSession(binding ConnectorSessionBinding) (PortfolioProjectionBinding, bool)

CapturePortfolioProjectionForSession snapshots positions, health, and the structural generation while portfolio/session mutations are excluded. False means binding is stale or the Connector is not ready.

func (*Connector) CaptureSession ¶

func (c *Connector) CaptureSession() (ConnectorSessionBinding, bool)

CaptureSession returns the exact ready Connection object and socket epoch that may own a new broker-adjacent read. The token is process-local and is evidence for a later equality check, not durable readiness or authority.

func (*Connector) ContractDetailsFirst ¶

func (c *Connector) ContractDetailsFirst(ctx context.Context, contract Contract, timeout time.Duration) (*ContractDetailsLite, error)

ContractDetailsFirst returns the first contract-details row the gateway emits for contract. It does not apply option-candidate preference. A timeout of zero or less uses five seconds; context cancellation and send or timeout failures are returned to the caller.

func (*Connector) CurrencyLedgerSnapshot ¶

func (c *Connector) CurrencyLedgerSnapshot() map[string]CurrencyLedger

CurrencyLedgerSnapshot returns a caller-owned map derived from the connector's streaming account-summary cache. It neither blocks nor issues gateway traffic. An empty map means either no non-base exposure was observed or the cache is not populated yet; use connection state to distinguish them. The method is safe to call concurrently with streaming cache updates.

func (*Connector) DataFarmStatuses ¶

func (c *Connector) DataFarmStatuses() []DataFarmStatus

DataFarmStatuses returns a detached snapshot of the latest tracked farm notices, sorted by type and then name. It returns nil for a nil Connector; callers determine freshness from each entry's DataFarmStatus.AsOf.

func (*Connector) EnsureMarketDataSubscription ¶

func (c *Connector) EnsureMarketDataSubscription(ctx context.Context, symbol string, fields []string, staleAfter time.Duration) (bool, error)

EnsureMarketDataSubscription creates a live symbol subscription or refreshes one whose last observed tick is at least staleAfter old. A staleAfter value of zero or less disables age-based refresh. The boolean reports whether a new wire request was sent. ctx must be non-nil and bounds market-data slot acquisition; unavailable, inactive, entitlement, and request failures are returned.

func (*Connector) ExerciseOptions ¶

func (c *Connector) ExerciseOptions(ctx context.Context, req OptionExerciseRequest) error

ExerciseOptions sends an option exercise or lapse instruction through the connector's active connection. A zero TickerID is replaced with a new request ID. The method checks ctx only before sending and does not wait for broker acknowledgement; a nil error means only that the frame was accepted for the socket write. Once the call reaches an active Connection, the default build returns ErrTradingDisabled before validation or transmission.

func (*Connector) ExerciseOptionsForSession ¶

func (c *Connector) ExerciseOptionsForSession(ctx context.Context, binding ConnectorSessionBinding, req OptionExerciseRequest) error

ExerciseOptionsForSession sends an option exercise or lapse instruction only on the exact Connector socket generation named by binding. A reconnect or disconnect before request-ID reservation or frame transmission is refused.

func (*Connector) ExerciseOptionsForSessionGuarded ¶

func (c *Connector) ExerciseOptionsForSessionGuarded(ctx context.Context, binding ConnectorSessionBinding, req OptionExerciseRequest, guard func() error) error

ExerciseOptionsForSessionGuarded carries a final authority guard through pacing to the exact exercise/lapse socket write.

func (*Connector) FetchContractDetails ¶

func (c *Connector) FetchContractDetails(symbol string, timeout time.Duration) ([]ContractDetailsLite, error)

FetchContractDetails returns cached contract details for symbol when a resolved entry exists; otherwise it requests all matching rows and waits for the broker's completion marker. Identical in-flight requests are coalesced; each response handler still filters by request ID so unrelated contracts can resolve independently. On timeout it returns any rows already received together with ErrContractDetailsTimeout.

func (*Connector) FetchHistoricalDailyBars ¶

func (c *Connector) FetchHistoricalDailyBars(ctx context.Context, symbol string, lookbackDays int, timeout time.Duration) ([]HistoricalBar, error)

FetchHistoricalDailyBars requests daily bars for symbol and waits for the historical-data response. A lookbackDays value of zero or less uses 400 days; a timeout of zero or less uses 45 seconds. The earlier of timeout and the ctx deadline bounds both paced transmission and response waiting. Cancellation best-effort cancels an already-sent broker request.

func (*Connector) FetchHistoricalDailyBarsWhatToShow ¶

func (c *Connector) FetchHistoricalDailyBarsWhatToShow(ctx context.Context, symbol string, lookbackDays int, whatToShow string, timeout time.Duration) ([]HistoricalBar, error)

FetchHistoricalDailyBarsWhatToShow requests daily bars using the normalized IBKR whatToShow value supplied by the caller. It does not fall back to another feed, so returned bars retain the requested feed provenance. Context, lookback, and timeout semantics match Connector.FetchHistoricalDailyBars.

func (*Connector) FetchHistoricalDailyBarsWithContract ¶

func (c *Connector) FetchHistoricalDailyBarsWithContract(ctx context.Context, contract Contract, lookbackDays int, timeout time.Duration) ([]HistoricalBar, error)

FetchHistoricalDailyBarsWithContract requests daily bars using the routing fields already present on contract, including exchange, currency, local symbol, or ConID. Context, lookback, and timeout semantics match Connector.FetchHistoricalDailyBars.

func (*Connector) FetchHistoricalDailyFeeRates ¶

func (c *Connector) FetchHistoricalDailyFeeRates(ctx context.Context, contract Contract, lookbackDays int, timeout time.Duration) ([]HistoricalBar, error)

FetchHistoricalDailyFeeRates requests daily stock-borrow fee-rate bars for an exact broker contract. It is intentionally narrower than the general historical APIs: FEE_RATE is pinned and ConID is required. A missing executable exchange may be completed only by a bounded exact-ConID contract details read whose identity and route are strictly checked; the method never resolves by symbol, substitutes another ConID, or fabricates SMART. Concurrent identical requests share one open HMDS request, and its detached typed result is reused for IBKR's 15-second identical-request cooldown.

func (*Connector) FetchMarketSnapshot ¶

func (c *Connector) FetchMarketSnapshot(ctx context.Context, symbol string, timeout time.Duration) (*MarketSnapshot, error)

FetchMarketSnapshot requests a one-shot bid, ask, and last-price snapshot and waits for the broker's end marker. ctx must be non-nil. A timeout of zero or less uses five seconds. Context cancellation returns ctx.Err; timeout returns context.DeadlineExceeded. Both paths best-effort cancel the request and release its market-data slot. Inactive and unavailable connectors return ErrSymbolInactive and ErrIBKRUnavailable without sending a request.

func (*Connector) FetchOptionExpiries ¶

func (c *Connector) FetchOptionExpiries(symbol string, timeout time.Duration) ([]string, error)

FetchOptionExpiries returns a newly allocated, sorted, deduplicated list of option expiry dates for symbol in YYYY-MM-DD form. A timeout of zero or less uses ten seconds. If the timeout expires after at least one response, the partial list is returned without an error; an empty timeout returns an error. An unavailable or inactive Connector returns the corresponding sentinel.

func (*Connector) FetchOptionExpiryStrikes ¶

func (c *Connector) FetchOptionExpiryStrikes(symbol string, timeout time.Duration) (map[string][]float64, error)

FetchOptionExpiryStrikes returns newly allocated, sorted, deduplicated strike slices keyed by YYYY-MM-DD expiry. It merges strikes across exchanges and trading classes; callers that require class identity should use Connector.FetchOptionExpiryStrikesClassed. Timeout, partial-result, and availability semantics match Connector.FetchOptionExpiries.

func (*Connector) FetchOptionExpiryStrikesClassed ¶

func (c *Connector) FetchOptionExpiryStrikesClassed(symbol string, timeout time.Duration) (map[string][]ExpiryClassedStrikes, error)

FetchOptionExpiryStrikesClassed returns newly allocated strike grids grouped first by YYYY-MM-DD expiry and then by broker trading class. Both class entries and strikes are sorted. This preserves distinct contracts that share a date and strike but have different trading classes. Timeout, partial-result, and availability semantics match Connector.FetchOptionExpiries.

func (*Connector) FetchWSHEarnings ¶

func (c *Connector) FetchWSHEarnings(ctx context.Context, symbol string) (string, error)

FetchWSHEarnings returns the raw WSH earnings-event JSON for a stock symbol. It preserves the legacy symbol-resolution and temporary-inactive-cache behavior. Call Connector.FetchWSHEarningsWithIdentity when the caller has a positive held contract ID and needs fresh broker identity evidence.

func (*Connector) FetchWSHEarningsWithIdentity ¶

func (c *Connector) FetchWSHEarningsWithIdentity(ctx context.Context, symbol string, conID int) (WSHEarningsResult, error)

FetchWSHEarningsWithIdentity reads WSH earnings events using a caller-proven positive held contract ID and independently attempts an exact contract- details lookup by that ID. A symbol-level temporary inactive mark does not suppress this exact lookup. If exact details are unavailable or contradict the request, the event read may still succeed but StockIdentity remains nil; callers must not infer issuer classification from the supplied ID or cache.

func (*Connector) HistoricalSessionCurrent ¶

func (c *Connector) HistoricalSessionCurrent(binding HistoricalSessionBinding) bool

HistoricalSessionCurrent is the historical-data compatibility spelling for Connector.SessionCurrent.

func (*Connector) InactiveReason ¶

func (c *Connector) InactiveReason(symbol string) (string, bool)

InactiveReason reports an unexpired in-memory inactivity mark for symbol. It performs no broker request. The boolean is false when no mark exists or the mark has expired; the returned reason is untrusted broker text.

func (*Connector) IsConnected ¶

func (c *Connector) IsConnected() bool

IsConnected reports whether the Connector currently has an active broker connection. It does not imply that response handlers are ready; use Connector.IsReady when issuing requests.

func (*Connector) IsOptionContractCached ¶

func (c *Connector) IsOptionContractCached(symbol, tradingClass, expiry string, strike float64, right string) bool

IsOptionContractCached reports whether the active connection has a resolved option entry matching symbol, tradingClass, expiry, strike, and right. Symbol, tradingClass, and right are trimmed and matched case-insensitively; expiry is trimmed, while strike is encoded to six decimal places. It returns false when no connection is attached or the matching entry has a zero ConID.

func (*Connector) IsReady ¶

func (c *Connector) IsReady() bool

IsReady reports whether the broker connection is established and the Connector's response handlers are registered.

func (*Connector) IsSymbolInactive ¶

func (c *Connector) IsSymbolInactive(symbol string) bool

IsSymbolInactive reports whether symbol has an unexpired in-memory inactivity mark. It performs no broker request.

func (*Connector) LastError ¶

func (c *Connector) LastError() string

LastError returns the most recent connector startup error that left the connector in degraded mode. Empty means either healthy or no concrete connector-level diagnosis is available.

func (*Connector) MarketDataAbsences ¶ added in v2.8.0

func (c *Connector) MarketDataAbsences() []MarketDataAbsenceError

MarketDataAbsences snapshots every route key whose terminal entitlement rejection is still inside its retry window, ordered by key. Expired records are dropped on read exactly as marketDataAbsenceFor drops them, so an observation surface can never name a key the subscribe paths would already let through. Message stays untrusted broker text; callers that classify must read Code.

func (*Connector) MarketDataSnapshot ¶

func (c *Connector) MarketDataSnapshot() map[string]*MarketData

MarketDataSnapshot returns a detached point-in-time copy of all locally tracked streaming subscriptions. The returned map and MarketData values may be mutated by the caller. Zero fields can represent data not yet observed. Timestamp carries the subscription's bookkeeping clock, which is seeded at subscribe time; LastTickAt is the any-tick liveness clock; LastPriceTickAt is the accepted-price observation clock. The latter two are zero until their respective tick class arrives. None guarantees broker-source freshness.

func (*Connector) MarketDataTypeForSymbol ¶

func (c *Connector) MarketDataTypeForSymbol(symbol string) int

MarketDataTypeForSymbol returns the latest gateway data-type notice for the symbol's active subscription: 1=live, 2=frozen, 3=delayed, 4=delayed-frozen, or 0 when the subscription or notice is absent.

func (*Connector) MaybeResubscribeStaleDailyPnL ¶

func (c *Connector) MaybeResubscribeStaleDailyPnL(marketOpen bool) bool

MaybeResubscribeStaleDailyPnL rebuilds all Daily P&L streams when marketOpen is true and the account stream has not produced its first frame or its last frame is stale. The caller owns the market calendar; off-hours inactivity is not treated as stale. It returns true when a rebuild attempt is issued, not when a replacement frame is received. Attempts are throttled to one per internal staleness window.

func (*Connector) OptionGreeks ¶

func (c *Connector) OptionGreeks(symbol string) (Greeks, bool)

OptionGreeks returns the last valid model-computation Greeks for an option key returned by Connector.SubscribeOption. The boolean is false until at least one field has been observed; callers must not interpret absence as a zero-valued Greek. The returned value is a copy.

func (*Connector) OptionIV ¶

func (c *Connector) OptionIV(symbol string) (float64, bool)

OptionIV returns the last valid implied-volatility observation for key as a fraction, such as 0.30 for 30 percent. The boolean is false when no valid observation has been cached; the method performs no broker request.

func (*Connector) OptionIVWithDataType ¶ added in v2.8.2

func (c *Connector) OptionIVWithDataType(symbol string) (iv float64, dataType int, ok bool)

OptionIVWithDataType returns the last valid implied-volatility observation together with the IBKR model-computation source type. dataType is 1 for tick 13, 3 for delayed tick 83, and 0 when IV came from an untyped generic tick. Callers that require clock alignment must reject 0 rather than infer.

func (*Connector) OptionPrevClose ¶

func (c *Connector) OptionPrevClose(symbol string) (float64, bool)

OptionPrevClose returns the option contract's own previous regular-session close, not the underlying's close. The boolean is false when no positive value has been observed.

func (*Connector) OptionQuoteBidAsk ¶

func (c *Connector) OptionQuoteBidAsk(symbol string) (bid, ask float64, ok bool)

OptionQuoteBidAsk returns the last observed bid and ask for an option key. It returns (0, 0, false) when neither side has been observed; one-sided results return true with the absent side left at zero. The method performs no broker request and does not itself determine freshness.

func (*Connector) OptionUnderlyingPrice ¶

func (c *Connector) OptionUnderlyingPrice(symbol string) (float64, bool)

OptionUnderlyingPrice returns the underlying price embedded in the latest model-computation tick for an option key. The boolean is false when no valid price has been observed. This is the price the broker used for the associated Greeks.

func (*Connector) OrderLifecycleGeneration ¶

func (c *Connector) OrderLifecycleGeneration() uint64

OrderLifecycleGeneration returns the current connection-local order-event frontier without issuing a broker request. Zero means no accepted lifecycle callback has been observed by this Connector.

func (*Connector) PortfolioProjectionGeneration ¶

func (c *Connector) PortfolioProjectionGeneration() uint64

PortfolioProjectionGeneration returns the current structural portfolio frontier without issuing a broker request. It advances for scope, completeness, contract-set, or quantity changes, but not mark/PnL-only updates.

func (*Connector) PositionDailyPnL ¶

func (c *Connector) PositionDailyPnL(conID int) (PositionDailyPnL, bool)

PositionDailyPnL returns the cached per-contract Daily P&L snapshot for conID. ok is false when no subscription exists. ok may be true while all value pointers are nil, meaning the stream is active but has not supplied usable values. The method neither blocks nor issues wire traffic. Handlers replace snapshots rather than mutating their pointed-to values, so the returned shallow copy remains stable.

func (*Connector) PreviewOrderWhatIf ¶

func (c *Connector) PreviewOrderWhatIf(ctx context.Context, contract *Contract, order *RawOrder) (OrderWhatIfResult, error)

PreviewOrderWhatIf sends a broker WhatIf preview for a connector-level contract/order pair. Nil inputs fail validation. It does not mutate order or add to Connector.openOrders because no working order should exist. Status and error behavior match Connection.PreviewOrderWhatIf.

func (*Connector) PreviewOrderWhatIfForSession ¶

func (c *Connector) PreviewOrderWhatIfForSession(ctx context.Context, binding ConnectorSessionBinding, contract *Contract, order *RawOrder) (OrderWhatIfResult, error)

PreviewOrderWhatIfForSession is PreviewOrderWhatIf constrained to the exact connector socket generation captured by binding.

func (*Connector) PreviewOrderWhatIfWithOrderID ¶

func (c *Connector) PreviewOrderWhatIfWithOrderID(ctx context.Context, contract *Contract, order *RawOrder, orderID int) (OrderWhatIfResult, error)

PreviewOrderWhatIfWithOrderID sends a broker WhatIf preview using a positive, caller-supplied broker order ID. This supports evaluating a replacement draft for a tracked order, but does not modify that order or grant authority to do so. Status and error behavior match Connection.PreviewOrderWhatIf.

func (*Connector) PreviewOrderWhatIfWithOrderIDForSession ¶

func (c *Connector) PreviewOrderWhatIfWithOrderIDForSession(ctx context.Context, binding ConnectorSessionBinding, contract *Contract, order *RawOrder, orderID int) (OrderWhatIfResult, error)

PreviewOrderWhatIfWithOrderIDForSession is PreviewOrderWhatIfWithOrderID constrained to the exact connector socket generation captured by binding.

func (*Connector) PrewarmOptionChain ¶

func (c *Connector) PrewarmOptionChain(
	ctx context.Context,
	symbol string,
	expiries []string,
	tradingClass string,
	timeout time.Duration,
) []PrewarmOptionChainResult

PrewarmOptionChain resolves and caches option contracts for each expiry in a symbol and trading-class pair. It returns one result per expiry with cache counts, duration, and any error. The call returns nil when disconnected; ctx and timeout bound the underlying bulk requests. Later Connector.SubscribeOption calls can reuse the resolved contract identities.

func (*Connector) RefreshPositions ¶

func (c *Connector) RefreshPositions(timeout time.Duration) ([]*RawPosition, error)

RefreshPositions issues the broker's singleton positions request, waits up to timeout for its end marker, and returns the filtered cache shape described by Connector.CachedPositions. Because the protocol supplies no request ID, callers must serialize refreshes.

func (*Connector) RegisterOrderLifecycleHandler ¶

func (c *Connector) RegisterOrderLifecycleHandler(handler func(OrderLifecycleEvent))

RegisterOrderLifecycleHandler appends a compatibility callback for broker order lifecycle messages. Callbacks run synchronously in registration order and must return quickly. A nil Connector or handler is ignored.

func (*Connector) RegisterOrderLifecycleReceiptHandler ¶

func (c *Connector) RegisterOrderLifecycleReceiptHandler(handler func(OrderLifecycleReceipt))

RegisterOrderLifecycleReceiptHandler appends a callback that receives the exact socket-session receipt for every event.

func (*Connector) RequestAccountSummary ¶

func (c *Connector) RequestAccountSummary(ctx context.Context, timeout time.Duration) (*RawAccountSummary, error)

RequestAccountSummary issues a synchronous reqAccountSummary request and returns a caller-owned parsed snapshot. ctx must be non-nil. The call blocks until the gateway emits accountSummaryEnd, ctx is cancelled, or timeout elapses.

Behavior:

• Returns ErrIBKRUnavailable immediately if the connector is not connected; no network traffic is generated.
• On timeout the request is cancelled (cancelAccountSummary sent) so the gateway does not continue streaming updates against the consumed reqID.
• timeout <= 0 falls back to defaultAccountSummaryTimeout (5s).

The method is safe to call concurrently; each invocation uses a fresh request ID and normally reads only that request's rows. If the gateway emits an end marker without rows, it falls back to a defensive copy of the streaming account-updates cache.

func (*Connector) RequestAccountSummaryWithProvenance ¶

func (c *Connector) RequestAccountSummaryWithProvenance(ctx context.Context, timeout time.Duration) (*RawAccountSummary, AccountSummaryProvenance, error)

RequestAccountSummaryWithProvenance preserves RequestAccountSummary's fallback behavior while exposing whether the gateway actually supplied rows for this request. CachedFallback has no trustworthy source receipt even though parsing gives the caller-owned copy an AsOf timestamp.

func (*Connector) RequestAccountUpdates ¶

func (c *Connector) RequestAccountUpdates(account string) error

RequestAccountUpdates starts the singleton streaming account and portfolio subscription used by Connector.CachedPositions. Pass an empty or aggregate account value to resolve a concrete managed account from the connection.

Aggregate values ("All", comma-separated managedAccounts lists) are not account codes — TWS rejects them with error 321 and the portfolio stream never starts. They are reduced to a concrete code (or to "", which TWS resolves itself for single-account logins) before hitting the wire.

func (*Connector) ReserveOrderID ¶

func (c *Connector) ReserveOrderID() (int, error)

ReserveOrderID claims the next broker order ID without submitting an order. Default builds return ErrTradingDisabled. The ID is consumed locally and should be passed to a later Connector.SubmitOrder call.

func (*Connector) ReserveOrderIDForSession ¶

func (c *Connector) ReserveOrderIDForSession(binding ConnectorSessionBinding) (int, error)

ReserveOrderIDForSession claims the next broker order ID from the exact socket generation named by binding. The reservation remains tied to that epoch and cannot authorize a later-session submission.

func (*Connector) ResolveExactHistoricalStockRoute ¶

func (c *Connector) ResolveExactHistoricalStockRoute(ctx context.Context, contract Contract, timeout time.Duration) (Contract, error)

ResolveExactHistoricalStockRoute completes a missing executable exchange only through an exact positive-ConID contract-details request. It rejects wrong, missing, or ambiguous broker details and never resolves by symbol or substitutes a default route. Callers may retain their original position identity separately from the returned route used on the wire.

func (*Connector) ResolveOrderContractForSession ¶

func (c *Connector) ResolveOrderContractForSession(ctx context.Context, binding ConnectorSessionBinding, contract Contract, timeout time.Duration) (ResolvedOrderContract, error)

ResolveOrderContractForSession resolves a symbol/option description to one exact positive-ConID identity. Epoch-aware handlers and an epoch-bound request prevent a callback from a retired socket completing a new preview.

func (*Connector) ResolveWSHStockIdentity ¶

func (c *Connector) ResolveWSHStockIdentity(ctx context.Context, symbol string, conID int) (*ContractDetailsLite, error)

ResolveWSHStockIdentity independently reads exact broker contract details for a caller-proven positive held contract ID. It deliberately bypasses the symbol-level temporary inactive cache and does not make a WSH metadata or event request. All failures are returned as sanitized WSH errors.

func (*Connector) RunScannerParameters ¶

func (c *Connector) RunScannerParameters(ctx context.Context, timeout time.Duration) (*ScannerParameters, error)

RunScannerParameters fetches and parses the gateway's scanner catalog. ctx must be non-nil, and a timeout of zero or less uses ten seconds. The returned value owns its typed slices and preserves the exact broker XML in RawXML. Because this broker request has no request ID, callers should serialize concurrent catalog requests.

func (*Connector) RunScannerSubscription ¶

func (c *Connector) RunScannerSubscription(ctx context.Context, sub ScannerSubscription, timeout time.Duration) ([]ScannerRow, error)

RunScannerSubscription starts a scanner subscription, returns a newly allocated copy of the first result frame, and then cancels the subscription. ctx must be non-nil. A timeout of zero or less uses 20 seconds. Context cancellation, timeout, request failures, and request-scoped broker errors are returned; informational farm notices do not fail the call.

func (*Connector) SeedAccountDailyPnLForTest ¶

func (c *Connector) SeedAccountDailyPnLForTest(account string, snap AccountDailyPnL)

SeedAccountDailyPnLForTest installs an account-level snapshot without wire traffic. It is intended only for tests outside package ibkr.

func (*Connector) SeedAccountIDForTest ¶

func (c *Connector) SeedAccountIDForTest(account string)

SeedAccountIDForTest installs the managed-account code returned by Connector.AccountID. It is intended only for tests outside package ibkr; runtime callers must obtain the value from IBKR.

func (*Connector) SeedContractDetails ¶

func (c *Connector) SeedContractDetails(symbol string, detail ContractDetailsLite) bool

SeedContractDetails adds a caller-supplied contract to the Connector's in-memory cache when symbol is non-empty, detail has a non-zero ConID, and no resolved entry is already cached for that symbol. It never replaces a live resolved entry and performs no broker request. The result reports whether the seed was applied.

func (*Connector) SeedOptionContracts ¶

func (c *Connector) SeedOptionContracts(options map[string]ContractDetailsLite) int

SeedOptionContracts copies resolved entries into the active connection's option cache and returns the number inserted. Entries with a zero ConID are ignored, and an existing resolved entry always wins. The input map is not retained or mutated. It returns zero when no connection is attached.

func (*Connector) SeedPositionDailyPnLForTest ¶

func (c *Connector) SeedPositionDailyPnLForTest(conID int, snap PositionDailyPnL)

SeedPositionDailyPnLForTest installs snap for conID without wire traffic and marks that contract as subscribed. It is intended only for tests outside package ibkr; runtime callers must use Connector.SubscribePositionDailyPnL.

func (*Connector) ServerVersion ¶

func (c *Connector) ServerVersion() int

ServerVersion returns the IBKR server protocol version reported by the gateway during the handshake. Returns 0 when no connection is established.

func (*Connector) SessionCurrent ¶

func (c *Connector) SessionCurrent(binding ConnectorSessionBinding) bool

SessionCurrent reports whether binding still names this Connector's ready Connection and exact socket epoch.

func (*Connector) SessionReceiptCurrent ¶

func (c *Connector) SessionReceiptCurrent(binding ConnectorSessionBinding) bool

SessionReceiptCurrent reports whether binding names the Connector's exact installed inbound socket generation. Connecting is accepted because startAPI synchronously processes a small frame burst before onConnect; disconnected/failed/reconnecting states are never current. This does not authorize outbound requests.

func (*Connector) SetMarketDataType ¶

func (c *Connector) SetMarketDataType(dataType int) error

SetMarketDataType requests the market-data mode for subsequent requests: 1=live, 2=frozen, 3=delayed, and 4=delayed-frozen. A live request is reduced to delayed mode when the connection has detected a competing live session. It returns an error when no broker connection is active or the write fails.

func (*Connector) SnapshotContracts ¶

func (c *Connector) SnapshotContracts() map[string]ContractDetailsLite

SnapshotContracts returns a caller-owned copy of the connector's resolved ordinary-contract cache. Entries with a zero ConID are omitted. Concurrent cache updates are synchronized, and mutating the returned map does not affect the connector.

func (*Connector) SnapshotOpenOrders ¶

func (c *Connector) SnapshotOpenOrders(ctx context.Context) (OpenOrderSnapshot, error)

SnapshotOpenOrders joins or starts one epoch-bound reqAllOpenOrders flight. Caller cancellation only stops that waiter; after the wire request begins, the collector remains installed until same-epoch openOrderEnd or the internal protocol deadline. This is required because the protocol has no request ID and a late terminator could otherwise bless a later flight.

A canceled waiter issues no late request. A protocol timeout or uncertain send poisons only the exact Connection epoch; callers fail closed until a reconnect advances that epoch.

func (*Connector) SnapshotOptionContracts ¶

func (c *Connector) SnapshotOptionContracts() map[string]ContractDetailsLite

SnapshotOptionContracts returns a caller-owned copy of the active connection's resolved option-contract cache, keyed by normalized symbol, trading class, expiry, strike, and right. Entries with a zero ConID are omitted. It returns nil when no connection is attached. Concurrent cache updates are synchronized, and mutating the returned map does not affect the connection.

func (*Connector) Start ¶

func (c *Connector) Start(ctx context.Context) error

Start attaches lifecycle handlers and attempts to open the Connector's broker connection. It returns an error when already started. An initial connection failure leaves the Connector running but not ready and is exposed through Connector.LastError, so that failure does not make Start fail. Context cancellation bounds the connection attempt.

func (*Connector) Stop ¶

func (c *Connector) Stop() error

Stop marks the Connector stopped, cancels its P&L subscriptions, and closes the broker connection. It is idempotent. The Connector remains a valid value after Stop; later method calls report unavailable state or no-op as defined by each method.

func (*Connector) SubmitOrder ¶

func (c *Connector) SubmitOrder(contract *Contract, order *RawOrder) error

SubmitOrder sends an unrestricted order through the active broker connection. Default builds return ErrTradingDisabled before transmission; builds with the "trading" tag enable the wire path. A successful return means the frame was sent, not that the broker accepted or filled the order.

func (*Connector) SubmitOrderForSession ¶

func (c *Connector) SubmitOrderForSession(binding ConnectorSessionBinding, contract *Contract, order *RawOrder) error

SubmitOrderForSession sends an unrestricted order only on the exact Connector socket generation named by binding. The binding must have been captured from this Connector; reconnect or disconnect drift is rejected at allocator claim and again at the transport boundary before any wire write.

func (*Connector) SubmitOrderForSessionGuarded ¶

func (c *Connector) SubmitOrderForSessionGuarded(ctx context.Context, binding ConnectorSessionBinding, contract *Contract, order *RawOrder, guard func() error) error

SubmitOrderForSessionGuarded carries caller cancellation and a final authority guard to the exact socket write. guard runs under the connection transport lock after pacing and epoch checks, immediately before any byte.

func (*Connector) SubmitPaperOrder ¶

func (c *Connector) SubmitPaperOrder(gate PaperOrderGate, contract *Contract, order *RawOrder) error

SubmitPaperOrder validates gate against the configured connection and sends an order to a paper account. It is available in default builds without enabling Connector.SubmitOrder. A successful return means the frame was sent, not that the broker accepted or filled the order.

func (*Connector) SubmitPaperOrderForSession ¶

func (c *Connector) SubmitPaperOrderForSession(binding ConnectorSessionBinding, gate PaperOrderGate, contract *Contract, order *RawOrder) error

SubmitPaperOrderForSession validates gate and sends a paper order only on the exact Connector socket generation named by binding.

func (*Connector) SubmitPaperOrderForSessionGuarded ¶

func (c *Connector) SubmitPaperOrderForSessionGuarded(ctx context.Context, binding ConnectorSessionBinding, gate PaperOrderGate, contract *Contract, order *RawOrder, guard func() error) error

SubmitPaperOrderForSessionGuarded is the paper-gated counterpart to SubmitOrderForSessionGuarded.

func (*Connector) SubscribeAccountPnL ¶

func (c *Connector) SubscribeAccountPnL(account string) error

SubscribeAccountPnL starts and caches a streaming reqPnL subscription for account. account must be non-empty. Repeated calls for the same account are idempotent; changing the account cancels the previous stream, clears its cached snapshot, and starts a new one. Connector.Stop cancels the active stream. Use Connector.AccountDailyPnL for non-blocking cache reads. Callers must serialize attempts to switch one connector between different accounts.

func (*Connector) SubscribeMarketData ¶

func (c *Connector) SubscribeMarketData(ctx context.Context, symbol string, fields []string) error

SubscribeMarketData ensures a symbol-keyed streaming subscription exists. Repeating the call for the same normalized symbol is a no-op, including from concurrent callers. ctx must be non-nil and bounds acquisition of a market-data slot. fields is retained as subscription metadata; the wire tick set is selected by the Connector. The slice is not copied and must not be mutated while subscribed. When disconnected, the method records a local subscription with no live request. Use Connector.UnsubscribeMarketData for cleanup.

func (*Connector) SubscribeMarketDataWithContract ¶

func (c *Connector) SubscribeMarketDataWithContract(ctx context.Context, contract Contract, fields []string) (string, error)

SubscribeMarketDataWithContract ensures a streaming subscription exists for an explicitly routed contract and returns its MarketDataKeyForContract key. Repeating the same route is a no-op. ctx must be non-nil and bounds slot acquisition. fields is retained as metadata; the Connector selects the wire tick set. The slice is not copied and must not be mutated while subscribed. When disconnected, it records a local subscription with ReqID zero.

func (*Connector) SubscribeMarketDataWithContractForSession ¶

func (c *Connector) SubscribeMarketDataWithContractForSession(ctx context.Context, binding ConnectorSessionBinding, contract Contract, fields []string) (string, error)

SubscribeMarketDataWithContractForSession creates a short-lived, non-sharing subscription for one exact positive-ConID contract, or one explicit CASH/IDEALPRO currency pair, on binding's physical socket. The unique key prevents a symbol/route cache entry from a different contract or socket satisfying broker-write evidence.

func (*Connector) SubscribeOption ¶

func (c *Connector) SubscribeOption(ctx context.Context, underlying, tradingClass, expiryYMD string, strike float64, right string) (string, int, error)

SubscribeOption ensures a streaming subscription exists for a fully specified option contract. expiryYMD uses YYYYMMDD and right uses C or P. An empty tradingClass defaults to the normalized underlying; callers handling multiple classes for one underlying must supply the class explicitly. The returned key addresses cached values in Connector.MarketDataSnapshot, and the request ID identifies the live subscription. ctx bounds contract resolution and slot acquisition.

func (*Connector) SubscribeOptionIV ¶

func (c *Connector) SubscribeOptionIV(ctx context.Context, symbol string, expiry time.Time, strike float64, right string) (int, error)

SubscribeOptionIV starts an option market-data subscription and routes model-computation IV to the normalized underlying key read by Connector.OptionIV. expiry is converted to a UTC YYYYMMDD date and right is normalized to upper case. ctx bounds contract resolution and slot acquisition. Pair the returned request ID with Connector.CancelOptionIV.

func (*Connector) SubscribeOptionIVKeyed ¶

func (c *Connector) SubscribeOptionIVKeyed(ctx context.Context, symbol string, expiry time.Time, strike float64, right string) (int, string, error)

SubscribeOptionIVKeyed starts one option market-data subscription and routes model IV to the returned per-contract key. Use the key with Connector.OptionIV and the request ID with Connector.CancelOptionIV. Unlike Connector.SubscribeOptionIV, concurrent legs for one underlying do not overwrite one shared underlying-keyed value.

func (*Connector) SubscribePositionDailyPnL ¶

func (c *Connector) SubscribePositionDailyPnL(account string, conID int) error

SubscribePositionDailyPnL starts and caches a reqPnLSingle stream for conID on account. account must be non-empty and conID must be positive. Streams are keyed by conID, so repeated calls for an already subscribed contract are idempotent. Connector.Stop cancels all active position streams. The method returns ErrIBKRUnavailable when the connector is disconnected. One connector must not reuse the same conID for different accounts.

func (*Connector) SubscriptionRejectCh ¶

func (c *Connector) SubscriptionRejectCh(key string) <-chan SubscriptionRejection

SubscriptionRejectCh returns the terminal-rejection channel for a tracked subscription key. The channel may receive at most one pending rejection and is not closed when the subscription ends. It returns nil when the key is not tracked or rejection signaling is unavailable; a nil channel can be used directly in a select to disable that case.

func (*Connector) UnsubscribeMarketData ¶

func (c *Connector) UnsubscribeMarketData(symbol string) error

UnsubscribeMarketData removes the normalized symbol or route key from the local subscription cache and best-effort cancels its live broker request. It is idempotent when no matching subscription exists. For routed subscriptions, pass the key returned by Connector.SubscribeMarketDataWithContract.

func (*Connector) UnsubscribeMarketDataForSession ¶

func (c *Connector) UnsubscribeMarketDataForSession(ctx context.Context, binding ConnectorSessionBinding, key string) error

UnsubscribeMarketDataForSession removes only the exact subscription created on binding and emits a cancel solely when that physical socket is still current. A retired cleanup can never cancel a successor subscription.

func (*Connector) UsingTLS ¶

func (c *Connector) UsingTLS() bool

UsingTLS reports the TLS mode the active session negotiated. False when disconnected or when a non-TLS handshake succeeded (possibly via fallback).

func (*Connector) WithBoundBrokerSession ¶

func (c *Connector) WithBoundBrokerSession(binding ConnectorSessionBinding, operation func() error) (bool, error)

WithBoundBrokerSession admits operation only when binding names the current Connector socket session. It deliberately does not hold publication while operation waits in pacing or on a paused transport. Protected transports acquire the publication read side only for their final guarded write, where the exact Connection epoch remains the final pre-wire authority. False means binding was not current and operation was not called.

func (*Connector) WithBrokerEvidenceMutation ¶

func (c *Connector) WithBrokerEvidenceMutation(change func())

WithBrokerEvidenceMutation serializes an external owner-published identity change after all in-flight Connector evidence dispatch and exact-session broker operations have drained. It exists for daemon connector publication only; it does not authorize broker activity.

func (*Connector) WithStableBrokerEvidence ¶

func (c *Connector) WithStableBrokerEvidence(binding BrokerEvidenceBinding, commit func() bool) bool

WithStableBrokerEvidence executes commit while structural portfolio/session writers and order lifecycle dispatch are excluded. It returns false without calling commit when binding is no longer exact.

func (*ContractStore) Load ¶

func (s *ContractStore) Load() (map[string]ContractDetailsLite, string, error)

Load returns a caller-owned symbol-to-contract map and the membership hash stored with it. Calls are serialized with ContractStore.Save. A nil store, missing payload, or newer legacy-file envelope returns (nil, "", nil) as a cold cache. Read and decode failures return an error. Older legacy envelopes are accepted; attached authorities are validated as current by ContractStore.UseAuthority.

func (*ContractStore) LoadOptions ¶

func (s *ContractStore) LoadOptions() (map[string]ContractDetailsLite, error)

LoadOptions returns a caller-owned option-key-to-contract map. Options whose expiry precedes the current New York date are omitted from the returned snapshot without rewriting persistence. Legacy keys without a trading class are migrated in memory to an empty class segment; malformed legacy keys are skipped. A nil store, missing payload, newer legacy envelope, or a snapshot containing no live options returns an empty non-nil map. Read and decode failures return an error. Calls are serialized with ContractStore.Save.

func (*ContractStore) Save ¶

func (s *ContractStore) Save(contracts map[string]ContractDetailsLite, options map[string]ContractDetailsLite, membersHash string) error

Save publishes one filtered contract-cache snapshot. It copies its map inputs and does not mutate them. Contracts with a zero ConID and options expired before the current New York date are omitted. Every option key and value must form a valid, matching tuple; otherwise Save returns an error without publishing. membersHash may be empty when membership is not tracked.

Calls on one store are serialized. An attached authority receives one encoded envelope; the legacy codec writes a temporary file and renames it over dir/contracts.json.

func (*ContractStore) UseAuthority ¶

func (s *ContractStore) UseAuthority(authority ContractCacheAuthority) error

UseAuthority validates authority's current payload and, on success, switches all subsequent loads and saves to it. A missing payload is a valid cold start. A nil store, nil authority, load failure, or invalid current envelope returns an error and leaves the existing backend unchanged. UseAuthority does not import or merge the legacy JSON file.

func (*HexPacketLogger) Close ¶

func (l *HexPacketLogger) Close() error

Close releases the underlying file handle.

func (*HexPacketLogger) Outbound ¶

func (l *HexPacketLogger) Outbound(label string, payload []byte)

Outbound logs a payload if the logger is still active.

func (*HistoricalDataValidationError) Error ¶

func (e *HistoricalDataValidationError) Error() string

Error returns a fixed connector-authored description and the allowlisted reason token; it never returns raw broker payload text.

func (*HistoricalRequestError) Error ¶

func (e *HistoricalRequestError) Error() string

Error returns the broker message when present, otherwise a code-based historical-data error description.

func (*MarketDataAbsenceError) Error ¶

func (e *MarketDataAbsenceError) Error() string

Error returns a concise description of the suppressed market-data request.

func (*RateLimiter) AcquireMarketDataSlot ¶

func (rl *RateLimiter) AcquireMarketDataSlot(ctx context.Context) error

AcquireMarketDataSlot acquires a market data subscription slot

func (*RateLimiter) GetMetrics ¶

func (rl *RateLimiter) GetMetrics() RateLimiterMetrics

GetMetrics returns current rate limiter metrics

func (*RateLimiter) ReleaseMarketDataSlot ¶

func (rl *RateLimiter) ReleaseMarketDataSlot()

ReleaseMarketDataSlot releases a market data subscription slot

func (*RateLimiter) Stop ¶

func (rl *RateLimiter) Stop()

Stop gracefully shuts down the rate limiter. The request queue is not closed: producers (Submit and the retry goroutine) race with shutdown and would panic on send to a closed channel. Instead, ctx cancellation signals both producers and consumers to exit, and the queue is GC'd once unreferenced.

func (*RateLimiter) Submit ¶

func (rl *RateLimiter) Submit(reqType RequestType, sendFunc func() error) error

Submit submits a request for rate-limited execution with the default retry count (3). For one-shot requests where any failure should bubble straight back to the caller (heartbeat path, test fixtures), use SubmitWithRetries(reqType, sendFunc, 0).

func (*RateLimiter) SubmitContext ¶

func (rl *RateLimiter) SubmitContext(ctx context.Context, reqType RequestType, sendFunc func() error) error

SubmitContext submits a request for rate-limited execution and cancels the queue/token wait when ctx is done. The send function should also check ctx if it may block after the limiter admits it.

func (*RateLimiter) SubmitWithRetries ¶

func (rl *RateLimiter) SubmitWithRetries(reqType RequestType, sendFunc func() error, maxRetries int) error

SubmitWithRetries submits a request with a custom retry count. Requests dispatch in arrival order; the only scheduling distinction is the context-carried pacing lane (see WithRequestPriority), which bounds how many token reservations PriorityBackground work may hold at once. A "queue jump" parameter existed before v0.16.0 but was never wired and was removed; the background lane is the deliberate replacement.

func (*RateLimiter) SubmitWithRetriesContext ¶

func (rl *RateLimiter) SubmitWithRetriesContext(ctx context.Context, reqType RequestType, sendFunc func() error, maxRetries int) error

SubmitWithRetriesContext is SubmitWithRetries plus caller-owned cancellation. This matters for interactive historical reads: the historical bucket can legitimately wait minutes during breadth fan-out, but a CLI/RPC request with a 60 s budget must leave that queue promptly when its caller is gone.

func (*RateLimiter) SubmitWithRetriesContextFunc ¶

func (rl *RateLimiter) SubmitWithRetriesContextFunc(ctx context.Context, reqType RequestType, sendFunc func(context.Context) error, maxRetries int) error

SubmitWithRetriesContextFunc passes the limiter-owned request context to the admitted callback. In addition to caller cancellation, that context is canceled synchronously by the limiter's own completion timeout, so work already admitted but parked behind another transport cannot run late.

func (*ScannerParameters) FilterByInstrument ¶

func (p *ScannerParameters) FilterByInstrument(instrument string) []ScannerScanType

FilterByInstrument returns scan types whose Instruments contain instrument, matched case-insensitively after trimming a non-empty query. An empty string returns all scan types. Returned values share nested slice data with p and must be treated as read-only.

func (*Semaphore) Acquire ¶

func (s *Semaphore) Acquire(ctx context.Context) error

Acquire blocks until a slot is available

func (*Semaphore) Count ¶

func (s *Semaphore) Count() int

Count returns current number of acquired slots

func (*Semaphore) Release ¶

func (s *Semaphore) Release()

Release frees a slot. Panics if the semaphore is empty — an over-release is always a bookkeeping bug at the caller (mismatched Acquire/Release pair), and silently absorbing it would mask the root cause.

func (*Semaphore) TryAcquire ¶

func (s *Semaphore) TryAcquire() bool

TryAcquire attempts to acquire without blocking

func (*SendDispositionError) Error ¶

func (e *SendDispositionError) Error() string

Error returns the underlying broker-send error text.

func (*SendDispositionError) SendDisposition ¶

func (e *SendDispositionError) SendDisposition() SendDisposition

SendDisposition returns the attached transport fact.

func (*SendDispositionError) Unwrap ¶

func (e *SendDispositionError) Unwrap() error

Unwrap returns the underlying broker-send error.

func (*TokenBucket) TryAcquire ¶

func (tb *TokenBucket) TryAcquire(n int) bool

TryAcquire attempts to acquire n tokens, returns true if successful

func (*TokenBucket) WaitForTokens ¶

func (tb *TokenBucket) WaitForTokens(ctx context.Context, n int) error

WaitForTokens blocks until n tokens are available

func (*WSHError) Error ¶

func (e *WSHError) Error() string

Error returns a sanitized classification without broker response prose.

func (*WSHError) Unwrap ¶

func (e *WSHError) Unwrap() error

Unwrap exposes only a caller context cancellation or deadline cause.

func (*WireInterceptor) Close ¶

func (w *WireInterceptor) Close() error

Close releases any resources associated with the interceptor.

func (*WireInterceptor) Enabled ¶

func (w *WireInterceptor) Enabled() bool

Enabled returns true if the interceptor is active.

func (*WireInterceptor) RecordInbound ¶

func (w *WireInterceptor) RecordInbound(msgID int, raw []byte, fields []string)

RecordInbound records an incoming frame from IBKR.

func (*WireInterceptor) RecordOutbound ¶

func (w *WireInterceptor) RecordOutbound(msgID int, raw []byte, fields []string)

RecordOutbound processes an outgoing frame. fields may be nil; in that case decode will be skipped.