Alpaca Market Data API — Stocks (REST + WebSocket)

Real-time and historical US equity data. Unlike the Broker endpoints, market data lives on its own host with its own auth, and the real-time feed is WebSocket, not SSE.

Read alpaca-broker-integration first. Assets/clock/calendar live on the Trading API host; everything else here is the Market Data API host.

Reference

• Guides: https://docs.alpaca.markets/docs/historical-stock-data, https://docs.alpaca.markets/docs/streaming-market-data
• Live schema: alpaca-docs MCP → list-endpoints title "Market Data API"

0. Hosts & auth

Auth: headers APCA-API-KEY-ID / APCA-API-SECRET-KEY (Broker partners may use Broker Basic auth in broker context).

1. REST endpoints

Clock/calendar/assets paths are host-dependent — verified live against the sandbox:

Path	Trading API host (api.alpaca.markets)	Broker API host (broker-api.*)
/v1/clock	—	200
/v2/clock	200	200
/v1/calendar	—	200
/v2/calendar	200	404
/v1/assets	—	200
/v2/assets	200	404

So: on the Trading/Market-Data API host use /v2/clock, /v2/calendar, /v2/assets. On the Broker API host use /v1/clock, /v1/calendar, /v1/assets (/v1/clock and /v2/clock both work there; /v2/calendar and /v2/assets 404). A Broker-API integration hitting /v1/clock is correct, not stale.

2. Bars — params

Pagination lesson: results are sorted by symbol, then timestamp. A multi-symbol request that hits limit may return only the first symbol(s) — you must follow next_page_token until empty to get them all. Don't assume one page = all symbols.

3. Feeds (entitlement matters)

• iex — single exchange (~2.5% of volume). The only feed available without a paid subscription. Good for dev/testing.
• sip — consolidated, all exchanges (100% volume). Requires a paid data plan.
• delayed_sip — SIP delayed 15 min (latest/snapshot endpoints).
• otc, boats (Blue Ocean overnight ATS), overnight (Alpaca-derived, cheaper).

Lessons:

• Pick iex explicitly if you're on the free tier — some endpoints default to sip, which then 403s without entitlement. (A common surprise: "why is my historical request failing?" → defaulted to SIP.)
• Without real-time access, start/end windows withhold the most recent 15 minutes.
• Trade/quote sizes are in shares as of 2025-11-03 (were round lots before).

4. Object shapes (compact keys)

Snapshot per symbol: latestTrade, latestQuote, minuteBar, dailyBar, prevDailyBar. Multi-symbol response is a map { "AAPL": {…} }.

• Bar: t time, o open, h high, l low, c close, v volume, n trade count, vw VWAP.
• Trade: t time, p price, s size, x exchange, c conditions, z tape, i id.
• Quote: bp/bs/bx bid price/size/exchange, ap/as/ax ask price/size/exchange, c conditions, z tape. (price 0 = no active bid/ask.)

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.