alpaca-broker-market-data

Alpaca 市场数据 API — 股票（REST + WebSocket）

美国股票的实时和历史数据。与经纪商端点不同，市场数据使用独立的主机和独立的身份验证，实时数据流使用 WebSocket，而不是 SSE。

请先阅读 alpaca-broker-integration。资产、时钟和日历位于 Trading API 主机；此处的其他所有内容都位于 Market Data API 主机。

参考

• 指南：https://docs.alpaca.markets/docs/historical-stock-data、https://docs.alpaca.markets/docs/streaming-market-data
• 实时架构：alpaca-docs MCP → list-endpoints，标题为 "Market Data API"

0. 主机与身份验证

接口	主机
市场数据 REST	https://data.alpaca.markets（沙盒 data.sandbox.alpaca.markets）
市场数据 WebSocket	wss://stream.data.alpaca.markets/{version}/{feed}
资产 / 时钟 / 日历	https://api.alpaca.markets（Trading API）— 模拟交易：paper-api.alpaca.markets

身份验证：经纪商合作伙伴使用客户端凭据访问令牌进行身份验证（POST https://authx.alpaca.markets/v1/oauth2/token — 流程见 alpaca-broker-integration）：在 REST 请求和 WS 握手中发送 Authorization: Bearer <token>，或者通过 WS 使用 {"action":"auth","key":"access_token","secret":"<token>"} 进行身份验证（字面字符串 access_token 是密钥）。令牌有效期为 15 分钟 — 请缓存并刷新令牌，不要每次调用都重新生成。密钥/密钥（APCA-API-* 标头，或 WS 上的 {"action":"auth","key":"…","secret":"…"}）属于 Trading API 路径和文档所述的经纪商旧版路径。

1. REST 端点

路径	用途
GET /v2/stocks/snapshots?symbols=… · GET /v2/stocks/{symbol}/snapshot	快照（最新成交 / 报价 + K 线）
GET /v2/stocks/bars?symbols=… · GET /v2/stocks/{symbol}/bars	历史 OHLCV K 线
GET /v2/stocks/bars/latest · …/{symbol}/bars/latest	最新 K 线
GET /v2/stocks/trades[/latest] · GET /v2/stocks/quotes[/latest]	历史 / 最新成交与报价
GET /v2/stocks/auctions	开盘 / 收盘竞价
GET /v2/stocks/meta/conditions/{trade|quote} · /meta/exchanges	代码查询
GET /v1beta1/news?symbols=…	新闻（limit 最大为 50）
GET /v1beta1/screener/stocks/most-actives · /screener/{stocks|crypto}/movers	筛选器
GET /v2/assets （Trading API 主机） · GET /v1/assets （Broker API 主机）	资产主数据 / 可交易性
GET /v2/clock · GET /v2/calendar （Trading API 主机）	市场交易时间

时钟 / 日历 / 资产路径取决于主机 — 已通过沙盒实时验证：

路径	Trading API 主机（api.alpaca.markets）	Broker API 主机（broker-api.*）
/v1/clock	—	200
/v2/clock	200	200
/v1/calendar	—	200
/v2/calendar	200	404
/v1/assets	—	200
/v2/assets	200	404

因此：在 Trading/Market-Data API 主机上使用 /v2/clock、/v2/calendar、/v2/assets。在 Broker API 主机上使用 /v1/clock、/v1/calendar、/v1/assets（/v1/clock 和 /v2/clock 在该主机上都可用；/v2/calendar 和 /v2/assets 会返回 404）。Broker API 集成调用 /v1/clock 是正确的，并非过时路径。

2. Bars — 参数

参数	说明
timeframe	[1-59]Min/T、[1-23]Hour/H、1Day/D、1Week/W、[1,2,3,4,6,12]Month/M。区分大小写。例如：1Min、5Min、1Hour、1Day
start / end	RFC3339 或 YYYY-MM-DD，包含边界值
limit	默认为 1000，最大 10000 — 计数范围为所有股票代码的数据点，而非每个股票代码
page_token	分页游标（来自 next_page_token）
adjustment	raw（默认）、split、dividend、spin-off、all — 可用逗号组合
feed	见 §3
sort	asc（默认）/ desc
asof	用于股票代码／名称变更映射的 YYYY-MM-DD；- 表示跳过映射

分页经验：结果按股票代码，然后时间戳排序。多股票代码请求达到 limit 时，可能只返回前几个股票代码的数据 — 必须持续使用 next_page_token，直到其为空，才能获取全部结果。不要认为一页就包含所有股票代码。

3. 数据源（订阅权限很重要）

• iex — 单个交易所（约占交易量的 2.5%）。**无需付费订阅即可使用的唯一数据源。**适合开发／测试。
• sip — 汇总数据，涵盖所有交易所（100% 交易量）。需要付费数据套餐。
• delayed_sip — SIP 延迟 15 分钟（最新／快照端点）。
• otc、boats（Blue Ocean 隔夜 ATS）、overnight（源自 Alpaca，价格更低）。

经验：

• 不要固定设置 feed=iex — 最新／快照端点默认使用订阅权限允许的最佳数据源；历史端点默认使用 sip，但如果没有实时访问权限，end 会默认为 15 分钟前，因此只要 end 至少是 15 分钟前，即使未订阅也可以查询历史 SIP 数据。若数据不在你的权限范围内，只有在明确请求 feed=sip 时才会返回 403（{"code":42210000,"message":"subscription does not permit querying recent SIP data"}）。
• 没有实时访问权限时，start/end 时间窗口会排除最近 15 分钟的数据。
• 截至 2025-11-03，交易／报价的数量以股为单位（此前以整手为单位）。

