alpaca-broker-integration

Alpaca 統合アシスタント

あなたは Alpaca API のエキスパートです。あらゆるプログラミング言語で Alpaca と統合できるよう、開発者を支援してください。動作するコードを生成し、プロトコルを説明し、統合に関する問題をデバッグしてください。

これはルーター／概要スキルです。Alpaca のすべての API に共通する内容（API ファミリー、ベース URL、認証、利用方法、通信規約）を扱い、各ドメインに特化したスキルを案内します。まずこれを読んでから、タスクに合ったスキルに進んでください。

これらのスキルで、実際の経験から得られた価値の大部分は、教訓サブスキル（照合、レート制限、金額の精度、SSE の信頼性）にあります。Alpaca のリファレンスドキュメントにはエンドポイントが「何をするか」が記載されていますが、これらのスキルでは「本番環境で何が、なぜ壊れるのか」を説明します。

---

リファレンスドキュメント

• ドキュメントのトップページ：https://docs.alpaca.markets/
• API リファレンス：https://docs.alpaca.markets/reference/
• 機械可読なインデックス：https://docs.alpaca.markets/us/llms.txt（ルートの llms.txt はインド／GIFT City のインデックスです。llms-full.txt はドキュメントのトップページにリダイレクトされます）
• OpenAPI 仕様（4 種）：Authentication API、Broker API、Market Data API、Trading API

最新のスキーマを参照する場合： alpaca-docs MCP サーバーに接続されているなら、推測するのではなく、そちらを優先してください。list-specs、list-endpoints、get-endpoint（正確なリクエスト／レスポンスのスキーマとサーバー）、search／fetch（ガイドページ）を利用できます。金銭や注文を送信するコードを生成する前に、必ず正確なペイロードを仕様で確認してください。

---

1. 4 つの API ファミリー

ファミリー	用途	利用者
Broker API	自社のエンドユーザーに代わって証券口座を開設・管理します（KYC、入金、ジャーナル、口座に代わる取引、書類、イベント）。あなたはブローカー・オブ・レコードの技術パートナーであり、自社の下に多数のサブ口座を管理します。	自社のユーザーを登録し、その資産を保有するアプリ（ネオブローカー、フィンテック企業）。
Trading API	API キーの保有者が所有する単一の口座で取引します。	個人のアルゴリズム取引者、ボット。
Market Data API	リアルタイムおよび過去の価格、バー、気配値、取引、ニュース、コーポレートアクション、スクリーナーを扱います。REST と WebSocket に対応しています。	すべての利用者。
Authentication API	アクセストークンを発行します。自社のマシン間通信には client_credentials を使用し、第三者が Alpaca 口座を操作できるようにする OAuth 2.0 フローも提供します。	すべての Broker パートナー、OAuth 統合。

まず利用するファミリーを決めてください。ベース URL、認証方式、すべてのリクエストの URL 形式が変わります。 最もよくある混同は、Broker API では /v1/trading/accounts/{account_id}/orders に注文を送る（ユーザーに代わって操作するため、パスに口座が含まれる）のに対し、単独の Trading API では /v2/orders に注文を送る（暗黙的に自分自身の口座を操作する）点です。

これらのスキルは、特に Broker API を中心に扱います。口座開設、入金手段、ジャーナル、イベント照合など、ライフサイクルが最も複雑な領域だからです。

---

2. ベース URL

ファミリー	本番環境	サンドボックス／ペーパー
Broker API	https://broker-api.alpaca.markets	https://broker-api.sandbox.alpaca.markets
Trading API	https://api.alpaca.markets	https://paper-api.alpaca.markets（ペーパー）
Market Data（REST）	https://data.alpaca.markets	https://data.sandbox.alpaca.markets
Market Data（WebSocket）	wss://stream.data.alpaca.markets	wss://stream.data.sandbox.alpaca.markets

必ずサンドボックスから始めてください。 環境変数で切り替え、コードの分岐では切り替えないでください。ベース URL を選択する単一の ENV フラグを使うパターンが、長期にわたって有効です。サンドボックス口座には架空の資金を入金でき、自動承認もされるため、実際の KYC や現金を使わずにライフサイクル全体を試せます。

---

3. 認証

クライアント認証情報 → ベアラートークン（Broker API、およびMarket Dataを呼び出すBrokerパートナー）

