alpaca-broker-trading-orders

Alpaca Broker API — 代表账户进行交易

为终端用户账户下单、修改、取消和跟踪订单，并读取持仓和购买力。Broker API 交易的标志性特征是：路径中包含 account_id——你代表用户账户操作，而不是操作自己的账户。

首先阅读 alpaca-broker-integration，了解基础 URL 和身份验证（客户端凭据 Bearer 令牌；旧版 Basic 仍可用）。（独立的 Trading API 使用 /v2/orders，路径中不含账户信息；此处的其他内容均适用。）

参考资料

• 指南：https://docs.alpaca.markets/docs/orders-at-alpaca、https://docs.alpaca.markets/docs/fractional-trading
• API 参考：https://docs.alpaca.markets/reference/postorder
• 实时架构：alpaca-docs MCP → get-endpoint 标题 "Broker API"，路径 /v1/trading/accounts/{account_id}/orders

1. 端点

方法	路径	用途
POST	/v1/trading/accounts/{id}/orders	创建订单
GET	/v1/trading/accounts/{id}/orders	列出订单（按 status、symbols、after 等筛选）
GET	/v1/trading/accounts/{id}/orders/{order_id}	按 ID 获取订单
GET	/v1/trading/accounts/{id}/orders:by_client_order_id?client_order_id=…	按你的客户端 ID 获取
PATCH	/v1/trading/accounts/{id}/orders/{order_id}	替换（修改）订单
DELETE	/v1/trading/accounts/{id}/orders/{order_id}	取消单个订单（204）
DELETE	/v1/trading/accounts/{id}/orders	取消全部订单（207 Multi-Status）
POST	/v1/trading/accounts/{id}/orders/estimation	估算订单成本
GET / DELETE	/v1/trading/accounts/{id}/positions[/{symbol_or_asset_id}]	列出 / 平仓
GET	/v1/trading/accounts/{id}/account	交易账户详情（购买力等）

2. 创建订单请求

架构要求：type 和 time_in_force。有条件要求：symbol、side，以及 qty / notional 中的其中一项。

// notional market buy (dollar-based, fractional)
{ "symbol": "AAPL", "notional": "25.00", "side": "buy", "type": "market", "time_in_force": "day",
  "client_order_id": "your-own-uuid" }

// limit qty sell
{ "symbol": "AAPL", "qty": "3", "side": "sell", "type": "limit", "limit_price": "190.00", "time_in_force": "gtc" }

字段	值 / 说明
symbol	必填（mleg 多腿期权除外）
qty	十进制字符串，最多 9 位小数；根据订单架构，仅 market + day 订单支持小数股
notional	十进制字符串，最多 2 位小数。不能与 qty 同时使用
side	buy、sell（以及高级选项：sell_short、…）
type	market、limit、stop、stop_limit、trailing_stop
time_in_force	day、gtc、opg、cls、ioc、fok
limit_price / stop_price	限价 / 止损订单类型必填
trail_price / trail_percent	trailing_stop 必须提供其中一项
extended_hours	布尔值；仅适用于 type=limit 且 TIF 为 day / gtc 的订单
client_order_id	≤128 个字符；你的幂等键（省略时自动生成）
order_class	simple（默认）、bracket、oco、oto、mleg
take_profit / stop_loss	对于 bracket / oco / oto，分别为 {limit_price} / {stop_price, limit_price?}
position_intent	buy_to_open、sell_to_close、…

**qty XOR notional（原文规则）：**二选一传入——两者都提供会返回 400。在响应中，未使用的字段会返回 null。

3. 小数股 / 名义金额规则

• 默认对所有账户启用（实盘 + 模拟）。
• 资产必须为 fractionable: true（检查 Assets API——参见 alpaca-broker-market-data），否则会提示 requested asset is not fractionable。
• 小数股 / 名义金额订单的 TIF 必须为 day。
• 名义金额仅适用于 market 和 limit（day）；扩展交易时段仅适用于 limit。
• 小数股不可卖空——所有小数股卖单都会标记为多头。
• 精度：notional 为 2 位小数，qty 为 9 位小数（Broker API FAQ 中的 “What is the precision for notional and qty”；订单架构中 qty 的 “2 decimal points” 已过时）。适用的订单类型：订单架构规定，仅 market + day 支持小数 qty；Fractional Trading 指南还允许 TIF 为 day 的 limit / stop / stop_limit 订单——依赖更宽泛的支持范围前，请先在沙盒中确认。

4. 订单状态生命周期

OrderStatus（订单对象的 status）：new、partially_filled、filled、done_for_day、canceled、expired、replaced、pending_cancel、pending_replace、accepted、pending_new、accepted_for_bidding、stopped、rejected、suspended、calculated。

订单的 status ≠ 交易事件的 event。 订单对象的 status 是上面的枚举。SSE 交易更新流报告更丰富的 event 枚举，其中增加了没有对应 Broker 订单状态的操作事件：trade_bust、trade_correct、restated、order_cancel_rejected、order_replace_rejected。held 两者皆是：它既是交易事件，也是 Trading API 枚举中的 OrderStatus，但不属于 Broker 的枚举，因此不要假设两个枚举相同。参见 alpaca-broker-sse-events。