4. 对象结构（简短键名）

快照按股票代码区分：latestTrade、latestQuote、minuteBar、dailyBar、prevDailyBar。多股票代码响应是一个映射 { "AAPL": {…} }。

• Bar：t 表示时间，o 表示开盘价，h 表示最高价，l 表示最低价，c 表示收盘价，v 表示成交量，n 表示交易笔数，vw 表示 VWAP。
• Trade：t 表示时间，p 表示价格，s 表示数量，x 表示交易所，c 表示条件，z 表示 tape，i 表示 ID。
• Quote：bp/bs/bx 分别表示买价／买方数量／交易所，ap/as/ax 分别表示卖价／卖方数量／交易所，c 表示条件，z 表示 tape。（价格为 0 = 当前没有有效买价／卖价。）

5. WebSocket 协议

URL： wss://stream.data.alpaca.markets/{version}/{feed} — 例如 v2/iex、v2/sip、v2/delayed_sip、v1beta1/boats、v1beta1/overnight 或 v2/test（始终在线，使用代码 FAKEPACA）。

连接流程：

1. 连接 → [{"T":"success","msg":"connected"}]
2. 在 10s 内完成身份验证： {"action":"auth","key":"…","secret":"…"} → [{"T":"success","msg":"authenticated"}]
3. 订阅：{"action":"subscribe","trades":["AAPL"],"quotes":["AMD"],"bars":["*"]} → 服务回显完整订阅状态。* = 所有代码。unsubscribe 可移除订阅。

消息类型（每条消息都是一个 JSON 数组；T 用于区分类型）：t 交易、q 报价、b 分钟 K 线、d 日 K 线、u 更新后的 K 线、s 交易状态（停牌/恢复）、l LULD、c 更正、x 取消/错误、i 失衡；控制消息：success、error、subscription。订阅 trades 会自动添加 corrections 和 cancelErrors。

WebSocket 使用要点：

• 连接数限制按通讯方计算，由你运行的所有进程共享——Broker 方案允许 5 个并发数据流（Standard、StandardPlus3000、StandardPlus5000）或 10 个（StandardPlus10000）。超出限制会返回 → [{"T":"error","code":406,"msg":"connection limit exceeded"}]。应将数据流集中到一个进程，再分发给自己的客户端（不要为每位用户都打开一个套接字）。
• 请在 10s 内完成身份验证，否则连接会被断开（404）。
• 其他错误代码：401 未进行身份验证、402 身份验证失败、405 代码数量超限、407 客户端速度过慢、409 订阅权限不足（无权使用该数据源）、410 对该数据源执行的操作无效。
• 消息会批量发送——务必遍历数组；不要假设一帧就对应一个事件。
• 处理 **u（更新后的 K 线）**和 c/x（更正/取消）：流式传输的 K 线/交易可能会在事后修订。

6. 资产、时钟、日历

使用与主机相对应的路径（见 §1 中的表格）：Trading API 主机使用 /v2/...，Broker API 主机使用 /v1/...。

• 资产（Trading 主机上的 GET /v2/assets · Broker 主机上的 GET /v1/assets 和 /v1/assets/{symbol}）——可交易性元数据：tradable、fractionable、marginable、shortable、borrow_status（替代已弃用的 easy_to_borrow）、status（active/inactive）、class（us_equity/us_option/crypto/ipo）、exchange、attributes[]（例如 has_options、overnight_tradable）。Broker /v1/assets 可按 status、asset_class、attributes 筛选——不支持 exchange 筛选；Trading /v2/assets 则支持。请缓存这些数据——变化较慢；交易前查询以确认 tradable/fractionable（参见 alpaca-broker-trading-orders）。
• 时钟（Trading 主机上的 /v2/clock · Broker 主机上的 /v1/clock）——is_open、next_open、next_close、timestamp。用它控制市场时段逻辑，而不是将美东时间 9:30–16:00 写死。
• 日历（Trading 主机上的 /v2/calendar · Broker 主机上的 /v1/calendar——注意，Broker 主机上没有 /v2/calendar）——每日的 open/close（HH:MM）、session_open/session_close（HHMM，延长时段）、settlement_date。使用日历处理节假日——简单地只检查“工作日”的做法会在市场假日运行任务（虽无害，但浪费资源），还会错误计算“上一个交易日”。

7. 缓存策略（成本与速率限制经验）

市场数据是请求量最高、成本最高的部分。生产环境中的经验：

1. 在自己的存储中持久化历史 K 线数据，以 (symbol, timeframe, timestamp) 为键，并使用 upsert/跳过重复项，然后从中提供图表数据——只从 Alpaca 获取缺失的数据。
2. 在短 TTL 缓存中缓存快照/报价（根据市场开盘或闭市调整 TTL）。
3. 按计划运行一次批量回填任务，为可搜索的标的回填数据，而不是针对每个用户请求单独获取。
4. 始终跟进 next_page_token，并留意 X-RateLimit-Remaining（参见 alpaca-broker-rate-limits-resilience）。

相关技能： 下单前检查可交易性 → alpaca-broker-trading-orders；速率限制/分页 → alpaca-broker-rate-limits-resilience；经纪商事件流（SSE，与此处的 WS 不同）→ alpaca-broker-sse-events。