alpaca-broker-account-onboarding

Alpaca Broker API — 口座開設とKYC

貴社のもとでエンドユーザーの証券口座を作成、管理できます。これは Broker API 統合の最初のステップです。口座が ACTIVE になるまでは、資金の入金、振替、取引を行えません。

ベース URL と認証（クライアント認証情報を使った Bearer トークン。従来の Basic 認証も引き続き使用可能）については、先に alpaca-broker-integration をお読みください。

リファレンス

• ガイド：https://docs.alpaca.markets/docs/getting-started-with-broker-api、https://docs.alpaca.markets/docs/accounts
• API リファレンス：https://docs.alpaca.markets/reference/createaccount
• 最新のスキーマ：alpaca-docs MCP → get-endpoint、タイトル "Broker API"、パス /v1/accounts

1. エンドポイント

メソッド	パス	用途
POST	/v1/accounts	口座を作成（申請を送信）
GET	/v1/accounts	口座を一覧表示／検索（最大1000件を返します）
GET	/v1/accounts/{account_id}	口座を1件取得（AccountExtended）
PATCH	/v1/accounts/{account_id}	口座を更新
POST	/v1/accounts/{account_id}/actions/close	口座を閉鎖（204を返します）
POST	/v1/accounts/{account_id}/documents/upload	口座所有者／KYC書類をアップロード（配列形式の本文）
GET	/v1/accounts/{account_id}/documents	アップロード済み書類を一覧表示
POST / GET	/v1/accounts/{account_id}/cip	CIPの結果を送信／取得
GET	/v1/country-info	対応国のデータ
GET	/v1/events/accounts/status	口座ステータス変更のSSEストリーム → alpaca-broker-sse-events を参照

2. 口座作成リクエスト（POST /v1/accounts）

次の4つのオブジェクトは必須です：contact、identity、disclosures、agreements。documents と trusted_contact は任意ですが、KYCでは通常必要です。

{
  "contact": {
    "email_address": "[email protected]",
    "phone_number": "+15555555555",
    "street_address": ["20 N San Mateo Dr"],
    "city": "San Mateo",
    "state": "CA",            // required if country / country_of_tax_residence is USA
    "postal_code": "94401",
    "country": "USA"          // ISO 3166-1 alpha-3
  },
  "identity": {
    "given_name": "Jane",
    "family_name": "Doe",
    "date_of_birth": "1990-01-01",
    "tax_id_type": "USA_SSN", // see enum below
    "tax_id": "666-55-4321",
    "country_of_tax_residence": "USA",
    "funding_source": ["employment_income"]
  },
  "disclosures": {
    "is_control_person": false,
    "is_affiliated_exchange_or_finra": false,
    "is_politically_exposed": false,
    "immediate_family_exposed": false
  },
  "agreements": [
    { "agreement": "customer_agreement", "signed_at": "2026-01-02T18:09:33Z", "ip_address": "185.13.21.99" }
  ],
  "documents": [ /* OwnerDocumentUploadRequest[] — see §4 */ ],
  "trusted_contact": { "given_name": "Jim", "family_name": "Doe", "email_address": "[email protected]" }
}

主なフィールドのルール：

• contact.street_address は配列です（最大3行）。国または税務上の居住地が USA の場合、contact.state は必須です。
• identity.funding_source は配列です。employment_income、investments、inheritance、business_income、savings、family のうち1つ以上を指定します。
• tax_id_type の列挙値は多数あり、国によって異なります。USA_SSN、USA_ITIN、IND_PAN、MEX_RFC、GBR_NINO、…に加え、汎用値として NATIONAL_ID、PASSPORT、DRIVER_LICENSE、OTHER_GOV_ID、NOT_SPECIFIED があります。全リストをハードコーディングせず、仕様を照会してください。
• トップレベルで指定できる任意項目：account_type（trading|custodial|donor_advised|ira）、account_sub_type（IRAの場合：traditional|roth）、enabled_assets（us_equity|us_option|crypto|ipo、デフォルトは us_equity）、allow_instant_ach（デフォルトは false — Instant ACH のパートナー側スイッチ）。
• 非推奨： investment_objective／investment_time_horizon／liquidity_needs／risk_tolerance は identity からトップレベルに移動しました。

レスポンス： 200 → 口座オブジェクト · 409 メールアドレスがすでに登録済み · 422 無効な値 · 400 不正な形式の本文

3. 同意書

各項目には agreement（customer_agreement、account_agreement、margin_agreement、crypto_agreement、options_agreement）、signed_at（RFC3339）、ip_address（IPv4）、および任意の revision を指定します。同意書の内容をユーザーに提示し、実際の署名日時とIPアドレスを取得する必要があります。Alpacaはこれらを法的記録として扱います。revision を省略した場合は、現在有効なリビジョンがデフォルトで適用されます。

4. 書類とW-8BEN

documents[] の項目：document_type と（content の base64 または content_data）。

{ "document_type": "identity_verification", "content": "<base64>", "mime_type": "image/jpeg", "document_sub_type": "passport" }

• document_type の列挙値には、identity_verification、address_verification、date_of_birth_verification、tax_id_verification、w8ben、w9、cip_result などがあります。
• mime_type：application/pdf、image/png、image/jpeg。ただし、w8ben に限り application/json も使用できます。
• W-8BEN の簡便な方法（教訓）： PDF を作成する代わりに、構造化された W8benDocument JSON オブジェクト（full_name、country_citizen、permanent_address_*、date_of_birth、ip_address、timestamp、signer_full_name、…）として content_data をアップロードすると、Alpaca が公式フォームを生成します。プログラムで米国以外の個人に必要な税務フォーム要件を満たすには、この方法が最適です。
• W-8BEN には有効期限があります。 署名した暦年に加えて、3 年ごとに新しいフォームを提出する必要があります。更新をスケジュールし、アップロードを一度きりの作業として扱わないでください。
• 書類のサイズ上限：Alpaca の KYC-as-a-service を使用する場合は 1 ファイルあたり 10 MB。独自の KYC を実行する場合、上限はありません。

