Alpaca券商行情数据

这个技能解决什么问题

在 Alpaca 生态里做行情接入，最常见的坑不是 API 不会调，而是把两台主机搞混：行情 REST 走 data.alpaca.markets，实时流走 wss://stream.data.alpaca.markets/{version}/{feed}，而 /v2/clock、/v2/calendar、/v2/assets 这些又位于 Trading API 主机 api.alpaca.markets。在 Broker API 主机上同样的资源用的是 /v1/...，/v2/calendar 和 /v2/assets 在那边直接 404。认证也不通用：行情侧用 APCA-API-KEY-ID / APCA-API-SECRET-KEY 头，实时流是 WebSocket 而不是 Broker 事件那套 SSE。本技能把这些宿主与路径的对应关系、参数约束、流式协议和缓存姿势整理成一份可以照做的参考。

核心能力

• REST 行情：快照（latest trade/quote 加分钟/日线）、历史 OHLCV、最新成交与报价、开盘/收盘集合竞价、新闻（单次最多 50 条）、最活跃股与异动筛选器。
• 参数约束：timeframe 大小写敏感；limit 默认 1000、上限 10000，且统计的是所有 symbol 的数据点总和，不是每只股票各 1000 条；结果按 symbol 再按时间排序，多 symbol 请求要顺着 next_page_token 翻到底，否则只能拿到排在前面的 symbol。
• WebSocket 实时流：连接后 10 秒内发 auth，成功后再 subscribe trades/quotes/bars，* 表示全市场；消息是 JSON 数组批量下发，必须逐个遍历，并且要处理 u（K 线更新）与 c/x（成交/撤单修正），不能假设一帧只有一个事件。
• 可交易性与交易时段：assets 给出 tradable、fractionable、marginable、shortable、borrow_status（取代已废弃的 easytoborrow）和 attributes；用 clock / calendar 判断开盘状态与节假日，而不是硬编码 9:30–16:00。
• 缓存策略：历史 K 线按 (symbol, timeframe, timestamp) 落自己的库，upsert 去重，只从 Alpaca 补缺口；快照和报价进短 TTL 缓存，TTL 按开盘/休市分别调；可搜索标的用定时批量任务回填，别按用户请求实时拉。

适用边界与注意点

• 数据源授权：iex 是免费档唯一可用的 feed（单一交易所，约占 2.5% 成交量）；sip（全市场合并）、delayed_sip、boats、overnight 需要付费订阅。部分端点默认走 sip，免费档下会 403，必须显式传 feed=iex。
• 没有实时权限时，start/end 会隐去最近 15 分钟数据。
• 单 key 并发连接受限：多数套餐只允许一条 WebSocket，第二条会收到 406 connection limit exceeded。架构上应单进程集中订阅再分发，不要每个用户各开一条 socket。
• 成交和报价的 size 单位是股数（2025-11-03 起，之前是整手）。
• 报价里 bp/bs/bx、ap/as/ax 的价格为 0，表示该侧没有活跃挂单。
• 下单前确认可交易性见 alpaca-broker-trading-orders；限流与翻页见 alpaca-broker-rate-limits-resilience；Broker 的事件流是 SSE，和这里的 WebSocket 是两套东西，见 alpaca-broker-sse-events。