alpaca-trading-paper-trading

Name: alpaca-trading-paper-trading
Author: alpacahq

github.com/alpacahqその他157140 回インストール1 週間前に更新

リポジトリ

alpaca-trading-paper-trading について

Alpaca Trading API を使うユーザー向けに、AI エージェントがペーパートレードの注文をプレビュー、送信、管理する手順を示すスキルです。戦略の確認からパラメーター検証、送信後の追跡までを扱い、ライブ注文を明確に禁止します。

主な機能

01戦略ロジックと注文内容を確認
02口座と資産クラスの設定を検証
03送信前に注文全体をプレビュー
04注文ごとの確認または自動送信
05注文ステータスと約定を追跡
06ライブ注文を確実に遮断

活用シーン

01バックテストシグナルの注文案を検証
02手動の取引案からペーパー注文を作成
03アラートやスケジュール起点の注文を処理
04約定、拒否、キャンセルの結果を確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/alpacahq/alpaca-skills --skill alpaca-trading-paper-trading

インストール後、Claude Code で/alpaca-trading-paper-tradingを入力して読み込まれたか確認します。

同梱ファイルreference.md

詳細

Alpaca ペーパートレーディング

Alpaca の Trading API を使用して、ペーパートレーディングの注文をプレビュー、送信、確認、管理したい場合に、このスキルを使用してください。

このスキルは、Trading API を利用して自身の Alpaca ペーパートレーディングアカウント、認証情報、ローカルワークスペースを扱うユーザー向けです。エージェントは、前提を明確にし、秘密情報を保護し、注文の送信前に詳細を確認する必要があります。

これは、特定の実装に依存しない汎用版のペーパートレーディングスキルです。特定の実行ツールに限定せず、ワークフロー、安全確認、出力仕様について説明します。Alpaca Python SDK（alpaca-py）、REST API の直接利用、JavaScript/TypeScript、Go、C#、または Trading API に対応する任意のツールを使用できます。CLI や MCP を使用したいユーザー向けに、それぞれに特化したコンパニオンスキルも用意されています。リンクについては §10 を参照してください。

0 - AI エージェントによるこのスキルの使用方法

まず、実行する作業を確認します。 シグナルがバックテストの出力、手動の取引アイデア、スケジュールされたトリガー、自動システムイベントのいずれであるかを特定します。エージェントは関連するコンテキスト（バックテストの実行フォルダー、戦略の説明、アラートのペイロードなど）を読み取り、意図を把握します。
戦略のロジックを言い換えて確認します。 エージェントは戦略の解釈（エントリー／イグジット条件、インジケーターのパラメーター、ポジションサイズ、前提など）を平易な言葉で説明し、続行する前に、その解釈が正しいかユーザーに確認します。
実行前に、詳細な設定をすべて収集して確認します。 エージェントは、注文のすべてのパラメーターを明示的に収集します。
- 実行タイミング（即時、スケジュール、条件付き）
- 資産クラス（米国株、米国オプション、暗号資産）
- シンボル
- 売買区分（買い／売り）
- 数量または想定元本
- 注文タイプ（market、limit、stop、stop_limit、trailing_stop）
- 有効期間（day、gtc、ioc、fok、opg、cls）
- 該当する場合は指値価格および／または逆指値価格
- 時間外取引フラグ
- リスク管理（最大ポジションサイズ、最大想定元本、損切り、利益確定）
- 証拠金の使用
使用するペーパーアカウントを確認します。 エージェントは、ペーパーアカウントの設定が戦略の要件を満たしていること（オプションの承認レベル、暗号資産取引の有効化、信用取引口座か現金口座か、PDT ステータスなど）を検証します。機能が有効になっていると、確認なしに決めつけることはありません。
送信前に、注文プレビューをすべて表示した表を提示します。 各注文について、すべてのパラメーター、想定元本、購買余力の確認結果を含む視覚的なプレビューを表示します。プレビューなしで注文を送信することはありません。
確認方法の希望を尋ねます。 エージェントは、注文を送信するたびに明示的な確認を行うか、自動送信モードを希望するかを尋ねます。セッション中はユーザーの希望に従います。デフォルト：確認 ON。
ペーパートレーディング環境にのみ注文を送信します。 エージェントは送信のたびに環境がペーパーであることを検証します。ライブ環境には決して送信しません。
送信後の詳細をすべて提示します。 送信後、エージェントは注文 ID、ステータス、送信したペイロードの概要、次に確認すべき手順を提示します。
注文のライフサイクルを監視し、状況を更新します。
- 約定 → 株式／契約の約定数量、約定価格、約定によるポートフォリオリスクの変化。
- 一部約定 → 現在の約定数量と残数量、これまでの平均約定価格。
- 拒否 → 拒否理由と、具体的な対処方法。
- キャンセル → 誰が（ユーザー、システム、ブローカー）キャンセルしたか、その理由。
ライブ取引は決して行いません。 ライブ用の認証情報が検出された場合（ベース URL に paper- のプレフィックスがない、またはプロファイルがライブに設定されている場合）、エージェントは直ちに停止し、警告します。これは警告にとどまらない、必須のブロックです。

1 - 前提条件

