Alpaca 券商资金划转

要解决什么问题

券商账户里的钱总要进出。Alpaca Broker API 给的是三条资金通道——ACH、Wire、Funding Wallet——但文档把「绑卡」和「划款」混在一起讲，接入时很容易踩坑：以为创建一条银行关系就能转账，结果发现关系还在 QUEUED；或者对每笔转账轮询状态，却发现经典转账早有 SSE 推送。

这个技能把资金模型拆开，明确告诉你什么时候该创建关系、什么时候该发起转账、什么时候该监听事件而不是轮询。

核心模型：关系与转账分离

Bank Relationship（/ach_relationships、/recipient_banks）只是登记一个外部银行账户，本身不动钱，有独立状态。Transfer（/transfers）通过 relationship_id 或 bank_id 引用关系，才是真正触发资金移动的实体。一条关系可以支撑多笔转账。

三条通道的差异：

• ACH：INCOMING + OUTGOING，仅美国境内，推荐通过 Plaid processor_token 创建
• Wire：仅 OUTGOING，支持境内外（SWIFT）；入金由汇款行发起，需 FFC 指令才会自动入账
• Funding Wallet：走 /v1beta 接口，多币种，支持 swift_wire / local_rails

创建转账时 amount 是十进制字符串且必须大于 0；additional_information 只在 wire 请求里可用，用在 ACH 上会返回 422。

事件与轮询不能一概而论

这是最值得注意的可靠性差异：经典 ACH/wire 转账有 SSE 流（/v2/events/funding/status），统一推送 Transfer、BankRelationship、WireBank、FundingWallet 四类实体，且支持 since/until 回放。但 Funding Wallet 的单笔转账状态并不进事件流，只能轮询 GET /v1beta/.../funding_wallet/transfers/{id}。

所以技能建议：按通道决定消费方式，再做一个状态对账轮询器兜底（SSE 可能丢事件），并且只轮询处于非终态的转账。终态包括 COMPLETE、REJECTED、CANCELED、RETURNED。

注意点

• 电汇手续费自 2022-06-01 起对出金收取，UI 要区分 requested_amount 和实际到账金额
• Travel Rule：所有入金不论金额都要传汇款人信息，保留至少 5 年
• 入金 wire 需要 FFC 指令才会自动入账
• 国际电汇漏填中间行 BIC 可能导致自动选择路由、延迟或额外费用
• Sandbox 电汇仅工作日推进，周末提交要等到周一
• immediate 字段已废弃并被静默忽略，不要再传

另外，如果生产环境用 omnibus/sweep 账户模式（用户付款到公司账户，再通过 journal 内部划拨），那么这个技能处理的只是「公司账户 ↔ 外部世界」这一段。