终态： filled、canceled、expired、rejected（原始订单的 replaced 也属于终态）。其他所有状态均表示仍在处理中。

早期状态的区别（容易混淆）：

• accepted — Alpaca 已收到订单，但尚未将其路由至交易场所（非市场交易时段较常见）。
• new — 已收到订单，并已路由至交易所；这是常见的初始活动状态。
• pending_new — 已路由，但尚未获准执行（罕见）。

订单通常会直接进入 new；accepted/pending_new 是罕见的中间状态。要点： 将 new/accepted/pending_new 视为“订单已存在，但尚未完成”。提交时保存订单，然后根据成交/取消/拒绝事件进行更新——不要同步阻塞用户，等待订单进入终态。

5. 持仓与交易账户

Position 关键字段：symbol、asset_id、qty、qty_available（未被未结订单占用的数量）、side（long/short）、avg_entry_price、market_value、cost_basis、unrealized_pl、unrealized_plpc、current_price、change_today。

TradeAccount 关键字段：

• buying_power（保证金 multiplier 为 1–4）、cash、cash_withdrawable、equity、last_equity。
• 限制项：trading_blocked、account_blocked、transfers_blocked、trade_suspended_by_user。
• multiplier、regt_buying_power、non_marginable_buying_power、long_market_value、initial_margin、maintenance_margin、sma。

要点——提交按名义金额下单前先检查购买力。 对于“支出 $X”的用户体验，先读取 buying_power/cash，如果资金不足则拒绝或通知用户，而不是等 Alpaca 拒绝订单。每笔订单获准后都要重新读取这些值——每笔订单都会占用购买力。

PDT/日内交易字段已移除，原因是 FINRA 修改了日内保证金规则：当前 TradeAccount 架构中不再包含 daytrade_count、pattern_day_trader、daytrading_buying_power 和 bod_dtbp，dtbp_check/pdt_check 配置也已移除。不要再针对这些字段编写代码。

6. 已记录的注意事项

• 最低订单金额： 每笔买单的市场价值至少需要 $1，否则会因 422 被拒绝；卖单不受此限制。
• 各资产类别的规则： 期权和加密货币也通过同一端点处理，并由 asset_class 控制 — 加密货币不接受 time_in_force: day（仅支持 gtc/ioc），且只允许 market/limit/stop_limit；期权仅允许 day/gtc。请查看 https://docs.alpaca.markets/reference/createorderforaccount 中 OrderType/TimeInForce 的类型/TIF 矩阵，不要想当然地套用股票规则。
• 洗售交易拒绝（403）： 如果用户的两笔订单可能互相成交（方向相反且价格可交叉），Alpaca 会拒绝。方向相反的市价单/止损单组合一律会被拒绝；买入限价 ≥ 卖出限价时，方向相反的限价单也会被拒绝。如需同时设置止盈 + 止损，请使用 bracket/oco/trailing_stop — 这些订单不受此限制。
• Bracket 订单限制： 必须同时提供 take_profit.limit_price 和 stop_loss.stop_price；买入订单的 TP 必须高于 SL；不支持延长交易时段；TIF 仅支持 day/gtc；只有在入场订单全部成交后，子订单才会激活；取消其中一笔会取消整个订单组。
• 名义金额订单无法替换 — 请取消后重新提交（IPO 类名义金额订单除外）。替换订单时无法修改零碎股 qty（“仅限整股”）。
• 替换 ≠ 保证成功： PATCH 返回 200 后，仍可能因原订单先成交而被拒绝；请关注交易更新流。订单处于 accepted/pending_new/pending_cancel/pending_replace 状态时无法替换。
• 取消语义： 取消单笔订单 → 204；如果订单已不可取消，则返回 422；取消全部订单 → 按每笔订单返回结果的 207；平仓所有持仓 → 207。平仓单笔持仓时，qty 和 percentage 只能二选一。

7. 幂等性与定期投资经验

• 务必设置 client_order_id，并使用你自己的交易记录生成该值。它是去重键，也可在创建响应丢失时用于查询订单（orders:by_client_order_id）。请注意，它用于去重查询，不一定能防止重放 — 请结合本地的“是否已提交？”检查。
• 定期/计划买入（经验）： 稳健的模式是 — 从数据库获取待处理的投资指令 → 检查购买力 → 针对每条指令提交一笔 notional market/day 订单 → 记录返回的订单 → 仅在成功创建后将指令标记为已完成。资金不足时，跳过本次执行并提示；是否取消长期有效的指令属于产品决策。请在市场开盘前不久安排批量操作，并遵循市场时钟（alpaca-broker-market-data）。
• 通过交易事件 SSE 流跟踪成交，而不是逐笔轮询订单 — 参见 alpaca-broker-sse-events。

相关技能： 价格/资产/时钟 → alpaca-broker-market-data；实时成交 → alpaca-broker-sse-events；批量下单的速率限制 → alpaca-broker-rate-limits-resilience；金额格式化 → alpaca-broker-money-precision。