Alpaca のペーパートレード口座 — alpaca.markets で無料で作成できます
ペーパー API キーとシークレットキーを環境変数（APCA_API_KEY_ID、APCA_API_SECRET_KEY）または SDK／CLI プロファイルに保存してください — チャットに貼り付けないでください
ペーパー環境のベース URL：https://paper-api.alpaca.markets（REST の場合）、またはペーパー環境を指定する適切な SDK 設定
オプションの場合：ペーパー口座で、適切な承認レベル（カバードコールとキャッシュセキュアド・プットはレベル 1、コールとプットの購入はレベル 2、スプレッドとストラドルはレベル 3）のオプション取引が有効になっている必要があります
暗号資産の場合：ペーパー口座で暗号資産取引が有効になっている必要があります
SDK／言語ランタイム（いずれかを選択）：
- Python 3.10 以降と alpaca-py（推奨）
- @alpacahq/alpaca-trade-api（v4 以降、公式提供で積極的にメンテナンスされています）を使用する JavaScript／TypeScript
- github.com/alpacahq/alpaca-trade-api-go/v3 を使用する Go — /v3 サフィックスは必須です。付けない場合は v1 のパスが取得されます
- Alpaca.Markets（公式提供）を使用する C#。Java などにはコミュニティ製 SDK もあります。
- curl、httpx、requests、または任意の HTTP クライアントを使用した直接の REST API 呼び出し
Alpaca API（paper-api.alpaca.markets）へのネットワークアクセス

2 - 入力情報の収集

必須入力

入力	説明	デフォルト
`signal_source`	取引アイデアの出所（バックテスト、手動、自動化）	指定必須
`symbol`	ティッカーシンボル（例：オプションの場合は `AAPL`、`BTC/USD`、`AAPL250718C00200000`）	指定必須
`side`	`buy` または `sell`	指定必須
`qty_or_notional`	株数／契約数、または金額（株数／契約数には `qty`、金額には `notional` を使用）	指定必須
`order_type`	`market`、`limit`、`stop`、`stop_limit`、`trailing_stop` — サポートされる値は資産クラスによって異なります。以下を参照してください	`market`
`time_in_force`	`day`、`gtc`、`ioc`、`fok`、`opg`、`cls` — サポートされる値は資産クラスによって異なります。以下を参照してください	株式は `day`、暗号資産は `gtc`

資産クラスごとの制約

API はこの表にない組み合わせを拒否するため、エージェントは送信後ではなく送信前に検証します。

資産クラス	注文タイプ	有効期間	注文クラス
`us_equity`	`market`、`limit`、`stop`、`stop_limit`、`trailing_stop`	`day`、`gtc`、`opg`、`cls`、`ioc`、`fok`	`simple`、`bracket`、`oco`、`oto`
`us_option`	`market`、`limit`、`stop`、`stop_limit`（`stop` タイプは単一レッグのみ）	`day`、`gtc`	`simple`、`mleg`
`crypto`	`market`、`limit`、`stop_limit`	`gtc`、`ioc` — `stop_limit` は `gtc` のみで、`ioc` は `market` と `limit` にのみ適用されます	`simple`

これは注文の構成に関するガイダンスとして扱い、送信前の厳格なゲートとしては扱わないでください。Alpaca の情報源間でオプションの行に食い違いがあります。OpenAPI の TimeInForce／OrderType の説明では market／limit と day のみとなっていますが、Options Trading ページと Placing Orders の表では gtc が許可され、単一レッグ注文の stop／stop_limit もどちらも許可されています。2 つの製品ページの内容が仕様データより一致しているため、この表では製品ページに従っています。安全策として、オプションのデフォルトは day としますが、表で許可されている組み合わせを事前にブロックせず、Alpaca に拒否させてください。

注文タイプをまたぐ制約：

時間外取引には、day または gtc の TIF を指定した limit タイプが必要です。それ以外はすべて拒否されます。
トレーリングストップで受け付けられるのは day と gtc のみです。
Notional 注文は qty と組み合わせることができず、置き換えもできません — 代わりにキャンセルして再送信してください。株式の場合はさらに、day TIF の market タイプが必要です。暗号資産の notional 注文は market タイプで、暗号資産の TIF セット（gtc／ioc）を使用するため、株式に適用される day の制限は適用されません。
Bracket、OCO、OTO は株式のみで、day または gtc が必要です。また、時間外取引には対応していません。
mleg は最大 4 レッグを保持でき、複数レッグのオプション戦略を表すために使用します。

任意の入力

入力	説明	デフォルト
`limit_price`	`limit` 注文および `stop_limit` 注文で必須です	None
`stop_price`	`stop` 注文および `stop_limit` 注文で必須です	None
`trail_price` または `trail_percent`	トレーリングストップ注文用です（どちらか一方のみ指定し、両方は指定しません）	None
`extended_hours`	時間外取引での執行を許可します（株式のみ。`day` または `gtc` の TIF を指定した `limit` タイプ）	`false`
`client_order_id`	ユーザーが指定する冪等性キー（最大 128 文字）	UUID を自動生成
`confirmation_mode`	注文ごとにエージェントが明示的な確認を求めるかどうか	`on`
`risk_controls`	最大ポジションサイズ、最大想定元本、最大損失しきい値	None（設定を推奨）
`asset_class`	`us_equity`、`us_option`、`crypto`	シンボルの形式から推定
`order_class`	`simple`、`bracket`、`oco`、`oto`、`mleg` — 上記の資産クラス別マトリックスを参照してください	`simple`
`position_intent`	`buy_to_open`、`buy_to_close`、`sell_to_open`、`sell_to_close`（オプションのみ）	コンテキストから推定

戦略の確認チェックリスト

設定フェーズを終えて先に進む前に、エージェントは以下の各項目をあなたに確認する必要があります。

戦略ロジックの解釈が正しい — エージェントによる戦略の言い換えが、あなたの意図と一致している
タイミング — 即時執行、または予約／条件付き（例：「価格が $180 を下回った場合のみ」）
資産クラスとシンボルが正しい — 正しいティッカー、正しい契約（オプションの場合）、正しい通貨ペア（暗号資産の場合）
注文パラメーターが戦略の意図と一致している — タイプ、売買方向、数量、価格、TIF がすべて希望どおりである
ペーパー口座がこの資産クラス用に設定されている — オプションの承認、暗号資産の有効化、証拠金の種類
リスク管理が設定されている（または明示的に免除されている） — ポジションサイズ、損切り、集中度の上限を了承している

3 - 参照元

