技能介绍

要解决的问题

接入 Alpaca Broker API 时，开户是整个集成链路的起点。如果账户没有达到 ACTIVE 状态，后续的入金、资金划转和交易都会失败。然而，Broker 的开户流程远不止调用一个接口：它要求你正确组装 contact、identity、disclosures、agreements 四个必填对象，处理国家代码、税务 ID 类型、资金来源等易错字段，提交具有法律效力的协议签署记录，上传 KYC 文档或结构化 W-8BEN，并通过异步状态轮询或 SSE 事件判断账户何时真正可用。任何一处细节出错，都可能导致 409、422 或更隐蔽的下游故障。

核心能力与工作流程

该技能封装了账户入驻的关键步骤。通过 POST /v1/accounts 创建账户，自动处理必填字段、可选的 account_type 和 enabled_assets。协议签署要求捕获真实的 signed_at（RFC3339）和 ip_address（IPv4），作为法律记录。文档上传支持 base64 或 content_data；对于非美国个人的 W-8BEN，可以上传结构化的 W8benDocument JSON，由 Alpaca 自动渲染官方表格，避免手动生成 PDF。账户状态遵循 SUBMITTED → APPROVAL_PENDING → APPROVED → ACTIVE 的路径，技能会解析 status 和 kyc_results，并建议订阅 SSE 事件或轮询来驱动 UI。

适用边界与注意点

不要把创建账户当成同步操作：POST /v1/accounts 返回 200 不代表账户可交易，必须等待 status == ACTIVE。国家字段必须为 ISO 3166-1 alpha-3（如 USA、PHL），在发送前剥离旗帜或显示名。重复邮箱会触发 409，应视为幂等信号，而非错误重试。关闭账户前必须先清算头寸和提取现金。此外，生产代码需防止 sandbox/paper 账户 ID 进入 live 事件处理器，避免误改真实记录。