Architecture¶

All 36 API modules share a single httpx.Client instance via FidelityClient. Cookies (the auth mechanism) propagate automatically.

FidelityClient
├── _http: httpx.Client              shared cookie jar
├── _auth: AuthSession               7-step login + CSRF
├── 12 portfolio modules             positions, balances, accounts, features, HTB, lots, ...
├── 8 order modules                  equity, option, cancel+preview, conditional+replace, ...
├── 3 market data modules            fastquote (chains + montage), chart, time & sales
├── 5 research modules               earnings, search, analytics, screener, short insights
├── 4 streaming modules              MDDS quotes + L2, BEPS events, news auth
├── watchlists, alerts, price_triggers, preferences
├── available_markets, holiday_calendar, security_context
├── session_keepalive, auto_refresh
└── close()

API Modules¶

#	Accessor	Endpoint	Host
1	`positions`	`POST /ftgw/dp/position/v2`	dpservice
2	`balances`	`POST /ftgw/dp/balance/detail/v2`	dpservice
3	`accounts`	`POST /ftgw/dp/customer-am-acctnxt/v2/accounts`	dpservice
4	`account_features`	`POST /ftgw/dp/customer-am-feature/v2/accounts/features/get`	dpservice
5	`option_summary`	`POST /ftgw/dp/retail-am-optionsummary/v1`	dpservice
6	`transactions`	`POST /ftgw/dp/accountmanagement/transaction/history/v2`	dpservice
7	`closed_positions`	`POST /ftgw/dp/customer-am-position/v1/.../closedposition`	dpservice
8	`loaned_securities`	`POST /ftgw/dp/retail-am-loanedsecurities/v1/.../rates`	dpservice
9	`hard_to_borrow`	`POST /ftgw/dp/retail-am-hardtoborrow/v1/.../rates/borrow`	dpservice
10	`tax_lots`	`POST /ftgw/dp/orderentry/taxlot/v1`	dpservice
11	`open_lots`	`POST /ftgw/dp/position/open/lots/v1`	dpservice
12	`short_insights`	`POST /ftgw/dp/retail-am-shortinsight/v1` + `/api/v1/timeseries`	dpservice
13	`order_status`	`POST /ftgw/dp/retail-order-status/v3` (summary + detail)	dpservice
14	`equity_orders`	`POST /ftgw/dp/orderentry/equity/{preview,place}/v1`	dpservice
15	`single_option_orders`	`POST /ftgw/dp/orderentry/option/{preview,place}/v2`	dpservice
16	`option_orders`	`POST /ftgw/dp/orderentry/multilegoption/{preview,place}/v1`	dpservice
17	`cancel_order`	`POST /ftgw/dp/orderentry/cancel/{preview,place}/v1`	dpservice
18	`cancel_replace`	`POST /ftgw/dp/orderentry/cancelandreplace/{preview,place}/v1`	dpservice
19	`conditional_orders`	`POST /ftgw/dp/orderentry/conditional/{preview,place}/v1`	dpservice
20	`conditional_orders`	`POST /ftgw/dp/retail-condition-replace/v1/.../orders/{preview,place}`	dpservice
21	`staged_orders`	`POST /ftgw/dp/ent-research-staging/v1/.../staged-order/get`	dpservice
22	`option_chain`	`GET fastquote/service/quote/{chainLite,dtmontage}`	fastquote
23	`chart`	`GET fastquote/service/marketdata/historical/chart/json`	fastquote
24	`time_and_sales`	`GET fastquote/rhistory/atng/timeandsalesLite`	fastquote
25	`research`	`GET /ftgw/dpdirect/research/{earning,dividend}/v1`	dpservice
26	`search`	`GET /ftgw/dpdirect/search/autosuggest/v1`	dpservice
27	`option_analytics`	`POST /ftgw/dp/research/option/positions/analytics/v1`	dpservice
28	`screener`	`POST fidelity.apps.livevol.com ExecuteScan`	livevol
29	`streaming`	`POST streaming-news/ftgw/snaz/Authorize`	streaming-news
30	`watchlists`	`POST /ftgw/dp/retail-watchlist/v1/.../get`	dpservice
31	`alerts`	`POST ecawsgateway/ftgw/alerts/services/ATBTSubscription`	ecawsgateway
32	`price_triggers`	`GET+POST /ftgw/dp/retail-price-triggers/v1`	dpservice
33	`preferences`	`POST /ftgw/dp/.../atn-prefs/{get,save,delete}preference`	dpservice
34	`available_markets`	`POST /ftgw/dp/reference/security/stock/availablemarket/v1`	dpservice
35	`holiday_calendar`	`GET /ftgw/dpdirect/market/holidaycalendar/v1`	dpservice
36	`security_context`	`POST /ftgw/digital/pico/api/v1/context/security`	digital

Real-Time Streaming¶

Two WebSocket protocols for real-time data:

MDDS (wss://mdds-i-tc.fidelity.com) — market data:

163 core quote fields + 10 Greek fields mapped from QwsFieldNameConstants
L2 depth via subscribe_virtualbook (25-level order book, 200 field IDs)
1-minute OHLCV bars via subscribe_1-minute-bar
Time & Sales derived from delta updates (fields 28, 29, 316, 882)
Symbol chunking at 50 per subscribe message

BEPS (AWS AppSync GraphQL) — account events:

19 event types across 8 categories (fills, cancels, positions, balance, price alerts)
GraphQL subscription via graphql-ws sub-protocol
Token-in-URL authentication (base64-encoded JSON)
Keep-alive pings (ka messages)

Production Layer (both MDDS and BEPS):

MDDSStream / BEPSStream — async managers with auto-reconnect
ReconnectPolicy — configurable backoff array, clamps to last value, resets on success
SubscriptionManager — ref-counted symbols, delayed unsubscribe (10s default)
Auto re-subscribe on reconnect, pending queue for offline subscribes

Version Diff Pipeline¶

Detect app updates and identify API changes:

python -m tools.version_check          # check installed vs baseline version
python -m tools.model_diff --snapshot  # snapshot current models
python -m tools.codegen.run --category all  # regenerate from new source
python -m tools.model_diff             # semantic diff (new/removed/changed classes, fields, enums)

Generated Models¶

The codegen pipeline (tools/codegen/) generates 1,224 Pydantic v2 models from C# source definitions:

src/fidelity_trader/models/generated/
├── enums/      17 files — OrderActionType, OrderStatusType, QuantityType, ...
├── api/        14 files — Trade DTOs, Order DTOs, Balance DTOs, BEPS models, ...
└── internal/   17 files — PositionDetail, BalanceDetail, Nebula state, ...

These are separate from the hand-written SDK models and provide the complete wire-format type definitions for all API contracts.

Project Structure¶

fidelity-trader-api/
├── src/fidelity_trader/           SDK library
│   ├── auth/                      Login, TOTP 2FA, session management
│   ├── portfolio/                 12 modules (positions, balances, features, HTB, lots, ...)
│   ├── orders/                    8 modules (equity, option, cancel, conditional, ...)
│   ├── market_data/               3 modules (chains, chart, time & sales)
│   ├── research/                  5 modules (earnings, search, analytics, screener, short insights)
│   ├── streaming/                 4 modules (MDDS quotes+L2, BEPS events, news)
│   ├── models/                    30+ hand-written + 1,224 generated models
│   └── cli/                       17 CLI commands
├── service/                       FastAPI REST service (57 endpoints)
├── tools/codegen/                 C# to Pydantic codegen pipeline
├── tests/                         1638 tests
├── docker/                        Dockerfile + docker-compose
└── docs/site/                     MkDocs Material documentation