技能介绍

要解决的问题

Alpaca 的集成难点不在单个接口，而在边界：同一个系统里会同时面对 Broker API、Trading API、Market Data API 和 Authentication API，它们的 base URL、鉴权方式、传输语义都不同。Broker API 是为终端用户开户并代客交易，Trading API 是操作 API-key 持有者自己的账户；把 /v1/trading/accounts/{account_id}/orders 和 /v2/orders 混用、把 Broker 事件流和市场数据 WebSocket 混为一谈，是常见故障来源。券商侧生命周期更长：KYC、入金、journals、订单、成交、转账、状态机、事件回放与本地账本对账，都会在真实生产中暴露问题。

它如何工作

这个技能先做路由和总览，不急着进入某个子域。使用时先判断任务属于哪个 API family，再选择 sandbox 或 production base URL；Broker 用 HTTP Basic，Market Data/Trading 多用 key/secret headers，Authentication API 走 OAuth 2.0 Bearer；消费方式分为 REST、SSE 和 WebSocket。Broker 生命周期事件走可回放的 SSE，实时行情走 WebSocket，不要混用。

推荐流程是：用 ENV 切换 sandbox/prod；启动时构建一次 auth；先调 GET /v1/accounts 验证连接；再按 KYC onboarding → ACTIVE → funding → journals → orders → SSE events → reconciliation 的顺序推进。通用 wire conventions 是重点：价格、数量、名义金额、资金字段都是 JSON string，必须用 Decimal 而不是 float；account/order/journal/transfer ID 是 UUID，activity 和部分事件 ID 是 ULID；下单要带 client_order_id，事件落库要按 Alpaca ID 做 upsert/skip-duplicate；列表分页要循环到 token 为空；响应里的 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset 要主动读，429 后等 reset；RFC3339 时间中的 + 要 URL-encode 成 %2B；2xx 只表示 accepted，不等于 settled，最终要以事件或轮询到的终态为准。

适用边界与注意点

它主要聚焦 Broker API，因为开户、资金通道、journals 和事件对账最复杂；Trading、Market Data、Authentication 的细节应跳到对应子技能。它是协议层路由知识，不依赖某一种语言，Python/TypeScript/Go/任何 HTTP/SSE/WS 栈都能用；官方 SDK 可以加速，但不应跳过 schema 验证。涉及下单或资金前，必须对照 OpenAPI spec、文档或 alpaca-docs MCP 确认 exact payload。不要把 sandbox URL 写死，不要在同一数据客户端里混用鉴权 scheme，也不要只信任 SSE；上线前需要加 polling heal 和 reconciliation。