Alpaca 券商交易订单

要解决的问题

当你的系统以 broker / white-label 模式代客交易时，订单不是发到「自己的账户」，而是发到某个终端用户的账户。Alpaca 的独立 Trading API 只需 /v2/orders，但 Broker API 把 account_id 放进了路径：所有订单、持仓、账户查询都要指明为哪个用户执行。这个技能解决的正是：如何在 Broker API 下替指定账户完成从下单到撤单的完整交易闭环，同时避开文档明确记录的坑。

核心能力

覆盖订单生命周期的全部操作：

• 下单：POST /v1/trading/accounts/{account_id}/orders
• 查询：列表（支持 status、symbols、after 过滤）、按 order_id 或 client_order_id 取单个订单
• 修改与撤销：PATCH 替换订单、删除单笔（204）、批量撤单（207）
• 成本预估：POST .../orders/estimation
• 持仓：列出、按 symbol 查询、平仓（全部或单笔，qty 与 percentage 二选一）
• 账户：读取 buying_power、cash、equity 等交易账户字段

下单请求里有几个容易出错的点：type 与 time_in_force 必填；qty 与 notional 互斥，两个都传直接 400，响应里未使用的字段返回 null；两者均为最多 9 位小数的十进制字符串；分数股默认开启，但资产必须 fractionable: true 且 time_in_force 只能是 day，分数股卖出一律标记 long、不能做空；client_order_id 是你的幂等键，应从本地交易记录生成，响应丢失后仍可用它反查订单。

状态机与注意点

订单状态不是非黑即白。典型启动序列是 accepted → pending_new → new，其中 accepted 仅表示 Alpaca 收到单、尚未路由到交易所。终态只有 filled、canceled、expired、rejected。正确做法是提交后立即持久化订单，再通过 SSE 交易事件流异步推进状态，而不是让用户同步等待终态。

文档明确记录的坑：

• 对冲自成交会被拒（403）：同账户内方向相反且价格可成交的订单会触发洗单拒绝，同时下止盈+止损应使用 bracket / oco / trailing_stop，它们豁免该规则
• bracket 必须同时给出 take_profit.limit_price 与 stop_loss.stop_price，且不支持 extended hours
• notional 订单不能 PATCH 替换，只能撤单重下（IPO 类名义单除外）
• PATCH 返回 200 也不保证替换成功，原单可能已成交，需盯交易事件流
• 下单前先读 buying_power / cash：「花 $X」这类场景自己拦截比让 Alpaca 拒单体验更好
• PDT / 当日交易字段（daytrade_count 等）已于 2026-04 弃用，不要再依赖

定期定投的可靠模式：从库里拉待执行指令 → 查购买力 → 逐条下 notional market/day 单 → 记录返回的订单 → 创建成功后才标记指令完成；资金不足时撤销指令并通知，而不是静默跳过。