情報源	URL	用途
Trading API の概要	https://docs.alpaca.markets/us/docs/trading-api	API の機能と構成
注文の操作	https://docs.alpaca.markets/us/docs/working-with-orders	注文の送信、置換、キャンセル
Alpaca の注文	https://docs.alpaca.markets/us/docs/orders-at-alpaca	注文タイプ、TIF の値、ステータスのライフサイクル
ペーパートレーディング	https://docs.alpaca.markets/us/docs/paper-trading	ペーパー環境の動作と制限
ポジションの操作	https://docs.alpaca.markets/us/docs/working-with-positions	ポジションの取得と管理
口座の操作	https://docs.alpaca.markets/us/docs/working-with-account	口座の状態、購買力、デイトレード回数
資産の操作	https://docs.alpaca.markets/us/docs/working-with-assets	取引可能性の確認、資産属性
オプション取引	https://docs.alpaca.markets/us/docs/options-trading	オプション注文の詳細、承認レベル
暗号資産取引	https://docs.alpaca.markets/us/docs/crypto-trading	暗号資産注文の詳細、対応通貨ペア
Alpaca の開示事項	https://alpaca.markets/disclosures	必要な開示文言

4 - ワークフロー

フェーズ 1：戦略の確認

ステップ 1 — シグナルの発生元を特定します。 エージェントが、取引アイデアの発生元を特定します。

バックテストの出力：実行フォルダー（notes.md、summary.json）を読み取り、戦略のロジック、確認済みのパラメーター、最後のシグナルを抽出します。シグナルを解析して、銘柄、売買方向、数量、価格目標があればその内容を特定します。
手動のアイデア：自然言語で取引内容を説明します。エージェントがパラメーターを抽出し、確認の質問をします。
自動化システム：Webhook、アラート、またはスケジュールされたトリガーを使用します。エージェントがペイロードを読み取り、注文パラメーターにマッピングします。

ステップ 2 — 戦略のロジックを再確認します。 エージェントが、戦略をどのように解釈したかを平易な言葉で詳しく説明します。

取引のトリガーとなる条件（エントリー条件）
取引を終了する条件（決済条件、損切り、利益確定）
インジケーターのパラメーター（例：「20 日 SMA と 50 日 SMA のクロスオーバー」）
ポジションサイジングのルール（例：「取引ごとにポートフォリオの 1% をリスクにさらす」）
エージェントが設定している前提（例：「成行価格でエントリーする想定」）

ステップ 3 — 解釈を確認します。 エージェントが、説明した内容を確認または訂正するよう求めます。確認されるまで先には進みません。訂正があった場合、エージェントは訂正内容を反映した説明を改めて提示し、再度確認を求めます。

フェーズ 2：設定の合意

ステップ 4 — 注文パラメーターをすべて収集します。 §2 の入力テーブルを使用して、エージェントは必須および任意のパラメーターをすべて収集します。すでに指定されていない項目があれば、質問します。

ステップ 5 — パラメーターの出所を示します。 各パラメーターについて、エージェントは次の情報を示します。

使用する値
その値があなたによって提供されたものか、コンテキストから推定されたものか（例：シンボル形式から資産クラスを推定）、標準値に設定されたものか

例：

Symbol:        AAPL           (provided)
Side:          buy            (provided)
Quantity:      50 shares      (provided)
Order type:    limit          (provided)
Limit price:   $180.00        (provided)
TIF:           day            (defaulted — standard for equities)
Extended hrs:  false          (defaulted)
Client order:  a7b3c9d1-...   (auto-generated)

ステップ 6 — タイミングを確認します。 エージェントは執行タイミングを確認します。

即時：現在の取引時間中に、ただちに発注します
スケジュール設定：特定の時刻に発注します（エージェントは外部のスケジュール設定が必要であることを伝えます）
条件付き：条件が満たされた場合にのみ発注します（エージェントは監視ロジックが必要であることを伝えます）

タイミングが即時でない場合、エージェントは必要なツールと、設定を支援できるかどうかを説明します（デプロイのガイダンスについては §4 のフェーズ 8 を参照してください）。

ステップ 7 — 資産クラス固有の項目を確認します。

米国株式の場合：

assets エンドポイントを使用して、シンボルが取引可能か確認します
数量に小数が含まれる場合は、端株の取引が可能か確認します
extended_hours が true の場合は、時間外取引が可能か確認します（対象となるのは limit 注文のみです）
売却代金の決済が T+1 であることを伝えます

米国オプションの場合：

コントラクトシンボルが OCC のシンボル表記に準拠しているか検証します：AAPL250718C00200000
- ルートシンボル（AAPL）、満期日（250718 = 2025 年 7 月 18 日）、コール／プット（C/P）、行使価格 × 1000（00200000 = $200.00）
満期日、行使価格、プット／コールを確認します
ポジションの意図を確認します：新規買い、買い戻し、新規売り、売り決済
コントラクト倍率を伝えます：1 コントラクト = 原資産 100 株
口座のオプション取引承認レベルが、戦略の要件を満たしているか確認します
満期日までの取引日数が 5 日以内の場合は、満期リスクについて警告します

暗号資産の場合：

ペア形式を確認します（例：BTC/USD、ETH/USD）
24 時間 365 日取引可能で、市場時間の制約がないことを伝えます
ペアの最小注文数量を確認します
口座で暗号資産取引が有効になっているか確認します

ステップ 8 — リスク管理を確認します。 エージェントはリスク管理について質問します。

最大ポジションサイズ：1 つのポジションで保有できる株式／コントラクトの最大数
ポートフォリオの最大配分：1 つのシンボルに配分できるポートフォリオの資産価値の最大割合
損切り：損失が出ているポジションを決済する価格または割合
利益確定：利益を確定する価格または割合

リスク管理を設定していない場合、エージェントは設定を検討するよう勧めます。今設定するか、設定せずに進むかを質問します。設定せずに進む場合、エージェントはその旨をセッションログに記録します。

