alpaca-broker-trading-orders

Alpaca Broker API — アカウントに代わって取引する

エンドユーザーのアカウントに対して、注文の発注、変更、キャンセル、追跡を行い、ポジションと購買余力を確認します。Broker API による取引の特徴は、パスに account_id が含まれることです。自分のアカウントではなく、ユーザーのアカウントに代わって操作します。

ベース URL と認証（クライアントクレデンシャルの Bearer トークン。従来の Basic も引き続き利用可能）については、先に alpaca-broker-integration をお読みください。（スタンドアロンの 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 title "Broker API" path /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}	1 件の注文をキャンセル（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	limit／stop 系では必須
trail_price / trail_percent	trailing_stop ではいずれか一方が必須
extended_hours	bool。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 と notional は排他的（原文どおりのルール）： どちらか一方を指定してください。両方を指定すると 400 が返されます。レスポンスでは、使用しなかった方が null になります。

3. 端株／想定元本のルール

• すべてのアカウント（ライブ＋ペーパー）でデフォルトで有効です。
• 資産の fractionable: true が必要です（Assets API を確認してください。alpaca-broker-market-data を参照）。そうでない場合は requested asset is not fractionable が返されます。
• 端株／想定元本の注文では、TIF は day である必要があります。
• 想定元本は market と limit（day）に限られます。延長時間取引では limit のみです。
• 端株の空売りはできません。端株の売りはすべて long として扱われます。
• 精度：notional は小数点以下 2 桁、qty は小数点以下 9 桁（Broker API FAQ「notional と qty の精度について」参照。注文スキーマにある qty の「小数点以下 2 桁」は古い情報です）。対象となる注文タイプ：注文スキーマでは、端株の qty は market＋day の場合のみとされています。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 取引更新ストリームでは、Broker の注文ステータスにはない運用イベントを追加した、より豊富な event 列挙型が報告されます。追加されるイベントは、trade_bust、trade_correct、restated、order_cancel_rejected、order_replace_rejected です。held は両方に含まれます。取引イベントであると同時に、Trading API の列挙型では OrderStatus ですが、Broker の列挙型にはありません。そのため、2 つの列挙型が一致するとは限りません。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 ドルを使う」という UX では、まず buying_power／cash を読み取り、資金不足の場合は注文を Alpaca に拒否させるのではなく、拒否するかユーザーに通知してください。注文が受け付けられるたびに再取得してください。注文ごとに購買余力が消費されます。

FINRA の日中証拠金ルール変更に伴い、PDT／デイトレード関連フィールドは廃止されました。現在の 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）： ユーザーの2つの注文が自己約定する可能性がある場合（反対売買で、価格が交差可能）、Alpaca によって拒否されます。反対方向の成行注文と逆指値注文の組み合わせは常に拒否されます。反対方向の指値注文は、買い指値価格が売り指値価格以上の場合に拒否されます。利確と損切りを同時に設定するには、bracket／oco／trailing_stop を使用してください。これらは拒否の対象外です。
• ブラケット注文の制約： 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）。ただし、重複排除されるのは 検索 であり、必ずしも 再送信 ではありません。ローカルで「すでに送信済みか」を確認するガードと組み合わせてください。
• 定期購入／スケジュール購入（教訓）： 堅牢な方法は、DB から保留中の投資指示を取得 → 購買余力を確認 → 指示ごとに 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。