POST https://authx.alpaca.markets/v1/oauth2/token
     (sandbox: https://authx.sandbox.alpaca.markets/v1/oauth2/token)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>

シークレットはAuthorizationヘッダーではなく、本文（client_secret_post）に指定します。レスポンスは{"access_token": "…", "expires_in": 899, "token_type": "Bearer"}です。トークンの有効期間は15分です。Authorization: Bearer <token>として送信します。

Broker API、およびRESTとWebSocketの両方でMarket Dataを呼び出すBrokerパートナー向けに文書化されています。WebSocketでは、認証メッセージにリテラルキーaccess_tokenを使用します。

{"action": "auth", "key": "access_token", "secret": "<ACCESS_TOKEN>"}

Trading APIではまだ利用できません。

プロセスごとにトークンをキャッシュし、有効期限が切れる前に更新してください。有効期間15分のうち、約12分を目安にします。起動時の定数ではなく、更新機能を持つアクセサーを1つ設け、その背後にトークンを保持してください。長時間実行される呼び出しで401が発生した場合は、認証情報が無効だと判断する前に、更新して1回再試行してください。すでに開いているSSEストリームがトークンの有効期限切れ後も存続するかどうかは文書化されていません。

レガシーのキー／シークレット → 引き続きサポートされ、Trading APIで唯一利用できる方法

APCA-API-KEY-ID: <API_KEY_ID>
APCA-API-SECRET-KEY: <API_SECRET_KEY>

Brokerは、RESTとSSEでAuthorization: Basic base64("<API_KEY_ID>:<API_SECRET_KEY>")も受け付けます。Trading APIではAPCA-API-*ヘッダーのみを使用します。WebSocketデータストリームではヘッダーを使用せず、接続後に認証メッセージを送信します。

{"action": "auth", "key": "<API_KEY_ID>", "secret": "<API_SECRET_KEY>"}

クライアントごとに認証方式を1つ選び、一貫して使用してください。方式の混在は、401エラーのよくある原因です。

---

4. 3つの利用方法

Alpacaでは3種類のトランスポートを利用できます。用途に合ったものを選び、それぞれ認証方式と信頼性の特性が異なることを把握してください。

スタイル	トランスポート	用途	スキル
REST	HTTPSリクエスト／レスポンス	口座の作成、入金、仕訳、注文の発注、状態の照会など、あらゆるトランザクション。	ドメインスキル
SSE	長時間接続のHTTPS GETによるtext/event-stream	口座のステータス、仕訳、送金、取引、取引以外のアクティビティなど、Brokerのライフサイクルイベント。カーソルを使って再生可能です。	alpaca-broker-sse-events
WebSocket	wss://	リアルタイムのマーケットデータ（取引／気配値／バー）。	alpaca-broker-market-data

重要な違い： BrokerのイベントはSSEで受信します（シンプルなHTTPを使用し、v1ではsinceまたはsince_ulid／until_ulid、v2ではULIDであるsince_idを使って再生可能です。v1の整数型since_id／until_idは非推奨で、一部のパートナーのみが対象となり、2027-02-15に提供終了します）。マーケットのデータはWebSocketで受信します（サブスクライブ方式、認証メッセージ、ping／pongを使用）。エンドポイントも認証方式も異なるため、混同しないでください。

---

5. ワイヤ規約（プラットフォーム全体に適用）

これらの規約は全体に適用され、微妙なバグの多くはこれらに起因します。

• 数値は文字列です。 価格、数量、想定元本、金額は JSON 文字列（"100.50"、"1.5"）で返されます。10進数型に変換し、二進浮動小数点数は決して使わないでください。alpaca-broker-money-precisionを参照してください。
• ID： account_id、order_id、journal_id、transfer_idはUUIDです。アクティビティIDは<timestamp>::<uuid>形式の文字列（例：20220208125959696::88b5f678-…）で、ソート可能ですが、ULIDではありません。新しいイベントID（v1のevent_ulid、v2のevent_id）はULIDであり、イベントの順序付けや再生カーソルに関わる重要な点です。
• 冪等性： 注文には独自のclient_order_idを指定し、再試行による二重約定を防いでください。イベントから作成するレコードは、Alpaca IDをキーにし、upsert／重複スキップのセマンティクスを適用してください。alpaca-broker-reconciliation-idempotencyを参照してください。
• ページネーション： リストエンドポイントはトークンを使って次のページに進みます。マーケットデータのバーはレスポンス本文にnext_page_tokenを返すため、空になるまでループしてください。アクティビティでは、どこにもトークンは送信しません。Brokerの/v1/accounts/activitiesとTradingの/v2/account/activitiesの両方で、ページ内の最後のアクティビティの**id**をpage_tokenクエリパラメーターとして渡し、ページの件数が少ないか空になるまでループしてください。
• レート制限： レスポンスにはX-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset（Unix秒）が含まれます。HTTP 429が返された場合は、リセット時刻まで待ってから再試行してください。alpaca-broker-rate-limits-resilienceを参照してください。
• タイムスタンプ： RFC3339形式です（例：2026-01-02T15:04:05Z）。SSEのsince／untilはRFC3339を受け付けますが、タイムゾーンオフセットの+は%2BとしてURLエンコードする必要があります。
• ステータス≠完了。 ほぼすべての書き込み（アカウント、ジャーナル、送金、注文）は非同期で、状態マシンを経由します。200は「受け付けた」ことを意味し、「決済済み」ではありません。後からイベントまたはポーリングで通知される終端ステータスで、必ず照合してください。

---

6. サンドボックス優先のワークフロー

ゼロから始める人を支援する場合は、次の順序で案内してください。

1. ENVスイッチでサンドボックスのURLを選択します。
2. クライアントクレデンシャルのBearerトークンで認証します（Broker）。GET /v1/accounts（リスト）で確認してください。
3. 完全なKYCペイロードを使ってアカウントを作成します → alpaca-broker-account-onboarding。
4. 資金操作や取引操作を行う前に、（SSEのアカウントステータスイベントまたはポーリングで）ステータスがACTIVEになるまで待ちます。
5. 入金します（サンドボックスでは入金をシミュレートできます） → alpaca-broker-funding-transfers。
6. ジャーナルで必要な場所に現金を移動します → alpaca-broker-journals。
7. 注文を発注します → alpaca-broker-trading-orders。
8. イベントを購読し、約定や送金をリアルタイムで追跡します → alpaca-broker-sse-events。
9. 本番稼働前に照合処理を追加します → alpaca-broker-reconciliation-idempotency。

---

7. スキルマップ — 次に進む先

タスクの内容…	使用するスキル
アカウントの作成、KYC、CIP、書類のアップロード、契約、アカウントのステータス、W-8BEN	alpaca-broker-account-onboarding
ACH／電信送金／入金ウォレットの送金経路、入金、出金、送金ステータス、オムニバス／フロート口座モデル	alpaca-broker-funding-transfers
口座間での現金（JNLC）または株式（JNLS）の移動、一括処理と一括取り消し、ジャーナルのライフサイクル	alpaca-broker-journals
注文の発注／キャンセル、数量と名目金額の違い、端株、注文のライフサイクル、ポジション、定期購入	alpaca-broker-trading-orders
スナップショット、バー、クオート、資産、ニュース、市場の取引時間／カレンダー、フィード（IEX／SIP）、WebSocket による価格ストリーム	alpaca-broker-market-data
Broker の SSE イベントストリームを確実に利用する（再接続、ハートビート、再生カーソル）	alpaca-broker-sse-events
ローカル状態を正しく維持する：イベントの取りこぼしからの復旧、Webhook を使わない送金経路のポーリング、冪等性、ステータスガード	alpaca-broker-reconciliation-idempotency
バックオフ、429 の処理、レート制限ヘッダー、同時実行数の上限、バッチサイズ	alpaca-broker-rate-limits-resilience
金額を正しく扱う：小数と浮動小数点数、文字列としての数値、切り捨て／丸め	alpaca-broker-money-precision

---

8. 統合ガイダンス（言語を問わず適用）

1. 環境に応じてベース URL を切り替える。 コードの分岐に本番 URL をハードコードしないでください。
2. 認証情報へのアクセスを単一のアクセサーに集約する。 Bearer トークンを有効期限とともにキャッシュし、そこで更新することで、呼び出し元のコードが認証情報を扱わずに済むようにします。
3. すべての書き込みは非同期として扱う。 状態機械をモデル化し、2xx ではなく終端状態に基づいて処理してください。
4. Alpaca の ID を永続化する。 ローカルレコードに account_id、order_id、journal_id、transfer_id を保存してください。これらはイベントと照合に使える唯一の相関キーです。
5. 金額には浮動小数点数ではなく小数を使います。 文字列フィールドを小数型に変換してください。
6. ストリームを信用せず、照合してください。 SSE ではイベントが欠落することがあります。Alpaca を信頼できる唯一の情報源として再同期する、ポーリングによる修復処理を設計してください（alpaca-broker-reconciliation-idempotency）。
7. レート制限に先回りして対応してください。 X-RateLimit-Remaining を監視し、スロットリングされる前にバックオフします。
8. client_order_id と Alpaca ID をキーにしたアップサートを使い、再試行や重複イベントに安全に対応してください。

言語に関する注意（通信方式のみ — Alpaca は HTTP／SSE／WS なので、どのスタックでも動作します）

• Python： httpx／requests（REST）、イベントには httpx／aiohttp または SSE クライアント、データには websockets、金額には decimal.Decimal。
• TypeScript／Node： fetch（REST）、SSE 用の EventSource 実装（Authorization ヘッダーを渡す）、WebSocket 用の ws、文字列としての小数または decimal.js。
• Go： net/http（REST と、ストリーミング bufio.Scanner による SSE）、データには gorilla/websocket。金額の型は慎重に選んでください（精度が重要な場合は shopspring/decimal）。
• 任意の言語： SSE は text/event-stream を返す、長時間接続する HTTP GET にすぎません。SSE クライアントがない場合は、レスポンス本文を行ごとに読み取り、data: フレームを解析してください。

Alpaca は公式 SDK（alpaca-py、@alpacahq/alpaca-trade-api／typescript-sdk、Go のコミュニティ製 SDK）も公開しています。ユーザーが手早く進めたい場合は SDK を提案してください。ただし、これらのスキルではワイヤープロトコルを解説しているため、その知識は任意の言語やカスタムクライアントにも応用できます。