Alpaca Broker Market Data

5. WebSocket protocol

URL: wss://stream.data.alpaca.markets/{version}/{feed} — e.g. v2/iex, v2/sip, v2/delayed_sip, v1beta1/boats, v1beta1/overnight, or v2/test (always-on, use symbol FAKEPACA).

Connect flow:

1. Connect → [{"T":"success","msg":"connected"}]
2. Auth within 10s: {"action":"auth","key":"…","secret":"…"} → [{"T":"success","msg":"authenticated"}]
3. Subscribe: {"action":"subscribe","trades":["AAPL"],"quotes":["AMD"],"bars":["*"]} → server echoes full subscription state. * = all symbols. unsubscribe removes.

Message types (every message is a JSON array; T discriminates): t trade, q quote, b minute bar, d daily bar, u updated bar, s trading status (halt/resume), l LULD, c correction, x cancel/error, i imbalance; control: success, error, subscription. Subscribing to trades auto-adds corrections + cancelErrors.

WebSocket lessons:

• One concurrent connection per key on most plans — a 2nd connection → {"code":406,"connection limit exceeded"}. Centralize the stream in one process and fan out to your own clients (don't open a socket per user).
• Authenticate within 10s or get dropped (404).
• Other error codes: 401 not auth'd, 402 auth failed, 405 symbol limit, 407 slow client, 409 insufficient subscription (feed not entitled), 410 invalid action for feed.
• Messages are batched — always iterate the array; don't assume one frame = one event.
• Handle u (updated bar) and c/x (corrections/cancels): a streamed bar/trade can be revised after the fact.

6. Assets, clock, calendar

Use the host-appropriate path (see the table in §1): /v2/... on the Trading API host, /v1/... on the Broker API host.

• Assets (GET /v2/assets on Trading host · GET /v1/assets and /v1/assets/{symbol} on Broker host) — tradability metadata: tradable, fractionable, marginable, shortable, borrow_status (replaces deprecated easy_to_borrow), status (active/inactive), class (us_equity/us_option/crypto/ipo), exchange, attributes[] (e.g. has_options, overnight_tradable). Filter by status, asset_class, exchange. Cache this — it changes slowly; query it before trading to confirm tradable/fractionable (see alpaca-broker-trading-orders).
• Clock (/v2/clock on Trading host · /v1/clock on Broker host) — is_open, next_open, next_close, timestamp. Use this to gate market-hours logic instead of hardcoding 9:30–16:00 ET.
• Calendar (/v2/calendar on Trading host · /v1/calendar on Broker host — note there is no /v2/calendar on the Broker host) — per-day open/close (HH:MM), session_open/session_close (HHMM, extended hours), settlement_date. Use the calendar for holidays — a naive "weekdays only" check runs jobs on market holidays (harmless but wasteful) and miscomputes "previous trading day."

7. Caching strategy (cost & rate-limit lesson)

Market data is the highest-volume, highest-cost surface. Production lesson:

1. Persist historical bars in your own store keyed by (symbol, timeframe, timestamp) with upsert/skip-duplicate, and serve charts from there — only fetch the gap from Alpaca.
2. Cache snapshots/quotes in a short-TTL cache (TTL tuned to market-open vs closed).
3. Run one bulk backfill job for searchable symbols on a schedule rather than fetching per user request.
4. Always follow next_page_token and watch X-RateLimit-Remaining (see alpaca-broker-rate-limits-resilience).

Related skills: tradability before ordering → alpaca-broker-trading-orders; rate limits/pagination → alpaca-broker-rate-limits-resilience; the broker event stream (SSE, different from this WS) → alpaca-broker-sse-events.