ステップ 9 — 証拠金の使用を確認します。 エージェントは次の項目を確認します。

account.multiplier による証拠金の分類 — アカウントオブジェクトに account_type フィールドはありません。1 は限定的な証拠金を使用する現金口座型、2 は日中および翌日の買付余力が 2 倍の Reg T 証拠金口座、4 は日中 4 倍、翌日 2 倍の PDT 口座です
戦略で必要となる可能性があるため、空売りが許可されているか（account.shorting_enabled）
現在の買付余力（account.buying_power）および、オプションの場合は account.options_buying_power
現在の資産価値（account.equity）
証拠金を使用する場合は、維持証拠金の必要額（account.maintenance_margin）

フェーズ 3：ペーパー口座の確認

ステップ 10 — 環境がペーパーであることを確認します。 エージェントはベース URL、SDK の設定、または CLI プロファイルを確認し、環境がライブではなくペーパーであることを確かめます。

確認項目	ペーパー	ライブ（ブロック）
REST ベース URL	`https://paper-api.alpaca.markets`	`https://api.alpaca.markets`
SDK 設定	`paper=True` または同等の設定	`paper=False` または設定なし
CLI プロファイル	ペーパープロファイルが選択済み	ライブプロファイルが選択済み

ライブの認証情報が検出された場合は、直ちに停止します。エージェントは明確な警告を表示し、処理を続行しません。エージェントが代わりに「ペーパーに切り替える」ことは提案しません。認証情報は自分で再設定する必要があります。

ステップ 11 — 口座のステータスを取得します。 エージェントは口座情報を取得し、次の項目を確認します。

status が ACTIVE または PAPER_ONLY であること。このスキルではペーパー専用口座も有効であり、ブロックしてはいけません
trading_blocked が false であること
account_blocked が false であること
trade_suspended_by_user が false であること
buying_power が予定している注文に十分であること
マージン区分の判定に使う multiplier。これは利用可能な唯一の PDT シグナルでもあります

Trading API の口座オブジェクトには、pattern_day_trader フィールドも daytrade_count フィールドもありません。エージェントはこれらを読み取ってはいけません。multiplier が 4 の場合は PDT 口座を示します。デイトレード回数が必要な場合は、口座オブジェクトではなく GET /v2/account/activities から算出してください。

ステップ 12 — オプション取引の準備状況を確認します（オプションを取引する場合）。

options_approved_level ではなく、options_trading_level を基準にします。有効なレベルは options_approved_level と、口座設定の max_options_trading_level の低い方で、Alpaca はこれを options_trading_level として直接公開しています。レベル 3 の承認を受けた口座でも、設定がレベル 1 なら取引できるのはレベル 1 のみです。
各レベルには、それより下のレベルの取引内容も含まれます。
- レベル 0：オプション取引は無効
- レベル 1：カバードコールの売り、現金担保付きプットの売り
- レベル 2：コールの買い、プットの買い
- レベル 3：スプレッドとストラドル
Alpaca では、どのレベルでも裸のショートオプションは提供されません。戦略にそれが必要な場合は、より高いレベルを探すのではなく、停止してその旨を伝えます。
options_trading_level が 0 の場合、または戦略に必要なレベルに達していない場合、エージェントは停止し、必要なレベルとアップグレードの申請方法を説明します。

ステップ 13 — 暗号資産取引の準備状況を確認します（暗号資産を取引する場合）。

crypto_status が ACTIVE であること
暗号資産取引が有効になっていない場合、エージェントは停止し、口座で有効にする方法を説明します

ステップ 14 — 口座の概要を表示します。 エージェントは口座の状態の概要を表示します。

┌─────────────────────────────────────────┐
│         PAPER ACCOUNT SUMMARY           │
├──────────────┬──────────────────────────┤
│ Account ID   │ ****-****-****-a1b2     │
│ Status       │ ACTIVE                   │
│ Equity       │ $100,000.00             │
│ Buying Power │ $100,000.00             │
│ Cash         │ $100,000.00             │
│ Positions    │ 3 open                   │
│ Multiplier   │ 2 (Reg T margin)         │
│ Options Lvl  │ 2 (effective)            │
│ Crypto       │ ACTIVE                   │
└──────────────┴──────────────────────────┘

フェーズ 4：注文のプレビュー

ステップ 15 — 注文のペイロードを作成します。 エージェントは、確認済みのすべてのパラメーターを含む完全な API リクエスト本文を作成します。冪等性を確保するため、一意の client_order_id を設定します。

ステップ 16 — 注文のプレビューを表示します。 エージェントは注文の全項目を含むプレビュー表を表示します。

┌─────────────────────────────────────────┐
│           ORDER PREVIEW                  │
├──────────────┬──────────────────────────┤
│ Environment  │ PAPER                    │
│ Symbol       │ AAPL                     │
│ Side         │ buy                      │
│ Quantity     │ 10 shares                │
│ Order Type   │ limit                    │
│ Limit Price  │ $185.50                  │
│ Time-in-Force│ day                      │
│ Extended Hrs │ no                       │
│ Client Order │ abc-123-def              │
│ Est. Notional│ ~$1,855.00              │
│ Buying Power │ $98,500.00 (sufficient) │
└──────────────┴──────────────────────────┘

オプションの場合、プレビューには次の情報も表示されます。

契約：AAPL 07/18/2025 $200 Call
契約数：2
倍率：1 契約あたり 100 株
推定プレミアム：約 $3.50 × 2 × 100 = $700.00
ポジションの意図：新規買い

暗号資産の場合、プレビューには次の情報も表示されます。

通貨ペア：BTC/USD
市場：24 時間 365 日（常時営業）
取引金額：$500.00（ノーショナル注文の場合）

ステップ 17 — 確認オンモード。 confirmation_mode が on の場合、エージェントは次のように尋ねます。

