broker-gotchas

星标12

分支5

更新时间2026年7月20日 17:39

Per-broker quirks for DaxAlgo Terminal's SDK-based IBrokerClient backends — Interactive Brokers, NinjaTrader 8, cTrader, and Alpaca. Use before editing their implementations under src/windows/Pipeline/TradingTerminal.Infrastructure/, or when diagnosing broker-specific connection, threading, protocol, or error-code behavior. Skip for broker-neutral Core, UI, and market-data pipeline work.

安装

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

来源

dhruuvsharma

dhruuvsharma/DaxAlgo-Terminal

打开 GitHub 仓库查看创作者相关仓库

下载

Broker Gotchas

Each backend has its own footguns. The seam (IBrokerClient) hides them from the rest of the app — keep them hidden.

Interactive Brokers

TWS handles its own 2FA. API socket has no separate 2FA step. Don't add 2FA prompts to the login screen.
ClientId must be unique across all simultaneously connected clients (Excel, Bookmap, another instance). Error 326 = collision.
Default ports: 7497 TWS Paper, 7496 TWS Live, 4002 Gateway Paper, 4001 Gateway Live.
Real client compiles only when HAS_IBAPI is defined (set by Infrastructure.csproj when CSharpAPI.dll resolves from lib/, MSBuild prop, or C:\TWS API\). Code touching IBApi.* must be inside #if HAS_IBAPI.
The TWS API is not on NuGet. Don't suggest dotnet add package IBApi.
EWrapper callbacks are on the IB reader thread. Always marshal to UI dispatcher inside MarketDataRepository before touching observable collections.
Error 502 = TWS not running / wrong port. Error 200 = no security found for contract. Error 326 = clientId collision.
The IB client is wired purely by build-time DLL resolution (HAS_IBAPI) — there's no UseRealClient switch and no synthetic IB fallback. For offline runs use the always-registered Simulated broker instead. (The UseRealClient key still in appsettings.json is vestigial and ignored.)

When in doubt, escalate to the ib-api-expert subagent.

NinjaTrader 8

NT must be running first. NTDirect.Connected(0) returns 0 only when NT 8 is up with Tools → Options → AT Interface → AT Interface enabled.
Real client compiles only when HAS_NTAPI is defined (set when NTDirect.dll resolves from lib/, MSBuild prop, or %USERPROFILE%\Documents\NinjaTrader 8\bin64\). Code touching NTDirect must be inside #if HAS_NTAPI.
NTDirect doesn't expose historical bars. RequestHistoricalBarsAsync synthesizes them with a warning log. Don't promise real history without a NinjaScript bridge add-on.
NTDirect doesn't expose L1 sizes via the simple Bid/Ask calls. Tick.BidSize/AskSize are 0 in NT mode.
Polling, not callbacks. Tick stream polls Bid/Ask at 200 ms; bar stream aggregates polled LastPrice.
NT defaults to false (must be explicitly enabled in appsettings.json).

cTrader

