alpaca-broker-journals

Alpaca Broker API — ジャーナル

ジャーナルは、Alpaca オムニバス内の自社アカウント間で資金を移動します。通常は、事前に資金を入金した会社／スイープアカウントとユーザーアカウントの間で行われます。「即時入金」、キャッシュバック、株式報酬を支える仕組みです。外部の銀行システムには一切関与しません（その用途には alpaca-broker-funding-transfers を使用します）。

ベース URL と認証（クライアントクレデンシャルの Bearer トークン。従来の Basic 認証も引き続き利用できます）については、まず alpaca-broker-integration をお読みください。

リファレンス

• ガイド：https://docs.alpaca.markets/docs/funding-via-journals
• API リファレンス：https://docs.alpaca.markets/reference/createjournal
• ライブスキーマ：alpaca-docs MCP → get-endpoint、タイトル "Broker API"、パス /v1/journals

1. エンドポイント

メソッド	パス	用途
POST	/v1/journals	単一のジャーナル（現金の JNLC または株式の JNLS）
POST	/v1/journals/batch	1 つの送金元 → 複数の送金先（JNLC のみ）
POST	/v1/journals/reverse_batch	複数の送金元 → 1 つの送金先（JNLC のみ）
GET	/v1/journals	一覧（フィルター：after、before、status、entry_type、to_account、from_account、limit）
GET	/v1/journals/{journal_id}	1 件を取得
DELETE	/v1/journals/{journal_id}	保留中のジャーナルをキャンセル（204）
GET	/v2/events/journals/status	SSE ジャーナルステータスストリーム（v1 はレガシー）

2. JNLC と JNLS

entry_type は "JNLC" または "JNLS" のいずれかです。

• JNLC — 現金。 アカウント間で USD を移動します。会社 ↔ ユーザー、両方向で利用できます。顧客間の移動には利用できません。
• JNLS — 有価証券。 整数株または端株を移動します。会社 → ユーザーのみで利用できます。登録特典や紹介特典の株式報酬に使用します。

// JNLC (cash)
{ "entry_type": "JNLC", "from_account": "<firm-uuid>", "to_account": "<user-uuid>", "amount": "100.00" }

// JNLS (shares)
{ "entry_type": "JNLS", "from_account": "<firm-uuid>", "to_account": "<user-uuid>", "symbol": "AAPL", "qty": "0.5" }

フィールド	JNLC	JNLS	備考
from_account / to_account	必須	必須	アカウント UUID
amount	必須	—	10 進数の文字列
symbol / qty	—	必須	qty は文字列。端株も指定可能
currency	任意	任意	ドキュメントに既定値の記載なし
description	任意	任意	≤1024 文字。サンドボックスのフィクスチャを受け付けます
transmitter_*	任意（JNLC）	該当なし	トラベルルールのフィールド

レスポンス： 200 ジャーナル · 403 金額／資産を利用できません · 404 アカウントが見つかりません · 422 異なる本文で冪等性キーが再利用されました。

3. Idempotency-Key ヘッダー — 必ず使用してください

ジャーナルの作成時には、Idempotency-Key ヘッダー（≤128 文字。クライアントで生成した UUID を推奨）を渡してください。

• 同じキー + 同一の本文 → 元のジャーナルを返します（重複しません）。
• 同じキー + 異なる本文 → 422。

教訓： 資金移動を安全に再試行するには、この方法が正解です。これを指定せずに POST /v1/journals がネットワークタイムアウトすると、現金が移動したかどうか分からなくなり、確認せず再試行すると二重に入金される可能性があります。自社の取引 ID からキーを決定的に生成し、毎回の試行で送信してください。

4. Batch と reverse-batch（JNLC のみ、全件成功または全件失敗）

Batch — 1 対複数（スイープアカウントから複数のユーザーへ分配）：

{ "entry_type": "JNLC", "from_account": "<firm-uuid>",
  "entries": [ { "to_account": "<u1>", "amount": "1000" }, { "to_account": "<u2>", "amount": "250" } ] }

Reverse batch — 複数対 1（複数のユーザーから会社アカウントへ現金を戻す）：

{ "entry_type": "JNLC", "to_account": "<firm-uuid>",
  "entries": [ { "from_account": "<u1>", "amount": "10" }, { "from_account": "<u2>", "amount": "100" } ] }

すべてのエントリーが検証に通る必要があり、1 件でも通らない場合はバッチ全体が失敗します（無効なアカウント ID が 1 つでもあると失敗します）。その後の挙動は異なります。/batch は Idempotency-Key を受け付け、BatchJournalResponse（Journal オブジェクトと、失敗した各エントリーの error_message）を返します。一方、/reverse_batch にはどちらも記載されていません。エントリーごとのエラー情報を含まない JNLC の配列をそのまま返すため、reverse-batch の再送はローカルで制御してください。

5. ステータスのライフサイクル

JournalStatus：queued、sent_to_clearing、pending、executed、activity_created、rejected、canceled、refused、deleted、correct。