この注文を送信しますか？（yes / no）

続行する前に、明示的な yes が入力されるまで待機します。明確な肯定以外の応答はすべて「no」として扱い、変更したい内容を尋ねます。

ステップ 18 — 確認オフモード。 confirmation_mode が off の場合、エージェントは次のように伝えます。

確認モードはオフです。この注文はただちに送信されます。確認用のプレビューを上に表示しています。

その後、エージェントは注文の送信に進みます。

フェーズ 5：注文の送信

ステップ 19 — 注文を送信します。 エージェントは、選択した実行方法（SDK、REST、CLI、または MCP ツール）を介してペーパートレーディング API に注文を送信します。エンドポイントは、ペーパー環境のベース URL に対する POST /v2/orders です。

ステップ 20 — レスポンスを取得します。 成功した場合、エージェントは次の情報を取得します。

id（注文 ID）
client_order_id
status — 通常は new で、Alpaca が注文を受け付け、ルーティングしたことを意味します。accepted は受け付けられたものの、まだルーティングされていないことを意味し、取引時間外によく見られます。pending_new と accepted_for_bidding はまれな状態として記載されています
created_at
submitted_at
symbol、side、qty、type、time_in_force
API レスポンスに含まれる、その他すべてのエコーバックされたフィールド

ステップ 21 — 送信の失敗に対処します。 送信に失敗した場合、エージェントは次の処理を行います。

エラーの完全なレスポンス（HTTP ステータスコード、エラーメッセージ、エラーコード）を取得します
エラーを平易な言葉で表示します
具体的な対処方法を提案します。POST /v2/orders で定義されているエラーレスポンスはちょうど 2 種類で、一般的な HTTP 名称が示す意味とは異なります。
- 403 Forbidden → 認証の問題ではなく、購買余力または株式数の不足です。現在の購買余力と必要な額、または現在のポジションと売却数量を表示します
- 422 Unprocessable Entity → 入力パラメーターが認識されません。該当するパラメーターを表示し、セクション 2 の資産クラスごとのマトリックスに照らして確認します
- 429 Too Many Requests → レート制限に達しています。Retry-After に従って待機し、リクエスト間隔を空けます
- 401 Unauthorized → 認証情報の問題です。処理を停止し、同じ認証情報で再試行しないでください
- ネットワークタイムアウト → ほかの処理を行う前に、注文が受信されたかどうかを確認します
取引できない銘柄や不明な銘柄は、注文エンドポイントで 404 ではなく 422 として返されます。エージェントは事前に GET /v2/assets/{symbol_or_asset_id} で銘柄を検証します。この場合、本当に不明な銘柄であれば 404 が返されます。暗号資産ではスラッシュを含まない旧シンボル体系（BTCUSD）が必要です。スラッシュが残る場合は URL エンコード（/v2/assets/BTC%2FUSDT）しないと、リクエストが不正な形式になります。
失敗した試行をセッションログに保存します
冪等でない送信を自動的に再試行しません。注文が受信されたかどうかが不明な場合（例：ネットワークタイムアウト）、まず client_order_id で既存の注文を確認します

フェーズ 6：送信後のモニタリング

ステップ 22 — 注文状況を取得します。 送信が成功した直後に、エージェントは ID で注文を取得し（GET /v2/orders/{id}）、現在の状況を確認します。

ステップ 23 — 送信後の概要を返します。 エージェントは次の情報を表示します。

Order submitted successfully.

Order ID:        b1e2f3a4-5678-9012-cdef-abcdef123456
Status:          accepted
Symbol:          AAPL
Side:            buy
Qty:             10
Type:            limit
Limit Price:     $185.50
TIF:             day
Submitted at:    2026-07-26T15:30:00Z
Environment:     PAPER

Next steps:
- Ask me to check the status of this order
- Ask me to cancel this order
- Ask me to show your current positions
- Ask me to show your portfolio summary

ステップ 24 — 注文のライフサイクル更新。

エージェントは注文のライフサイクルを追跡し、状態が変化するたびに報告します。

約定：

✅ Order FILLED

Order ID:        b1e2f3a4-...
Symbol:          AAPL
Side:            buy
Filled Qty:      10 shares
Avg Fill Price:  $185.32
Fill Time:       2026-07-26T15:30:05Z

Portfolio impact:
- AAPL position:   10 shares @ $185.32 (new position)
- Position value:   $1,853.20
- Portfolio %:      1.85% of equity
- Buying Power:     $98,146.80 (was $100,000.00)

一部約定：

⏳ Order PARTIALLY FILLED

Order ID:        b1e2f3a4-...
Filled:          6 of 10 shares
Avg Fill Price:  $185.35
Remaining:       4 shares (still working)

拒否：

❌ Order REJECTED

Order ID:        b1e2f3a4-...
Reason:          insufficient buying power
Details:         Required ~$1,855.00, available $500.00

Remediation:
- Reduce order quantity
- Close existing positions to free buying power
- If this is unexpected, check your account for pending orders
  consuming buying power

キャンセル：

🚫 Order CANCELED

Order ID:        b1e2f3a4-...
Canceled by:     system
Reason:          day order expired at market close (16:00 ET)

If you still want this position, consider:
- Resubmitting as a GTC order
- Waiting for the next market open

置換：

🔄 Order REPLACED

Old Order ID:    b1e2f3a4-...
New Order ID:    c2d3e4f5-...
Changed:
  Limit Price:   $185.50 → $186.00
  Quantity:      10 → 15

フェーズ 7：ポートフォリオへの影響の評価

ステップ 25 — 更新されたポジションと口座を取得します。 約定後、エージェントは現在のポジション（GET /v2/positions）と口座（GET /v2/account）を取得し、影響を表示します。

ステップ 26 — ポートフォリオのリスク概要を表示します。

