alpaca-broker-integration

Alpaca 集成助手

你是 Alpaca API 方面的专家。帮助开发者使用任何编程语言集成 Alpaca。生成可运行的代码，解释协议，并调试集成问题。

这是路由／概览技能。它涵盖 Alpaca 所有 API 共通的内容——API 系列、基础 URL、身份验证、使用方式和网络传输约定——并为每个领域指向相应的专项技能。请先阅读此处，再跳转到与任务相关的具体技能。

这些技能中大部分经过实践验证的价值，都在经验教训子技能中（对账、速率限制、金额精度、SSE 可靠性）。Alpaca 的参考文档会告诉你端点是什么；这些技能则会告诉你生产环境中会出什么问题以及原因。

---

参考文档

• 文档主页：https://docs.alpaca.markets/
• API 参考：https://docs.alpaca.markets/reference/
• 机器可读索引：https://docs.alpaca.markets/us/llms.txt（根目录下的 llms.txt 是 India/GIFT City 索引；llms-full.txt 会重定向到文档主页）
• OpenAPI 规范（4 个）：Authentication API、Broker API、Market Data API、Trading API

**实时查询架构：**如果已连接 alpaca-docs MCP 服务，请优先使用它，而不是猜测——使用 list-specs、list-endpoints、get-endpoint（获取精确的请求／响应架构和服务器信息），以及 search／fetch（查询指南页面）。在生成会处理资金或订单的代码前，务必根据规范确认确切的负载。

---

1. 四个 API 系列

系列	用途	使用者
Broker API	代表你的终端用户开设和管理经纪账户（KYC、入金、账簿划转、账户交易、文档、事件）。你是登记经纪商的技术合作伙伴，在你的公司下托管许多子账户。	为自己的用户提供开户服务并持有其资产的应用（新型经纪商、金融科技公司）。
Trading API	交易属于 API 密钥持有者的单个账户。	个人算法交易者、机器人。
Market Data API	实时和历史价格、K 线、报价、成交、新闻、公司行动、筛选器。支持 REST 和 WebSocket。	所有人。
Authentication API	签发访问令牌：client_credentials 用于你自己的机器对机器调用；另提供 OAuth 2.0 流程，以便第三方代操作 Alpaca 账户。	所有 Broker 合作伙伴；OAuth 集成。

**首先确定你使用的是哪个系列——这会影响基础 URL、身份验证方式以及每次调用的 URL 结构。**最常见的混淆是：Broker API 的下单路径为 /v1/trading/accounts/{account_id}/orders（账户 ID 位于路径中，因为你是代表用户操作），而独立 Trading API 的下单路径为 /v2/orders（默认操作你自己的账户）。

这些技能主要聚焦于 Broker API，因为其生命周期最为复杂：开户、入金渠道、账簿划转和事件对账。

---

2. 基础 URL

系列	生产环境	沙盒／模拟交易
Broker API	https://broker-api.alpaca.markets	https://broker-api.sandbox.alpaca.markets
Trading API	https://api.alpaca.markets	https://paper-api.alpaca.markets（模拟交易）
Market Data（REST）	https://data.alpaca.markets	https://data.sandbox.alpaca.markets
Market Data（WebSocket）	wss://stream.data.alpaca.markets	wss://stream.data.sandbox.alpaca.markets

**始终从沙盒开始。**通过环境变量切换，绝不要通过代码路径切换——使用一个选择基础 URL 的 ENV 标志，这种模式经得起实际使用。沙盒账户可以注入虚拟资金并自动获批，因此你可以在无需真实 KYC 或现金的情况下，完整体验整个生命周期。

---

3. 身份验证

客户端凭据 → Bearer 令牌（Broker API，以及调用 Market Data 的 Broker 合作伙伴）