正常系の流れは、Alpaca が設定した JNLC のバージョンによって異なります。 JNLS および JNLC v1：queued → sent_to_clearing → executed。JNLC v2（単一の現金ジャーナルのみ。バッチは引き続き v1 で処理）：作成レスポンスはすでに executed になって返ることが多く、その後 activity_created が続きます。手動承認の経路でのみ sent_to_clearing が表示されます。いずれの場合も、10 種類すべてのステータスを受け入れてください。購買余力が移動したことを示すのは executed です。

ステータス	意味	終端
queued	キュー内	いいえ
sent_to_clearing	帳簿および記録システムに送信済み	いいえ
pending	Alpaca のオペレーション担当者による承認が必要です（通常は JNLC の上限によるものです。§7 を参照）	いいえ
executed	残高が更新されました。ただし、最終状態ではありません。キャッシャリングによって取り消される可能性があります	いいえ（最終状態ではありません）
activity_created	非取引アクティビティが作成されました（JNLC v2 のみ）。情報提供のみで、取り消し可能です	いいえ（最終状態ではありません）
rejected	手動で拒否されました	いいえ
refused	事前チェックに失敗しました。台帳には登録されていません（例：高速再生時に残高チェックに失敗した場合）	いいえ
canceled	API またはオペレーションによってキャンセルされました	最終状態
deleted	台帳から削除されました	最終状態
correct	以前に実行されたジャーナルがキャンセルされ、修正後の金額で再作成されました	最終状態

重要な教訓が 2 つあります：

1. executed ≠ 最終状態です。 executed を取り消し不能と見なさないでください。Alpaca のキャッシャリングによって、許可されていないジャーナルが取り消される場合があります。後続イベントと照合してください。
2. correct は新しいジャーナル ID を作成します。 修正では元のジャーナルをキャンセルし、修正後の金額で新しいジャーナルを発行します。その場で編集するわけではありません。ジャーナル ID で照合する場合、元の ID は correct／キャンセル済みに遷移し、別の ID が実際の資金を表します。両方を処理してください。（このため、イベントコンシューマーは冪等で、ID をキーにする必要があります。alpaca-broker-reconciliation-idempotency を参照してください。）

6. SSE ジャーナルイベント

GET /v2/events/journals/status は JournalStatusEventV2 をプッシュします。フィールドは event_id（ULID、ソート可能）、journal_id、entry_type、status_from、status_to、description、idempotency_key、idempotency_key_type（single|batch）、batch_error_message です。再生ルール：until を指定する場合は since が必要です。until_id を指定する場合は since_id が必要です。since と since_id は併用できません。since／since_id を指定しない場合、履歴は返されません。alpaca-broker-sse-events を参照してください。

7. 制約と注意事項

• 利用資格： 現金プーリング／ジャーナルのユースケースでは、Alpaca による審査、および場合によっては現地のライセンスが必要です。法律顧問に確認してください。
• JNLS の口座状態： to_account は ACTIVE、from_account は ACTIVE または CLOSE である必要があります。
• 十分な資金： JNLC の作成は、金額を利用できない場合に 403 を返します。逆方向のバッチ処理での 403 は、残高／資産が不足していることを示します。
• JNLC の上限を超えると pending になります（オペレーション担当者による手動承認）：1 件あたりの上限（デフォルトは $50）と、1 日あたりの合計上限（デフォルトは $1,000）があります。どちらも設定可能です。上限を超えたジャーナルは、翌日の BOD ジョブで実行されます。
• 取引口座の cash_transferable を事前に確認してください。これは「振替可能な現金（JNLC）」を示します。一方、cash には未決済の売却代金も含まれます。
• GET /v1/journals は、結果セットが 100,000 件を超えると 422 を返します。必ず after／before／limit でフィルターしてください。
• 削除できるのは保留中のものだけです： pending の場合に限り DELETE が成功し（204）、実行済みのジャーナルでは 422 が返されます。実行済みのジャーナルを取り消すには、削除しようとせず、反対方向のミラージャーナルを作成してください。
• トラベルルール： 資金移動を伴うジャーナルには送金者情報を含めてください（入金は金額にかかわらずすべて必須です）。
• サンドボックスのフィクスチャ： description にフィクスチャを設定すると（例：/fixtures/status=rejected/fixtures/）、テスト用に rejected／pending の結果をシミュレートできます。

8. スイープアカウントによる資金供給パターン（ジャーナルが存在する理由）

標準的な Broker API の資金供給アーキテクチャ：

Bulk external wire ──> FIRM / SWEEP account (pre-funded) ──JNLC──> user accounts (instant)
user account ──JNLC──> FIRM account ──external wire/ACH──> outside world (withdrawal)

独自の方法で資金を集め、会社の口座に保管し、ユーザーごとに外部送金を行うのではなく、即座にユーザーへジャーナルで振り替えます。出金時は逆の流れになります。これにより、銀行の決済レールが遅くても、「即時入金」の UX を実現できます。

関連スキル： 外部との入出金 → alpaca-broker-funding-transfers；再試行の安全性と訂正 → alpaca-broker-reconciliation-idempotency；小数の処理 → alpaca-broker-money-precision；イベント → alpaca-broker-sse-events。