技能介绍

要解决的问题

自建美股行情管线时，最常见的坑是把数据面和交易面混在同一个 host 上，结果 /v2/clock 时通时不通；或者以为实时行情是 SSE 流，接上去才发现是 WebSocket。这个技能专门解决行情接口的边界问题：哪些 endpoint 属于 Market Data API，哪些属于 Trading API，实时流怎么握手，以及免费额度下为什么历史请求会莫名 403。

核心能力与工作流程

行情数据独立部署在 data.alpaca.markets（沙盒为 data.sandbox.alpaca.markets），认证用 APCA-API-KEY-ID / APCA-API-SECRET-KEY 两个 header，与 Broker API 不是同一套。REST 面覆盖：

快照与 K 线：/v2/stocks/snapshots 返回 latestTrade、latestQuote、当日与前一日的日 K；/v2/stocks/bars 按 timeframe 拉历史 OHLCV，支持 adjustment（split/dividend/raw/all）与 asof 映射
逐笔与盘口：trades / quotes 的 latest 与历史版本，以及开盘、收盘竞价数据
元数据：news（单次上限 50）、most-actives 与 movers 筛选器
交易时间：clock / calendar 位于 Trading API host，应替换硬编码的 9:30–16:00 判断

实时链路走 wss://stream.data.alpaca.markets/{version}/{feed}，流程固定：连接 → 10 秒内发 auth → 发 subscribe。消息全是 JSON 数组，靠 T 字段区分 trade / quote / bar / trading status / LULD / correction / cancel 等类型，且单条连接按 key 计费并发，官方建议集中在单进程再扇出。

适用边界与注意点

feed 权限：免费档只有 iex（约占 2.5% 成交量），不显式指定时部分 endpoint 会默认走 sip 并直接 403；无实时权限时，最近 15 分钟数据会被扣住
分页陷阱：limit 统计的是所有 symbol 的总数据点数，结果按 symbol 再按时间排序，多 symbol 请求必须跟随 next_page_token 直到为空
版本差异：Broker host 上只有 /v1/clock、/v1/calendar、/v1/assets，Trading host 上对应 /v2/...，混用会 404
数据单位：自 2025-11-03 起 trade/quote 的 size 以股为单位，不再是整手
成本控制：历史 K 线应自建存储按 (symbol, timeframe, timestamp) upsert，快照走短 TTL 缓存，并关注 X-RateLimit-Remaining