REST Service¶

The service wraps all 40 SDK modules as REST endpoints with session lifecycle management, streaming fan-out, and Docker deployment.

pip install fidelity-trader-api[service]
python -m service  # Starts on http://localhost:8787

Configuration¶

All settings via environment variables with FTSERVICE_ prefix:

Variable	Default	Description
`FTSERVICE_HOST`	`127.0.0.1`	Bind address
`FTSERVICE_PORT`	`8787`	Port
`FTSERVICE_API_KEY_REQUIRED`	`true`	Require `Authorization: Bearer <key>`
`FTSERVICE_ENCRYPTION_KEY`		Fernet key for credential storage
`FTSERVICE_LIVE_TRADING`	`false`	Enable live order placement
`FTSERVICE_AUTO_REAUTH`	`true`	Re-authenticate on session expiry
`FTSERVICE_SESSION_KEEPALIVE_INTERVAL`	`300`	Keep-alive interval (seconds)
`FTSERVICE_LOG_LEVEL`	`INFO`	Logging level
`FTSERVICE_BEPS_TOKEN`		BEPS JWT auth token (enables event streaming)
`FTSERVICE_BEPS_HOST`		AppSync host for BEPS WebSocket
`FTSERVICE_BEPS_STREAM_URL`		BEPS WebSocket URL template (`{0}` = auth header)
`FTSERVICE_BEPS_MID`		Member identifier for BEPS subscription
`FTSERVICE_BEPS_APP_ID`	`ATN`	BEPS consumer app ID

Endpoints¶

Auth & Session¶

POST   /api/v1/auth/login              Login with Fidelity credentials
POST   /api/v1/auth/logout             Logout and clear session
GET    /api/v1/auth/status             Session state
POST   /api/v1/auth/credentials        Store encrypted credentials
DELETE /api/v1/auth/credentials        Remove stored credentials

Accounts & Portfolio (17 endpoints)¶

GET    /api/v1/accounts                                     All accounts
GET    /api/v1/accounts/{acct}/positions                    Positions
GET    /api/v1/accounts/{acct}/balances                     Balances
GET    /api/v1/accounts/{acct}/transactions                 Transaction history
GET    /api/v1/accounts/{acct}/options-summary              Option positions
GET    /api/v1/accounts/{acct}/closed-positions             Closed positions
GET    /api/v1/accounts/{acct}/loaned-securities            Loaned securities
GET    /api/v1/accounts/{acct}/tax-lots/{symbol}            Tax lots
GET    /api/v1/accounts/{acct}/features                     Account capabilities
GET    /api/v1/accounts/{acct}/hard-to-borrow?symbols=      Borrow rates
GET    /api/v1/accounts/{acct}/lots/{symbol}                Open lots per position
GET    /api/v1/accounts/{acct}/short-insights?symbols=      Short interest data
GET    /api/v1/accounts/{acct}/short-insights/{sym}/timeseries  Short insights history
GET    /api/v1/accounts/{acct}/accruals                     Margin/dividend accruals
GET    /api/v1/accounts/{acct}/cash-accruals                Cash sweep accruals
GET    /api/v1/accounts/{acct}/closed-lots/{symbol}         Closed lots with gain/loss

Orders (20 endpoints)¶

GET    /api/v1/orders/status                                Open/recent orders
GET    /api/v1/orders/{order_id}/detail?acct=               Single order detail
GET    /api/v1/orders/staged                                Staged orders
POST   /api/v1/orders/equity/preview                        Preview equity order
POST   /api/v1/orders/equity/place                          Place equity order
POST   /api/v1/orders/option/preview                        Preview single-leg option
POST   /api/v1/orders/option/place                          Place single-leg option
POST   /api/v1/orders/options/preview                       Preview multi-leg option
POST   /api/v1/orders/options/place                         Place multi-leg option
POST   /api/v1/orders/{conf_num}/cancel/preview             Preview cancel (warnings)
POST   /api/v1/orders/{conf_num}/cancel                     Cancel order
POST   /api/v1/orders/replace/preview                       Preview cancel-replace
POST   /api/v1/orders/replace/place                         Place cancel-replace
POST   /api/v1/orders/conditional/preview                   Preview conditional order
POST   /api/v1/orders/conditional/place                     Place conditional order
POST   /api/v1/orders/conditional/replace/preview           Preview conditional replace
POST   /api/v1/orders/conditional/replace/place             Place conditional replace
POST   /api/v1/orders/staged/save                           Save staged order
DELETE /api/v1/orders/staged/{stage_id}                     Delete staged order
POST   /api/v1/orders/trade-agreement                       Accept trade agreement

