alpaca-broker-account-onboarding

Alpaca Broker API — 账户开户与 KYC

在您的公司名下创建和管理终端用户经纪账户。这是任何 Broker API 集成的第一步：账户达到 ACTIVE 之前，无法进行入金、账簿划转或交易。

请先阅读 alpaca-broker-integration，了解基础 URL 和身份验证（客户端凭据 Bearer 令牌；旧版 Basic 仍然可用）。

参考资料

• 指南：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}	获取单个账户（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）

四个对象为必填项：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。
• 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 有效期有限。**除签署当年外，每三年必须提交一份新表格——请安排续期，不要把上传视为一次性操作。
• 文档大小上限：使用 Alpaca 的 KYC 即服务时，每个文件 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 后才启用入金、账簿分录或交易。尝试向非活动账户记账或交易会失败。加密货币操作应以 crypto_status 为准，因为它与 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。
• 开立个人账户的最低要求：验证姓名、出生日期、地址和身份证件号码。
• 除非 Alpaca 另行要求，否则 WATCHLIST_HIT 无需账户所有者采取任何操作。

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，两个环境使用不同的主机和凭证。
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。