Alpaca 券商开户与 KYC 接入

解决什么问题

在接入 Alpaca Broker API 时，最常见的卡点不是下单，而是开户。任何资金划转、调拨或交易，都要求账户状态达到 ACTIVE。这意味着你需要一套能稳定提交 KYC/CIP 信息、上传合规文档、处理协议签署元数据，并能实时跟踪开户状态变更的流程。本技能聚焦于这套前置链路，避免你把「创建账户」当成一次同步的表单提交，结果在账户尚未可用时就尝试交易，导致请求失败。

核心能力与关键步骤

• 创建账户：通过 POST /v1/accounts 提交申请，构造 contact、identity、disclosures、agreements 四类必填对象。对于 contact.street_address 这类字段，需要按数组形式传入；而涉及国家字段时，应先调用 GET /v1/country-info 做 ISO 3166-1 alpha-3 校验。
• 协议与文档：协议中的 signed_at 与 ip_address 是法律记录，必须反映用户真实操作。文档上传支持 PDF/PNG/JPEG，且 W-8BEN 可直接通过结构化 JSON 传入，无需手工生成 PDF。
• 状态生命周期：开户本质是异步流程。创建成功后，应持久化 account_id，并订阅账户状态事件或轮询接口，而不是把 200 响应当作账户可用。

适用边界与注意点

• 不要在账户未达到 ACTIVE 时执行任何交易或资金操作。
• 如果在生产环境中同时运行沙盒与实盘，务必在事件处理中过滤沙盒账户，避免误改真实数据。
• 提交时遇到 409 通常意味着邮箱已注册，应转为查询既有账户，而不是重复创建。
• 关闭账户前必须先清空持仓并提取现金，ACCOUNT_CLOSED 是终态且记录不会消失。