技能介绍

要解决的问题

券商账户体系里，把外部资金搬进用户账户、再把资金取出，是高频但琐碎的需求。Alpaca Broker API 为此提供了 ACH、Wire、Funding Wallet 三条通道，但三者的状态机、事件推送和字段约束并不统一。把持久的「银行链接（relationship）」和实际的「资金移动（transfer）」混为一谈，很容易在状态流转、费用展示与对账上踩坑。

技能如何工作

先建关系，再发起划转：ACH 与 Wire 都要求先创建 relationship（ach_relationships / recipient_banks），状态到达 APPROVED 后才能发起 transfer；一个 relationship 可支撑多次 transfer。
按通道选字段：transfer_type、amount（decimal 字符串，>0）、direction 为公共必填；ACH 传 relationship_id，Wire 传 bank_id，两者互斥。Wire 还支持 fee_payment_method（user 从金额中扣 / invoice 月结）与 additional_information（在非 Wire 请求中携带会返回 422）。
状态机与终态：经典 transfer 为 QUEUED → APPROVAL_PENDING → PENDING → SENT_TO_CLEARING → COMPLETE，REJECTED / CANCELED / RETURNED / EXPIRED 为失败终态；Funding Wallet 则使用 PENDING / EXECUTED / COMPLETE / CANCELED / FAILED，direction 为小写。
事件优先，轮询兜底：经典 ACH/Wire 有统一 SSE 流 GET /v2/events/funding/status，支持 since / until 回放；Funding Wallet 的单笔状态不在推送中，需轮询 GET /v1beta/.../funding_wallet/transfers/{id}。建议建立状态映射表，并对非终态 transfer 跑对账轮询。

适用边界与注意点

Wire 自 2022-06-01 起对出站收手续费，requested_amount 与 amount + fee 需在 UI 中区分展示。
入站 Wire 需要 FFC 指令才会自动入账；所有入金（含低于 FinCEN $3,000）都要传 Travel Rule 信息，并留存至少 5 年。
ACH 通过 Plaid 的 processor_token 建立，账户类型限 CHECKING / SAVINGS；immediate 参数已废弃（2026-08-26 下线），不要再传。
跨境 Wire 遗漏中间行/代理行 BIC 可能导致自动选择、延迟或额外费用。
沙箱 Wire 是异步的，仅工作日自动完成；账户之间的内部资金调拨应使用 journals，不走这套接口。