技能介绍

要解决的问题

给终端用户做交易界面时，订单系统不是给自己下的：请求路径里带的是 account_id，你代表某个用户账户在操作。硬啃 Alpaca 文档很容易踩三类坑：把 Broker API 和普通 Trading API 的路径搞混、下单时在 qty 和 notional 上反复 400、以及以为 PATCH 成功就等于改单成功。这个技能把 Broker 交易该注意的规则集中整理成一份可执行清单。

核心能力

订单全生命周期：创建（POST /v1/trading/accounts/{id}/orders）、按状态/标的/时间过滤查询、按 order_id 或 client_order_id 单查、PATCH 替换改单、DELETE 撤单。撤单语义要分清：撤单笔成功返回 204，已不可撤时是 422；撤全部返回 207 Multi-Status 逐单结果，平掉全部持仓同理。还有订单成本试算接口 POST .../orders/estimation。

下单字段的硬约束：type 与 time_in_force 必填；qty 与 notional 互斥——同时传直接 400，响应里没用的那个字段返回 null。两者都是最多 9 位小数的十进制字符串。client_order_id 是你的幂等键，务必从自己的流水号生成，万一创建响应丢了还能用 orders:by_client_order_id 找回。

分数股与 notional 规则：默认对所有账户开启，但资产必须 fractionable: true；time_in_force 必须是 day；notional 只支持 market/limit；分数股不允许做空，卖出一律标记为 long。

状态机与资金检查：订单生命周期是 accepted → pending_new → new → 成交，终态只有 filled / canceled / expired / rejected / replaced。注意订单 status 不等于交易事件流里的事件枚举，held 只作为 SSE 事件存在。做“花 $X”交互前先读 buying_power/cash 并按账户缓存，别让 Alpaca 替你拒单。

几个文档明确的坑：自成交会触发 wash-trade 403，同向止盈止损用 bracket/oco/trailing_stop 规避；notional 订单不能改单只能撤了重下；PATCH 返回 200 仍可能被拒，要以交易事件流为准；bracket 要求 TP/SL 同时存在且 TP 高于 SL。

适用边界

这是 Broker API 专用：独立 Trading API 用的是不带账户路径的 /v2/orders。PDT/day-trade 相关字段（daytrade_count、pattern_day_trader 等）已随 FINRA 日内保证金规则变更被废弃，依赖它们的逻辑需要迁移。定时投资场景的稳妥模式是：读取待执行指令 → 校验购买力 → 逐笔下 notional 订单 → 记录返回的订单 → 创建成功后才标记指令完成；成交跟踪走 SSE 流而不是轮询。

截图预览

使用场景

给面向终端用户的交易应用写下单接口，需要在路径里带 account_id 创建 limit/market 订单，并保证 qty 与 notional 只传其一。
用户反复重试同一笔投资指令，需要用 client_order_id 做幂等去重，并在创建成功后回写本地流水，避免重复下单。
批量执行定投买入前，需要先读 buying_power 与 cash，余额不足时取消该笔指令并通知用户，而不是让 Alpaca 拒单。
订单提交后需要按 order_id 查询状态，撤单时区分 204 与 422，遇到 notional 订单不支持改单时改成撤销后重新提交。

适合人员

券商或交易应用的后端工程师：需要在请求路径里带 account_id 代客下单、查持仓，并区分 Broker API 与独立 Trading API 的路径差异。
量化策略平台的接入开发者：需要为策略下分数股或 notional 订单，并处理 fractionable 校验、TIF 必须是 day 等限制。
定投/复投类产品的后端开发者：需要实现购买力校验后批量下单、client_order_id 幂等，并跟踪成交结果。
交易风控与排障工程师：需要依据订单状态机、wash-trade 403 与 bracket 约束，定位下单被拒或改单失败的原因。

Alpaca 券商交易订单