Alpaca券商资金划转

解决什么问题

把现金弄进最终用户账户（入金）或从里面拿出来（出金）。这里有几个常见坑：把外部银行关系当成一笔转账，导致状态和 ID 引用混乱；把 omnibus 内部划转和外部入金混用同一机制，误用 journal；以为所有资金通道都有事件推送，结果 funding wallet 的单笔状态没有轮询，reconcile 缺位。

技能如何工作

模型拆成两层：

• 银行关系（bank link）：relationship_id（ACH）、bank_id（wire）、funding wallet 的 recipient bank。它本身不搬钱，有自己的 status，例如 wire 必须先到 APPROVED 才能继续。
• 转账（transfer）：引用上面的关系真正移动资金，一个关系可支撑多笔转账。

三条 rail：ACH（美国境内，推荐用 Plaid 的 processor_token 建关系）；Wire（仅 outgoing，bank_code_type 选 ABA 或 BIC，跨境要带 intermediary/correspondent BIC，否则可能被自动选择、延迟或多收费）；Funding wallet（/v1beta，多币种，swift_wire/local_rails）。注意 wire 的当前端点是 /recipient_banks，旧的 /banks 只是历史别名。

关键步骤：先读 alpaca-broker-integration（Broker API + HTTP Basic auth）；按 rail 建关系；发 POST /v1/accounts/{id}/transfers；订阅 GET /v2/events/funding/status 的 SSE；事件不可用时，用 reconcile poller 只查询非终态的转账。

状态机与可靠性

经典转账走 QUEUED → APPROVAL_PENDING → PENDING → SENT_TO_CLEARING → COMPLETE，终态包括 REJECTED、CANCELED、RETURNED。funding wallet 用另一套 PENDING / EXECUTED / COMPLETE / CANCELED / FAILED，direction 还是小写的 incoming/outgoing。

SSE 覆盖经典 ACH/wire，可用 since/until（时间戳）或 since_id/until_id（ULID）重放；funding wallet 的单笔状态不在推送里，只能轮询。因此要维护一张 Alpaca 状态到内部状态的显式映射表，并且只轮询非终态的转账——SSE 本身也可能丢。

注意点

additional_information 仅 wire 可用，非 wire 请求带它会返回 422。fee_payment_method 选 user 时费用从金额里扣，UI 要提示用户；选 invoice 则按月向机构收费，且只有 outgoing wire 会自动扣费。入金 wire 需要 FFC（For Further Credit）指令才能自动入账。Travel Rule 要求所有 incoming deposits 无论金额都传 transmitter/originator 信息，并至少保留 5 年。ACH 账户类型只支持 CHECKING/SAVINGS。immediate 参数已废弃且会被静默忽略，别再发送。同一 omnibus 下账户之间的现金移动走 alpaca-broker-journals，不是这套 endpoint。