┌─────────────────────────────────────────┐
│        PORTFOLIO RISK SUMMARY           │
├──────────────┬──────────────────────────┤
│ Total Equity │ $100,050.00             │
│ Buying Power │ $98,146.80              │
│ Open Pos.    │ 4 positions              │
│ Open Orders  │ 1 working                │
│                                         │
│ Position Concentration:                 │
│   AAPL       │  1.85% ($1,853.20)      │
│   MSFT       │  3.20% ($3,201.00)      │
│   TSLA       │  2.10% ($2,100.50)      │
│   BTC/USD    │  5.00% ($5,002.30)      │
│                                         │
│ Unrealized P&L (total): +$50.00        │
└──────────────┴──────────────────────────┘

ポジション集中度：abs(position.market_value) / equity × 100 — Position フィールドは market_value です。（position_market_value は、全ポジションの合計値として口座ペイロードにのみ存在します。）
未実現損益：(current_price - avg_entry_price) × qty
デイトレード回数：株式口座の資産が 25,000 ドル未満の場合に該当します
未決済注文：引き続き有効で、追加の購買余力を消費する可能性がある注文

フェーズ 8：デプロイに関するガイダンス

このフェーズは任意です。デプロイや戦略の自動化について質問された場合に限り、エージェントがこのガイダンスを提供します。

ステップ 27 — デプロイの選択肢を提示します。

戦略のデプロイや自動化の方法について質問すると、エージェントは次の方法を提示します。

ローカルスケジューラー：

cron（Linux/macOS）、launchd（macOS）、または Windows タスクスケジューラを使用します
戦略ロジックをまとめた alpaca-py 使用の Python スクリプトを作成します
希望する頻度で実行されるようスケジュールします
確認できるよう、出力をファイルに記録します

クラウドホスティング：

サーバーレスのスケジュール実行には AWS Lambda + EventBridge
Google Cloud Functions + Cloud Scheduler
継続的なプロセスのホスティングには Railway、Render、または Fly.io
スケジュールに従って Python/Node.js プロセスを実行できる任意のプラットフォーム

Webhook ベース：

TradingView アラート → webhook エンドポイント → サーバー → Alpaca API
カスタムアラートシステム → webhook → 注文実行ロジック

デプロイしたすべての方法で、起動時にペーパー環境であることを検証します。 スケジュール設定、ホスティング、Webhook によるトリガーはそれぞれ異なりますが、共通の要件があります。無人で実行される成果物は、注文を発行する前にペーパー環境を参照していることを確認し、確認できない場合は終了します。誤ったエンドポイントを見つけるオペレーターはおらず、ライブアカウントはペーパーアカウントと同じ形式の応答を返すため、後続の処理から誤りを検出することはできません。

この検証を確実にするには、次の 2 つのルールを守ります。

ペーパーエンドポイントは設定ではなく、コード内にリテラルとして固定します。 環境変数、設定ファイル、CI シークレットから読み込むエンドポイントは、このスキルを読んでいない人によって変更される可能性があります。alpaca-py では、クライアントを TradingClient(key, secret, paper=True) として構築し、paper=True をリテラルで記述するということです。paper=os.getenv(...) は決して使用しません。
ライブ環境を意図していることを示す兆候があれば、処理を中止します。 ライブエンドポイント、ライブ取引フラグ、またはライブプロファイルが環境に存在する場合は、競合を黙って解決するのではなく、最初の注文を出す前にゼロ以外の終了コードで終了します。

認証情報や変数に「paper」と名付けても、証拠にはなりません。確認すべきなのは、解決されたエンドポイントだけです。

エージェントが必ず含める重要な注意事項：

ライブ環境を検討する前に、新たな自動化を一定期間、ペーパー環境で検証してください
エージェントは特定のホスティングプロバイダーを推奨せず、稼働時間も保証しません
ライブ取引の自動化は、追加の規制上およびリスク上の考慮事項を伴う、別個の重大な判断です
自動化システムを定期的に監視してください。「設定したら放置」はしないでください
自動化システムには、エラー処理、ログ記録、アラートを含めてください
自動化が予期しない市場状況に遭遇した場合にどうなるかを検討してください

5 - 実行ルール

環境の安全性

このスキルはペーパー取引環境のみで動作します。
エージェントがライブ API 認証情報を検出した場合（ベース URL が paper- プレフィックスのない https://api.alpaca.markets である場合、または SDK/CLI プロファイルがライブに設定されている場合）、エージェントは直ちに停止し、警告しなければなりません。
エージェントは、セッション開始時に一度確認するだけでなく、注文を送信するたびに環境を検証しなければなりません。セッション中に認証情報が再設定されると、環境の状態が変わる可能性があります。
エージェントは「ライブに切り替える」ことを提案したり、ペーパー取引からライブ取引への移行を支援したりすることはありません。

確認時の動作

各セッションの開始時に、注文ごとに明示的な確認を求めるかどうかをエージェントが質問します（デフォルト：ON）。
確認ONモードでは、エージェントが注文プレビューを表示し、送信する前に明示的な「はい」を待ちます。
確認OFFモードでも、エージェントは注文プレビューを表示しますが、短時間表示した後に送信します。送信することを明確に通知します。
セッション中はいつでも、エージェントに伝えることで確認モードを切り替えられます。
モードにかかわらず、エージェントは必ず注文プレビューを表示します。黙って注文を送信することはありません。

冪等性

エージェントは、注文の重複送信を防ぐため、すべての注文に一意の client_order_id を設定します。
ネットワークエラーで送信に失敗し、注文が受け付けられたかどうか不明な場合、エージェントは再試行する前に、既存の注文から client_order_id を確認します。
監査用に、client_order_id の値はセッションの orders.json に記録されます。

レート制限