Always wired — the cTrader.OpenAPI.Net NuGet package restores unconditionally. There's no HAS_CTRADERAPI gate.
Real client requires OAuth credentials (clientId + clientSecret + accessToken + ctidTraderAccountId). When missing, ConnectAsync reports ConnectionState.Failed with a clear log. Don't add a synthetic fallback in the DI graph; the Failed state IS the affordance.
Access tokens expire (~30 days). Surface refresh failures as a clear error pointing at OAuth — don't suppress them.
Wire prices are ulong scaled by 10^Digits per symbol. We resolve Digits lazily via ProtoOASymbolByIdReq on first subscribe.
Trendbars use relative encoding (Low + DeltaOpen/DeltaHigh/DeltaClose). Reconstruct OHLC then divide by 10^Digits.
Per-call correlation via clientMsgId + a Dictionary<string, TaskCompletionSource<IMessage>>. Spot events bypass the request/response router; subscribers filter the OpenClient's stream by SymbolId directly.
Depth events (ProtoOADepthEvent) follow the same pattern — filter on SymbolId, but cast (long)e.SymbolId because depth events declare it as uint64 (unlike spots' int64).
Depth (L2) wired via ProtoOASubscribeDepthQuotesReq + ProtoOADepthEvent. Events carry NewQuotes (add/replace by Id) and DeletedQuotes (remove by Id). Each ProtoOADepthQuote has either Bid or Ask set (not both) — route to the right side's Dictionary<ulong, DepthLevel>. After each event, emit a consistent top-N DepthSnapshot.
Spot tick enrichment: top-of-book size comes from the depth cache, not the spot event itself (commit ad68d9e). If a strategy needs L1 sizes from cTrader, subscribe to depth alongside spots.
No trade tape. SubscribeTradesAsync throws NotSupportedException — the protocol has no per-print trade channel. Not fixable. Trade-tape strategies must check broker capability at Continue and route through IB instead.

Alpaca

Always wired — Alpaca.Markets NuGet restores unconditionally. No HAS_ALPACAAPI gate.
Auth = API key + secret. No OAuth. IsLive toggle picks Environments.Live vs Environments.Paper.
Three asset classes multiplexed by Contract.SecType:
- "STK" → stock data client + stock streaming client.
- "CRYPTO" → crypto data client + crypto streaming client.
- "OPT" → not yet supported (Alpaca's options SDK is still stabilising).
Live stock stream pinned to IEX — the SDK default targets SIP, which the free/paper plan can't subscribe to (HTTP 403 — entitlement wall). We rebase the data-stream endpoint to /v2/iex so the same code works on free accounts. Don't revert this.
Eager auth on both streams. ConnectAndAuthenticateAsync is called for stock + crypto streams during ConnectAsync so first-subscribe doesn't pay the auth round-trip. If auth fails (AuthStatus != Authorized), throw — don't silently leave a half-connected client.
No L2 depth. SubscribeDepthAsync throws NotSupportedException. Strategies that need depth must route through IB or cTrader.
No OMS yet. PlaceOrderAsync / CancelOrderAsync throw NotSupportedException like the other brokers. The trading client is constructed but not wired for orders.
Trade tape is wireable. Alpaca's WebSocket has a native trade channel with taker_side. It's the highest-leverage next SDK broker to add trade-tape support to (tape is already wired on IB, Binance, and Ironbeam; Alpaca/NT/cTrader still throw).
Instrument discovery pins data feed to IEX in Infrastructure/Alpaca/ (commit 805462b).

Cross-broker rules

IBrokerClient.ConnectAsync takes no params. Each impl reads its own IOptions<XxxOptions>. The login form pushes user-supplied values into options before flipping the selector.
Reconnect uses exponential backoff (1s → 30s cap). New broker calls must assume the connection can drop mid-call; surface failures as ConnectionState transitions, don't crash.
View-models never see EClientSocket / NTDirect / OpenClient. If you're tempted to import a broker SDK type into UI or Core, stop and re-read the layer graph.
IBrokerClient.PlaceOrderAsync / CancelOrderAsync / OrderEvents exist on the interface but all three real clients throw NotSupportedException. That's the seam OMS will fill — don't pretend it works.

同仓库更多 Skills

同仓库

add-broker

dhruuvsharma/DaxAlgo-Terminal

Recipe for wiring a new broker backend into DaxAlgo Terminal behind the IBrokerClient seam, alongside the existing twelve (Interactive Brokers, NinjaTrader 8, cTrader, Alpaca, Ironbeam, London Strategic Edge, Upstox, Binance, Coinbase, Bybit, Kraken, OKX). Use when the user asks to add a broker (e.g. "add Tradovate", "wire up Rithmic", "implement IBrokerClient for X"). Covers project layout, DI registration, login tile, options binding, fake vs real split, and the layering rules that must not be broken.

2026-07-2012

add-notifier

dhruuvsharma/DaxAlgo-Terminal

Recipe for adding a new notification transport (e.g. Slack, Email, SMS) to DaxAlgo Terminal's INotificationTransport seam, alongside the existing Telegram (Bot API) and Discord (channel webhook) transports. Use when the user asks for a new notifier, fanout target, alert channel, or webhook integration. Covers transport interface, options binding, settings persistence, hot-reload, and the dispatcher auto-discovery contract.

2026-07-2012

add-strategy

dhruuvsharma/DaxAlgo-Terminal

Create or modify a DaxAlgo Windows strategy as an external runtime plugin using DaxAlgo.Sdk, DaxAlgo.Sdk.Wpf, the daxalgo-strategy template, StrategyTool, plugin.json, offline tests, and .daxplugin packaging. Use when asked to add, scaffold, implement, package, test, or install a strategy. Do not create in-tree strategy projects or add strategy references to the public host.

2026-07-2012

ai-analyst

dhruuvsharma/DaxAlgo-Terminal

Python sidecar (LangGraph indicator/pattern/trend/decision agents + TA-Lib + vision LLM) reached over HTTP/JSON via IAiAnalystClient; hot-swappable Null↔Http via IOptionsMonitor. Use when touching tools/python-ml/, the IAiAnalystClient seam in Core/Infrastructure, the AiAnalystEnricher in the notification pipeline, the AI Market Analyst window, or debugging "AI Analyst unavailable" / HTTP 504 / 500 errors.

2026-07-2012

archive-offloader

dhruuvsharma/DaxAlgo-Terminal

Telegram-backed archive offloader for the canonical market-data store — parquet bundling, 2 GB split-binary parts, sha256 verification, manifest store, retention pruning. Use when touching src/windows/Pipeline/TradingTerminal.MarketData/Archive/, adding store tables to the bundle, changing the archive schedule, swapping the Telegram transport for another backend, or debugging archive/restore round-trips.

2026-07-2012

backtest-engine

dhruuvsharma/DaxAlgo-Terminal

Internals of DaxAlgo Terminal's tick/event backtest stack — Core contracts, TradingTerminal.Backtest.Engine replay and optimization, Infrastructure persistence adapters, and the Backtest/BacktestStudio tools. Use for fee/risk/fill simulation, event ordering, reports, optimization, or backtest surfaces. Skip strategy authoring; use add-strategy for external plugins.

2026-07-2012

name	broker-gotchas
description	Per-broker quirks for DaxAlgo Terminal's SDK-based IBrokerClient backends — Interactive Brokers, NinjaTrader 8, cTrader, and Alpaca. Use before editing their implementations under src/windows/Pipeline/TradingTerminal.Infrastructure/, or when diagnosing broker-specific connection, threading, protocol, or error-code behavior. Skip for broker-neutral Core, UI, and market-data pipeline work.

Broker Gotchas

Each backend has its own footguns. The seam (IBrokerClient) hides them from the rest of the app — keep them hidden.

Interactive Brokers

TWS handles its own 2FA. API socket has no separate 2FA step. Don't add 2FA prompts to the login screen.
ClientId must be unique across all simultaneously connected clients (Excel, Bookmap, another instance). Error 326 = collision.
Default ports: 7497 TWS Paper, 7496 TWS Live, 4002 Gateway Paper, 4001 Gateway Live.
Real client compiles only when HAS_IBAPI is defined (set by Infrastructure.csproj when CSharpAPI.dll resolves from lib/, MSBuild prop, or C:\TWS API\). Code touching IBApi.* must be inside #if HAS_IBAPI.
The TWS API is not on NuGet. Don't suggest dotnet add package IBApi.
EWrapper callbacks are on the IB reader thread. Always marshal to UI dispatcher inside MarketDataRepository before touching observable collections.
Error 502 = TWS not running / wrong port. Error 200 = no security found for contract. Error 326 = clientId collision.
The IB client is wired purely by build-time DLL resolution (HAS_IBAPI) — there's no UseRealClient switch and no synthetic IB fallback. For offline runs use the always-registered Simulated broker instead. (The UseRealClient key still in appsettings.json is vestigial and ignored.)

When in doubt, escalate to the ib-api-expert subagent.

NinjaTrader 8

NT must be running first. NTDirect.Connected(0) returns 0 only when NT 8 is up with Tools → Options → AT Interface → AT Interface enabled.
Real client compiles only when HAS_NTAPI is defined (set when NTDirect.dll resolves from lib/, MSBuild prop, or %USERPROFILE%\Documents\NinjaTrader 8\bin64\). Code touching NTDirect must be inside #if HAS_NTAPI.
NTDirect doesn't expose historical bars. RequestHistoricalBarsAsync synthesizes them with a warning log. Don't promise real history without a NinjaScript bridge add-on.
NTDirect doesn't expose L1 sizes via the simple Bid/Ask calls. Tick.BidSize/AskSize are 0 in NT mode.
Polling, not callbacks. Tick stream polls Bid/Ask at 200 ms; bar stream aggregates polled LastPrice.
NT defaults to false (must be explicitly enabled in appsettings.json).

cTrader

Always wired — the cTrader.OpenAPI.Net NuGet package restores unconditionally. There's no HAS_CTRADERAPI gate.
Real client requires OAuth credentials (clientId + clientSecret + accessToken + ctidTraderAccountId). When missing, ConnectAsync reports ConnectionState.Failed with a clear log. Don't add a synthetic fallback in the DI graph; the Failed state IS the affordance.
Access tokens expire (~30 days). Surface refresh failures as a clear error pointing at OAuth — don't suppress them.
Wire prices are ulong scaled by 10^Digits per symbol. We resolve Digits lazily via ProtoOASymbolByIdReq on first subscribe.
Trendbars use relative encoding (Low + DeltaOpen/DeltaHigh/DeltaClose). Reconstruct OHLC then divide by 10^Digits.
Per-call correlation via clientMsgId + a Dictionary<string, TaskCompletionSource<IMessage>>. Spot events bypass the request/response router; subscribers filter the OpenClient's stream by SymbolId directly.
Depth events (ProtoOADepthEvent) follow the same pattern — filter on SymbolId, but cast (long)e.SymbolId because depth events declare it as uint64 (unlike spots' int64).
Depth (L2) wired via ProtoOASubscribeDepthQuotesReq + ProtoOADepthEvent. Events carry NewQuotes (add/replace by Id) and DeletedQuotes (remove by Id). Each ProtoOADepthQuote has either Bid or Ask set (not both) — route to the right side's Dictionary<ulong, DepthLevel>. After each event, emit a consistent top-N DepthSnapshot.
Spot tick enrichment: top-of-book size comes from the depth cache, not the spot event itself (commit ad68d9e). If a strategy needs L1 sizes from cTrader, subscribe to depth alongside spots.
No trade tape. SubscribeTradesAsync throws NotSupportedException — the protocol has no per-print trade channel. Not fixable. Trade-tape strategies must check broker capability at Continue and route through IB instead.

Alpaca

Always wired — Alpaca.Markets NuGet restores unconditionally. No HAS_ALPACAAPI gate.
Auth = API key + secret. No OAuth. IsLive toggle picks Environments.Live vs Environments.Paper.
Three asset classes multiplexed by Contract.SecType:
- "STK" → stock data client + stock streaming client.
- "CRYPTO" → crypto data client + crypto streaming client.
- "OPT" → not yet supported (Alpaca's options SDK is still stabilising).
Live stock stream pinned to IEX — the SDK default targets SIP, which the free/paper plan can't subscribe to (HTTP 403 — entitlement wall). We rebase the data-stream endpoint to /v2/iex so the same code works on free accounts. Don't revert this.
Eager auth on both streams. ConnectAndAuthenticateAsync is called for stock + crypto streams during ConnectAsync so first-subscribe doesn't pay the auth round-trip. If auth fails (AuthStatus != Authorized), throw — don't silently leave a half-connected client.
No L2 depth. SubscribeDepthAsync throws NotSupportedException. Strategies that need depth must route through IB or cTrader.
No OMS yet. PlaceOrderAsync / CancelOrderAsync throw NotSupportedException like the other brokers. The trading client is constructed but not wired for orders.
Trade tape is wireable. Alpaca's WebSocket has a native trade channel with taker_side. It's the highest-leverage next SDK broker to add trade-tape support to (tape is already wired on IB, Binance, and Ironbeam; Alpaca/NT/cTrader still throw).
Instrument discovery pins data feed to IEX in Infrastructure/Alpaca/ (commit 805462b).

Cross-broker rules

IBrokerClient.ConnectAsync takes no params. Each impl reads its own IOptions<XxxOptions>. The login form pushes user-supplied values into options before flipping the selector.
Reconnect uses exponential backoff (1s → 30s cap). New broker calls must assume the connection can drop mid-call; surface failures as ConnectionState transitions, don't crash.
View-models never see EClientSocket / NTDirect / OpenClient. If you're tempted to import a broker SDK type into UI or Core, stop and re-read the layer graph.
IBrokerClient.PlaceOrderAsync / CancelOrderAsync / OrderEvents exist on the interface but all three real clients throw NotSupportedException. That's the seam OMS will fill — don't pretend it works.