技能介绍

先澄清的问题

Alpaca 暴露了四类 API：Broker API、Trading API、Market Data API 与 Authentication API。它们使用不同的 Base URL、不同的鉴权方式，以及不同的可靠性语义。很多坑来自把不同家族混在一个客户端里：Broker API 下单要把 account_id 放进路径，Trading API 直接打到 /v2/orders；Broker 事件走 SSE，行情走 WebSocket；金额返回的是字符串，若用二进制浮点解析会出现舍入误差。

这个技能做什么

这是 router / overview 技能：先给出跨全部 API 都成立的共识——API 家族、Base URL、鉴权、消费方式和报文约定——然后按领域指向更细的子技能。

核心能力包括：

按家族分流：先判断你在哪个家族，再决定 URL 形态和鉴权方案。
鉴权分层：Broker 用 HTTP Basic，且 REST、SSE 事件流、代客下单共用同一凭证；行情与 Trading 常用 key/secret 头；认证 API 走 OAuth 2.0 Bearer。
三种传输：事务性操作用 REST；Broker 生命周期事件用 SSE，可回放；实时行情用 WebSocket。
报文约定：数字是字符串，应用 decimal 类型；ID 主要是 UUID，活动与新事件 ID 是 ULID；下单带上 client_order_id 保证幂等；列表分页直到 token 为空；X-RateLimit-* 头用于限流退避；时间戳是 RFC3339。

推荐的 sandbox-first 步骤是：用 ENV 切换 Base URL，先验证鉴权，再创建账户并等待 ACTIVE，然后入金、用 journals 调拨现金、下单，订阅 SSE 跟踪成交，上线前加入对账逻辑。

适用边界与注意点

这个技能不替代文档，而是告诉你参考文档不会展开的生产细节，例如 SSE 断线重连、对账与幂等、限流退避和金额精度。它主要覆盖 Broker API，因为账户生命周期最复杂。

使用时要遵守：不要硬编码生产 URL，不要按代码分支切换环境；鉴权凭证在客户端构造时构建一次；把每个写入视为异步状态机，200 只代表已接受；持久化 Alpaca 返回的 ID 作为对账键；对资金字段使用 decimal 而非 float；不要把 SSE 当作唯一事实来源，需要轮询或修复流程重新同步。