固定の上限値ではなく、レスポンスヘッダーに基づいてスロットリングを制御します。すべてのレスポンスには X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset が含まれます。Remaining がゼロに近づいたら、スロットリングされる前にエージェントが処理速度を落とします。Trading API については毎分 200 リクエストという数値が広く引用されていますが、Alpaca の現在のドキュメントには記載されていないため、固定値として設定しないでください。
レート制限に達した場合（HTTP 429）は、停止して、ジッターを加えた指数バックオフ（1s、2s、4s、8s、上限あり）で再試行します。また、X-RateLimit-Reset で指定された時刻より前に再試行しないでください。
注文ステータスの確認を頻繁に繰り返さないでください。妥当な間隔でポーリングします。
- 有効な成行注文：最初の 10 秒間は 2 秒ごと、その後は 5 秒ごと
- 有効な指値注文：最初の 1 分間は 5 秒ごと、その後は 30 秒ごと
- 1 つの注文に対するポーリング回数は、合計 60 回を超えないようにしてください

資産クラスのルール

米国株式：

通常の取引時間：米国東部時間 9:30 AM～4:00 PM
時間外取引には、day または gtc の TIF を指定した limit 注文で extended_hours: true が必要です。時間外取引は次の 3 つのセッションで行われます。
- 夜間：日曜日から金曜日、8:00 PM～4:00 AM（米国東部時間）
- プレマーケット：月曜日から金曜日、4:00 AM～9:30 AM（米国東部時間）
- アフターアワーズ：月曜日から金曜日、4:00 PM～8:00 PM（米国東部時間）
すべての資産が夜間セッションの対象になるわけではありません。前提とせず、資産レコードで確認してください。
対象銘柄では端株に対応しています（fractionable 属性を確認してください）。
T+1 決済です。売却代金は翌営業日に利用できます。
空売りには、証拠金口座と借り入れ可能な株式が必要です。

米国オプション：

通常の取引時間：米国東部時間 9:30 AM～4:00 PM
1 枚の契約は、原資産の 100 株に相当します。
承認レベル（1、2、または 3）が必要です。送信前に確認してください。
ITM オプションは、満期時に自動的に権利行使または割り当てが行われます。
オプションには満期日があり、時間の経過とともに価値が下がります（セータ減衰）。
アメリカンスタイルのオプションは、満期前であればいつでも権利行使できます。
主要銘柄では、週次、月次、四半期の満期が利用できます。

暗号資産：

24 時間 365 日取引可能で、取引時間の制約はありません。
通貨ペアごとに最小注文数量が適用されます（アセットエンドポイントを確認してください）。
すべての通貨ペアが利用できるわけではありません。送信前に確認してください。
時間外取引という概念はなく、常時取引可能です。
ほとんどの通貨ペアでは端数量に対応しています。
暗号資産の空売りには対応していません。

エラー処理

認証失敗（401）： 処理を停止し、エラーを表示して、再認証を促します。同じ認証情報で再試行しないでください。
購買余力または株式数の不足（403）： POST /v2/orders での 403 は、取引可能残高または株式数の不足を意味し、認証失敗ではありません。現在の購買余力、必要な想定元本、不足額を表示します。数量を減らすか、ポジションを決済するよう促します。
取引不可の銘柄（422）： 注文エンドポイントでは、認識できない入力は 422 として報告されます。資産ステータスを表示し、銘柄を確認するよう促します。正しい銘柄を検索する方法も提示します。404 が正当に発生するのは GET /v2/assets/{symbol_or_asset_id} です。
市場休場（422）： クロックエンドポイント（GET /v2/clock）を使用して、現在の市場ステータスと次の取引開始時刻を表示します。
レート制限（429）： 待機して、指数バックオフで再試行します。遅延時間を通知します。
ネットワークタイムアウト： 再試行するかどうかを判断する前に、client_order_id を使って注文が受け付けられたかどうかを確認します。
不明なエラー： エラーレスポンス全体を表示します。エラーを黙って無視しないでください。エラーをセッションファイルに記録します。

6 - 出力の契約

注文送信後のチャット内応答

Order submitted successfully.

Order ID:        {order_id}
Status:          {status}
Symbol:          {symbol}
Side:            {side}
Qty:             {qty}
Type:            {order_type}
TIF:             {time_in_force}
Submitted at:    {submitted_at}
Environment:     PAPER

Next steps:
- Ask me to check the status of this order
- Ask me to cancel this order
- Ask me to show your current positions
- Ask me to show your portfolio summary

実行フォルダーの成果物

複数の注文を含むセッションの一部としてスキルが使用されると、エージェントはセッションの成果物を実行フォルダーに書き込みます。

runs/<YYYYMMDD-HHMMSS>-paper-trading/
  notes.md              # strategy context, confirmation choices, assumptions
  orders.json           # all orders submitted in this session
  order_log.csv         # timeline: order_id, timestamp, event, status, details
  positions_snapshot.json # positions after last fill
  portfolio_summary.md  # human-readable portfolio state
  review.md             # session review and open questions

ファイルの説明：

ファイル	内容	形式
`notes.md`	戦略の説明、シグナルの情報源、確認に関する設定、設定した前提、適用したリスク管理策	Markdown
`orders.json`	送信したすべての注文の配列。リクエストのペイロードとレスポンスを含みます	JSON
`order_log.csv`	時系列のイベントログ：`order_id, timestamp, event_type, status, details`	CSV
`positions_snapshot.json`	セッション終了時点のポジション（`GET /v2/positions` から取得）	JSON
`portfolio_summary.md`	人が読める形式のポートフォリオ状態：エクイティ、購買余力、ポジション、集中度、損益	Markdown
`review.md`	セッションのレビュー：うまくいったこと、うまくいかなかったこと、未解決の疑問、改善案	Markdown

7 - 検証とテスト

以下に対する動作を検証してください。

各資産クラスの正常系シナリオ
入力の欠落や曖昧さへの対応
認証および権限エラーへの対応
環境の安全性検証（ライブ認証情報の検出）
注文のライフサイクル遷移
エッジケース：購買余力不足、取引不可の銘柄、市場休場、PDT 警告
冪等性とネットワーク障害からの復旧
確認モードの切り替え