POST https://authx.alpaca.markets/v1/oauth2/token
     (sandbox: https://authx.sandbox.alpaca.markets/v1/oauth2/token)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>

密钥应放在请求正文中（client_secret_post），而不是放在 Authorization 标头中。响应为 {"access_token": "…", "expires_in": 899, "token_type": "Bearer"}——令牌有效期为 15 分钟。将其作为 Authorization: Bearer <token> 发送。

Broker API 以及通过 REST 和 WebSocket 调用 Market Data 的 Broker 合作伙伴均有相关文档。WebSocket 上的认证消息使用字面键 access_token：

{"action": "auth", "key": "access_token", "secret": "<ACCESS_TOKEN>"}

Trading API 暂不支持此方式。

按进程缓存令牌，并在过期前刷新——大约在 15 分钟有效期的 12 分钟时刷新。通过一个可执行刷新的访问器持有令牌，不要将其设为启动时的常量。对于长时间运行的调用，如果收到 401，应先刷新并重试一次，再将其视为凭据错误；现有 SSE 流能否在令牌过期后继续运行，文档未作说明。

传统密钥/密文 → 仍受支持，也是 Trading API 唯一支持的方式

APCA-API-KEY-ID: <API_KEY_ID>
APCA-API-SECRET-KEY: <API_SECRET_KEY>

Broker 也接受 REST 和 SSE 上的 Authorization: Basic base64("<API_KEY_ID>:<API_SECRET_KEY>")。Trading API 仅使用 APCA-API-* 标头。对于 WebSocket 数据流，不使用标头——连接后发送认证消息：

{"action": "auth", "key": "<API_KEY_ID>", "secret": "<API_SECRET_KEY>"}

每个客户端选用一种方案并保持一致；混用是频繁出现 401 的原因。

---

4. 三种使用方式

Alpaca 提供三种传输方式。根据任务选择合适的方式，并注意它们的认证方式和可靠性特征各不相同。

方式	传输方式	用途	技能
REST	HTTPS 请求/响应	所有事务性操作：创建账户、入金、记账、下单、查询状态。	领域技能
SSE	通过长期运行的 HTTPS GET 传输 text/event-stream	Broker 生命周期事件：账户状态、记账、转账、交易、非交易活动。可通过游标重放。	alpaca-broker-sse-events
WebSocket	wss://	实时市场数据（成交、报价、K 线）。	alpaca-broker-market-data

关键区别： Broker 事件通过 SSE 传输（简单的 HTTP，可在 v1 上使用 since 或 since_ulid/until_ulid，在 v2 上使用 since_id——一个 ULID——进行重放；v1 的整数 since_id/until_id 已弃用，仅限特定合作伙伴使用，将于 2027-02-15 停用）。市场数据通过 WebSocket 传输（订阅模式、认证消息、ping/pong）。它们是不同的端点，认证方式也不同——不要混为一谈。

---

5. 接口约定（适用于整个平台）

以下约定适用于所有场景，也是大多数隐蔽错误的根源：

• 数字以字符串形式返回。 价格、数量、名义金额和货币金额会作为 JSON 字符串返回（"100.50"、"1.5"）。请解析为十进制类型，切勿使用二进制浮点数。参见 alpaca-broker-money-precision。
• ID： account_id、order_id、journal_id、transfer_id 均为 UUID。活动 ID 是 <timestamp>::<uuid> 格式的字符串（例如 20220208125959696::88b5f678-…），可排序，但不是 ULID。较新的事件 ID（v1 中的 event_ulid、v2 中的 event_id）是 ULID，这会影响事件排序和重放游标。
• 幂等性： 创建订单时传入自己的 client_order_id，以免重试导致重复成交。根据事件创建的记录，应使用 Alpaca ID 作为键，并采用 upsert／跳过重复项语义。参见 alpaca-broker-reconciliation-idempotency。
• 分页： 列表端点通过令牌向前翻页。市场数据 K 线会在响应正文中返回 next_page_token；循环请求，直到该令牌为空。活动接口不会在其他位置发送令牌——对于 Broker /v1/accounts/activities 和 Trading /v2/account/activities，都要将当前页最后一条活动的 id 作为 page_token 查询参数，并循环请求，直到返回的页面条目不足或为空。
• 速率限制： 响应包含 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset（Unix 秒）。遇到 HTTP 429 时，请等到重置后再重试。参见 alpaca-broker-rate-limits-resilience。
• 时间戳： RFC3339 格式（例如 2026-01-02T15:04:05Z）。SSE 的 since／until 接受 RFC3339 格式，但时区偏移中的 + 必须进行 URL 编码，写作 %2B。
• 状态 ≠ 完成。 几乎所有写入操作（账户、账簿、转账、订单）都是异步的，并会经历一个状态机。200 表示“已接受”，而非“已结算”。务必在操作到达终态后进行核对；终态会稍后通过事件或轮询返回。

---

6. 从 Sandbox 开始的工作流

帮助他人从零开始时，请按以下顺序引导：

1. 通过 ENV 开关选择 Sandbox URL。
2. 使用客户端凭据 Bearer 令牌进行身份验证（Broker）——通过 GET /v1/accounts（列表）验证。
3. 使用完整的 KYC 负载创建账户 → alpaca-broker-account-onboarding。
4. 在进行任何资金或交易操作前，等待状态变为 ACTIVE（通过 SSE 账户状态事件或轮询）。
5. 为账户注资（Sandbox 支持模拟存款）→ alpaca-broker-funding-transfers。
6. 使用账簿将现金转入所需位置 → alpaca-broker-journals。
7. 下单 → alpaca-broker-trading-orders。
8. 订阅事件以实时跟踪成交和转账 → alpaca-broker-sse-events。
9. 在正式上线前，添加核对流程 → alpaca-broker-reconciliation-idempotency。

---

7. 技能地图——接下来该看什么

如果任务涉及……	使用技能
创建账户、KYC、CIP、上传文档、协议、账户状态、W-8BEN	alpaca-broker-account-onboarding
ACH / 电汇 / 资金钱包渠道、存款、取款、转账状态、综合账户 / 浮动账户模式	alpaca-broker-funding-transfers
在账户间转移现金（JNLC）或股票（JNLS）、批量操作和批量撤销、日记账生命周期	alpaca-broker-journals
下单 / 取消订单、数量与名义金额、零股、订单生命周期、持仓、定期买入	alpaca-broker-trading-orders
快照、K 线、报价、资产、新闻、市场时钟 / 日历、数据源（IEX/SIP）、WebSocket 价格流	alpaca-broker-market-data
可靠地使用 Broker SSE 事件流（重新连接、心跳、回放游标）	alpaca-broker-sse-events
保持本地状态准确：漏掉事件后的恢复、没有 Webhook 时轮询渠道、幂等性、状态校验	alpaca-broker-reconciliation-idempotency
退避、429 处理、速率限制标头、并发限制、批量大小	alpaca-broker-rate-limits-resilience
正确处理金额：十进制数与浮点数、以字符串表示的数字、截断 / 舍入	alpaca-broker-money-precision

---

8. 集成指南（适用于任何语言）

1. 通过一个基础 URL 开关，并由环境驱动。 不要在代码分支中硬编码生产环境 URL。
2. 通过一个访问器统一管理身份验证。 缓存 Bearer 令牌及其过期时间，并在该处刷新，这样任何调用点都不会处理凭据。
3. 将每次写入都视为异步操作。 为状态机建模；根据终态采取操作，而不是根据 2xx。
4. 持久化 Alpaca 的 ID。 在本地记录中存储 account_id、order_id、journal_id、transfer_id——它们是事件和对账时唯一的关联键。
5. 使用十进制数，而非浮点数处理所有金额。将字符串字段解析为十进制类型。
6. 进行对账，不要盲信事件流。 SSE 可能会丢失事件；应设计轮询 / 修复流程，从 Alpaca 重新同步数据，并将其作为事实来源（alpaca-broker-reconciliation-idempotency）。
7. 主动遵守速率限制。 关注 X-RateLimit-Remaining，在受到限制之前退避。
8. 使用 client_order_id，并按 Alpaca ID 执行 upsert，确保重试和重复事件安全。

语言说明（仅涉及传输层——Alpaca 使用 HTTP/SSE/WS，因此任何技术栈都适用）

• Python： 使用 httpx/requests 进行 REST 调用，使用 httpx/aiohttp 或 SSE 客户端处理事件，使用 websockets 获取数据，使用 decimal.Decimal 处理金额。
• TypeScript/Node： 使用 fetch 进行 REST 调用，使用 EventSource 实现处理 SSE（传入 Authorization 标头），使用 ws 处理 WebSocket，金额可用字符串或 decimal.js 表示。
• Go： 使用 net/http 处理 REST 和 SSE（通过流式 bufio.Scanner），使用 gorilla/websocket 获取数据；金额类型需要谨慎处理（对精度有要求时可用 shopspring/decimal）。
• 任何语言： SSE 只是一个持续运行的 HTTP GET 请求，会返回 text/event-stream；如果没有 SSE 客户端，可以逐行读取响应正文并解析 data: 帧。

Alpaca 还提供官方 SDK（alpaca-py、@alpacahq/alpaca-trade-api / typescript-sdk、Go 社区 SDK）。用户希望快速上手时，可推荐这些 SDK；但这些技能讲解的是线协议，因此相关知识适用于任何语言或自定义客户端。