5. アカウントステータスのライフサイクル

status（および crypto_status）では、AccountStatus の列挙値が使用されます。

ステータス	意味
INACTIVE	対象の資産では有効化されていません
PAPER_ONLY	ペーパートレードのみ可能です
ONBOARDING	作成済みですが、KYC はまだ実施されていません — Onfido を使用する場合のみ使用されます（OpenAPI の列挙値の説明では、まだ提出されていない「申請予定」とされています）
SUBMITTED	提出済みで、処理中です
SUBMISSION_FAILED	提出エラーです。Alpaca が解決するため、対応は不要です
ACTION_REQUIRED	ユーザーによる手動対応と書類のアップロードが必要です（例：true の開示回答がこのステータスに割り当てられます）。kyc_results を参照してください
APPROVAL_PENDING	アカウントが自動 KYC チェックに合格しなかったため、チームが手動で審査します。通常、書類は不要です
APPROVED	承認済みで、有効化待ちです
ACTIVE	完全に利用可能です。入金と取引ができます
REJECTED	申請が却下されました
ACCOUNT_UPDATED	個人情報を審査中です。一時的な状態で、ACTIVE に戻ります。その間、送金は制限されます
ACCOUNT_CLOSED	閉鎖済みです

通常の流れ： SUBMITTED → APPROVED → ACTIVE。自動 KYC チェックに合格しなかった場合は、例外として APPROVAL_PENDING または ACTION_REQUIRED に進みます。どちらも APPROVED に戻るか、REJECTED で終了します。（OpenAPI の列挙値では、今も APPROVAL_PENDING を「初期値」としていますが、ステータスガイドのほうが新しい情報源です。）

教訓 — 後続のすべての操作は ACTIVE を条件にしてください。 POST /v1/accounts が 200 を返しても、取引が可能とは限りません。アカウントステータスの SSE イベントを購読するか、GET /v1/accounts/{id} をポーリングし、status == ACTIVE になってから入金、振替、取引を有効にしてください。アクティブでないアカウントへの振替や取引は失敗します。暗号資産については、status とは別に管理される crypto_status を条件にしてください。ACCOUNT_UPDATED は失敗ではなく、一時的な制限状態として扱います。審査後、アカウントは ACTIVE に戻ります。

6. KYC 結果と CIP

• アカウントオブジェクトの kyc_results には、reject／accept／indeterminate の各セットと additional_information が含まれます。summary は pass／fail です（内部専用）。
• KYCResultType は拡張可能な文字列セットであり、固定された列挙型ではありません。 例：IDENTITY_VERIFICATION、WATCHLIST_HIT、W8BEN_CORRECTION。生成コードでは、認識できない値を固定の列挙型として解析せず、そのまま受け入れて保持する必要があります。ドキュメントに記載されている識別子は、https://docs.alpaca.markets/reference/getaccount の KYCResults にあります。
• KYC を自社で実施する場合（または Onfido／Trulioo／Veriff などを通じて実施する場合）、CIPInfo ボディ（provider_name、kyc、document、photo、identity、watchlist の各サブ結果）を指定して POST /v1/accounts/{id}/cip から結果を送信してください。サブチェックの結果は clear／consider です。
• 個人口座を開設するための最低要件は、氏名、生年月日、住所、識別番号の確認です。
• WATCHLIST_HIT については、Alpaca が別途求めない限り、アカウント所有者による対応は不要です。

7. 統合のガイダンスと学んだ教訓

1. 送信前に、入力を正規の形式に統一してください。 国のフィールドは ISO 3166-1 alpha-3（USA、PHL、…）である必要があります。UI の装飾（国旗／絵文字、表示名）を取り除き、GET /v1/country-info に照らして検証してください。country／country_of_tax_residence に無効な値が含まれていることは、422 エラーのよくある原因です。
2. 実際の同意に関するメタデータを記録してください。 signed_at と ip_address には、サーバー時刻やプレースホルダーではなく、実際のユーザー操作を反映させる必要があります。
3. 作成は非同期として扱ってください。 返された account_id をすぐに保存し、作成レスポンスではなく、ステータスイベントに基づいて UI を更新してください。
4. サンドボックスと本番環境の認証情報／設定は、別々のデプロイ環境で管理してください。 アカウント ID から確認できる情報はありません。ID は通常の UUID であり、2 つの環境はホストも認証情報も別々です。
5. 送信時の冪等性を確保してください。 メールアドレスの重複による 409 は、既存のアカウントを検索するための手がかりになります。作成を再試行するのではなく、既存のアカウントを検索してください。タイムアウトによってアカウントが紐付けられないままになるのを防ぐため、ネットワーク呼び出しの前に、ローカルのユーザーと account_id の対応関係を保存してください。
6. アカウントの閉鎖は、手順を調整する責任があります。 POST .../actions/close の前に、すべてのポジションを清算し、すべての現金を出金する必要があります。アカウントレコードは削除されず、ステータスが ACCOUNT_CLOSED になります。

関連スキル： アカウントへの入金 → alpaca-broker-funding-transfers；企業スイープを使った現金の入金 → alpaca-broker-journals；取引 → alpaca-broker-trading-orders；ステータスのリアルタイム追跡 → alpaca-broker-sse-events。