このスキルを変更する場合は、これらのテストを想定上、またはペーパーアカウントで実行してください。

8 - 開示、安全性、データの取り扱い

必須の開示

重要な開示： この資料は、情報提供、教育、調査のみを目的としています。投資助言、推奨、有価証券、オプション、暗号資産、その他の金融商品の売買の申し出や勧誘ではありません。あらゆる投資および取引には、元本を失う可能性を含むリスクが伴います。ペーパートレードはシミュレーションであり、約定、マーケットインパクト、流動性、手数料、レイテンシーなどの点でライブ取引と異なる場合があります。Alpaca の開示情報を https://alpaca.markets/disclosures で確認してください。

エージェントは、すべてのセッション概要、レポート、ポートフォリオレビューにこの開示を含めます。

ペーパートレードに関する注意事項

ペーパートレードの結果はシミュレーションであり、実際の取引実績を示すものではありません。
ペーパー取引の約定は、価格、タイミング、一部約定、拒否の挙動の点でライブ取引の約定と異なる場合があります。
ペーパートレードでは、実際の手数料や料金は発生しません。ライブ取引では費用が発生する場合があります。
ペーパー取引からライブ取引への移行は、リスク許容度、資本の十分性、規制要件について追加の確認が必要となる、独立した重大な判断です。
このスキルがその移行を直接支援することはありません。

オプションに関する注意事項

オプションが関係する場合、エージェントは以下を含めます。

オプションには重大なリスクが伴い、すべての投資家に適しているわけではありません。
オプションは価値のないまま満期を迎えることがあります。ロングオプションでは、支払ったプレミアムの全額を失う可能性があります。
オプションの売却には、受け取ったプレミアムを超える損失が生じるリスクがあり、権利行使の割り当てによって不利な価格でポジションを持つことになる可能性があります。
複雑なオプション戦略（スプレッド、ストラドル、ストラングル）にはさらなるリスクがあり、異なる結果となる複数のレッグを伴う場合があります。
オプションには、特に満期日が近づくと、権利行使および割り当てのリスクが伴います。
取引前に、グリークス（デルタ、ガンマ、セータ、ベガ）と、それらがポジションに及ぼす影響を理解してください。

暗号資産に関する注意事項

暗号資産が関係する場合、エージェントは以下を含めます。

暗号資産の取引には、価格変動が大きいため重大なリスクが伴います。
暗号資産は有価証券ではなく、従来の有価証券とは異なる規制上の保護が適用される場合があります。
暗号資産市場は 24 時間 365 日稼働しており、いつでも大幅な価格変動が発生する可能性があります。
暗号資産は FDIC の預金保険の対象ではなく、SIPC による保護も受けません。
暗号資産を取り巻く規制環境は変化しており、今後変更される可能性があります。

認証情報とデータの取り扱い

エージェントは、環境変数（APCA_API_KEY_ID、APCA_API_SECRET_KEY）、SDK 設定ファイル、または CLI プロファイル設定から認証情報を読み取ります。
API キーやシークレットをチャットに貼り付けてはいけません。提示されても、エージェントは受け取りを拒否します。
エージェントは、セッション外で共有するあらゆる要約から、アカウント ID、注文 ID、個人を特定できる情報を削除します。
API レスポンスの生データはローカル（実行フォルダー内）にのみ保存され、アカウントレベルの機密情報として分類されます。
エージェントが取引データ、アカウントデータ、認証情報を第三者に送信することはありません。
セッションの生成物（実行フォルダー内のファイル）は、ローカルファイルシステムに残ります。適宜確認し、削除してください。

9 - アンチパターン

決して本番の取引環境に注文を送信してはいけません。このスキルはペーパー取引専用です。
決してチャットで API キーやシークレットを求めてはいけません。認証情報は環境変数または設定ファイルから取得します。
決して認証情報、トークン、口座番号、プロファイルの詳細をプレーンテキストで出力してはいけません。
決して注文のプレビューを省略してはいけません。確認モードにかかわらず、必ず表示してください。
決して元の注文が受信されたかを先に確認せず、失敗した注文の送信を再試行してはいけません（冪等性のためにclient_order_idを使用してください）。
決して投資アドバイスをしたり、特定の証券を推奨したり、戦略が適切、収益性がある、または低リスクであると示唆したりしてはいけません。
決してアカウントのエンドポイントを確認せずに、ペーパー取引口座で特定の機能（オプション、暗号資産、証拠金取引）が有効になっていると仮定してはいけません。
決して注文パラメーター、デフォルト値、または執行に関する前提をあなたに隠してはいけません。
決してペーパー取引の結果を、本番取引の成績の証明や予測として扱ってはいけません。
決してユーザーに知らせずにループ内で注文を自動送信してはいけません。一括注文を行う場合は、それぞれをプレビューするか、全注文の概要表を表示して一括確認を得てください。
決して市場の取引時間を仮定してはいけません。時間に制約のある注文を送信する前に、必ず時刻／カレンダーのエンドポイントを確認してください。
決して同じセッションでペーパー取引と本番取引の認証情報を混在させてはいけません。
決して取引することを確認していない資産クラスの注文を行ってはいけません。

10 - 関連ファイル

ファイル	説明
`reference.md`	API エンドポイントの詳細、注文スキーマ、ステータスのライフサイクル図、エラーコード

基本情報

作者: alpacahq
リポジトリ: alpacahq/alpaca-skills
カテゴリ: その他
インストール数: 140
GitHub スター: 157

問題を報告

スキル	説明
`alpaca-trading-paper-trading-cli`	Alpaca CLI を使用する CLI 固有のバージョン
`alpaca-trading-paper-trading-mcp`	Alpaca MCP サーバーのツールを使用する MCP 固有のバージョン