Market Data (5 endpoints)¶

GET    /api/v1/market-data/chain/{symbol}                   Option chain
GET    /api/v1/market-data/montage/{symbol}                 Depth of market
GET    /api/v1/market-data/chart/{symbol}                   Historical OHLCV
GET    /api/v1/market-data/time-and-sales/{symbol}          Historical T&S
GET    /api/v1/market-data/markets/{symbol}                 Available markets

Streaming (SSE + WebSocket)¶

GET    /api/v1/streaming/quotes?symbols=AAPL,TSLA          SSE: real-time quotes
GET    /api/v1/streaming/events                             SSE: account events (BEPS)
WS     /api/v1/ws/quotes                                   WebSocket: bidirectional quotes
POST   /api/v1/streaming/subscribe                          Subscribe symbols
POST   /api/v1/streaming/unsubscribe                        Unsubscribe symbols
GET    /api/v1/streaming/subscriptions                      Active subscriptions
GET    /api/v1/streaming/status                             Connection status

Research (9 endpoints)¶

GET    /api/v1/research/earnings?symbols=                   Earnings data
GET    /api/v1/research/dividends?symbols=                  Dividend data
GET    /api/v1/research/search?q=                           Symbol autosuggest
POST   /api/v1/research/analytics                           Option position analysis
POST   /api/v1/research/screener                            LiveVol screener scan
GET    /api/v1/research/notebooks                           List research notes
POST   /api/v1/research/notebooks                           Create research note
DELETE /api/v1/research/notebooks/{note_id}                 Delete research note
PUT    /api/v1/research/notebooks/{note_id}                 Update research note

Watchlists, Preferences, Reference — 10 more endpoints. See /docs for the full OpenAPI spec.

Response Format¶

All responses use a consistent envelope:

{"ok": true, "data": { ... }, "error": null}

Error responses:

{"ok": false, "data": null, "error": {"code": "AUTH_REQUIRED", "message": "Not authenticated"}}

Error Code	HTTP	Meaning
`AUTH_REQUIRED`	401	Not logged in
`SESSION_EXPIRED`	401	Session timed out
`LIVE_TRADING_DISABLED`	403	Dry-run mode active
`API_KEY_INVALID`	403	Bad or missing API key
`FIDELITY_ERROR`	502	Upstream Fidelity error

Streaming (SSE / WebSocket)¶

The service fans out a single MDDS WebSocket connection to multiple consumers. MDDS uses production streaming with auto-reconnect (configurable backoff) and ref-counted subscriptions with delayed unsubscribe (prevents churn when consumers rapidly connect/disconnect).

Server-Sent Events:

curl -N "http://localhost:8787/api/v1/streaming/quotes?symbols=AAPL,TSLA"
# event: quote
# data: {"symbol": "AAPL", "last": 195.23, "bid": 195.20, "ask": 195.25}

WebSocket:

const ws = new WebSocket("ws://localhost:8787/api/v1/ws/quotes");
ws.send(JSON.stringify({ action: "subscribe", symbols: ["AAPL", "TSLA"] }));
ws.onmessage = (e) => console.log(JSON.parse(e.data));

Account Events (BEPS):

# Requires FTSERVICE_BEPS_* env vars to be configured
curl -N "http://localhost:8787/api/v1/streaming/events"
# event: beps
# data: {"event_type": "ORDER_FILL", "category": "order", "desc": {...}}

REST control:

POST /api/v1/streaming/subscribe      {"symbols": ["AAPL"]}
POST /api/v1/streaming/unsubscribe    {"symbols": ["AAPL"]}
GET  /api/v1/streaming/subscriptions  Current subscriptions
GET  /api/v1/streaming/status         MDDS + BEPS connection state

Docker Deployment¶

# Copy and edit environment config
cp docker/.env.example docker/.env
# Generate encryption key:
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

# Start
docker compose -f docker/docker-compose.yml up -d

# Health check
curl http://localhost:8787/health