/market-data

name: alpaca-broker-market-data
description: Pull and stream US stock market data from Alpaca — REST snapshots/bars/trades/quotes, historical bars with timeframes and feeds (IEX vs SIP), the assets master list, market clock & calendar, news, and the real-time WebSocket stream. Use when building charts, quotes, price feeds, or asset metadata on Alpaca in any language.

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

| Surface | Host | |---------|------| | Market data REST | `https://data.alpaca.markets` (sandbox `data.sandbox.alpaca.markets`) | | Market data WebSocket | `wss://stream.data.alpaca.markets/{version}/{feed}` | | Assets / clock / calendar | `https://api.alpaca.markets` (Trading API) — paper: `paper-api.alpaca.markets` |

**Auth:** Broker partners authenticate with a **client-credentials access token** (`POST https://authx.alpaca.markets/v1/oauth2/token` — flow in `alpaca-broker-integration`): send `Authorization: Bearer <token>` on REST and on the WS handshake, or authenticate over WS with `{"action":"auth","key":"access_token","secret":"<token>"}` (the literal string `access_token` is the key). Tokens are valid **15 minutes** — cache and refresh one, don't mint per call. Key/secret (`APCA-API-*` headers, or `{"action":"auth","key":"…","secret":"…"}` on WS) is the Trading API path and the documented **legacy** Broker path.

1. REST endpoints

| Path | Purpose | |------|---------| | `GET /v2/stocks/snapshots?symbols=…` · `GET /v2/stocks/{symbol}/snapshot` | Snapshot (latest trade/quote + bars) | | `GET /v2/stocks/bars?symbols=…` · `GET /v2/stocks/{symbol}/bars` | Historical OHLCV bars | | `GET /v2/stocks/bars/latest` · `…/{symbol}/bars/latest` | Latest bar(s) | | `GET /v2/stocks/trades[/latest]` · `GET /v2/stocks/quotes[/latest]` | Historical / latest trades & quotes | | `GET /v2/stocks/auctions` | Opening/closing auctions | | `GET /v2/stocks/meta/conditions/{trade\|quote}` · `/meta/exchanges` | Code lookups | | `GET /v1beta1/news?symbols=…` | News (max `limit` 50) | | `GET /v1beta1/screener/stocks/most-actives` · `/screener/{stocks\|crypto}/movers` | Screeners | | `GET /v2/assets` *(Trading API host)* · `GET /v1/assets` *(Broker API host)* | Asset master / tradability | | `GET /v2/clock` · `GET /v2/calendar` *(Trading API host)* | Market hours |

> **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

| Param | Notes | |-------|-------| | `timeframe` | `[1-59]Min`/`T`, `[1-23]Hour`/`H`, `1Day`/`D`, `1Week`/`W`, `[1,2,3,4,6,12]Month`/`M`. Case-sensitive. e.g. `1Min`, `5Min`, `1Hour`, `1Day` | | `start` / `end` | RFC3339 or `YYYY-MM-DD`, inclusive | | `limit` | default **1000**, max **10000** — counts data points **across all symbols**, not per symbol | | `page_token` | pagination cursor (from `next_page_token`) | | `adjustment` | `raw` (default), `split`, `dividend`, `spin-off`, `all` — comma-combinable | | `feed` | see §3 | | `sort` | `asc` (default) / `desc` | | `asof` | `YYYY-MM-DD` for symbol/name-change mapping; `-` skips mapping |

**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:**

• **Don't hard-pin `feed=iex`** — latest/snapshot endpoints default to the best feed your subscription entitles you to, and historical endpoints default to `sip` but default `end` to 15 minutes ago when you lack real-time access, so historical SIP is queryable unsubscribed as long as `end` is at least 15 minutes old. A `403` (`{"code":42210000,"message":"subscription does not permit querying recent SIP data"}`) comes from **explicitly** asking for `feed=sip` on data you aren't entitled to.
• 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` ta