alpaca-broker-funding-transfers

Alpaca Broker API — 资金存取与转账

向终端用户账户存入和提取现金。共有 三种外部渠道，另有即时入金；对于外部渠道，模型明确分为 银行关联（持久存在）和 转账（实际资金流动）。

请先阅读 alpaca-broker-integration，了解基础 URL 和身份验证（客户端凭据 Bearer 令牌；旧版 Basic 仍可使用）。如需在你的综合账户内的账户之间转移现金（而非与外部世界之间转账），请参阅 alpaca-broker-journals——这是另一种机制。

参考

• 指南：https://docs.alpaca.markets/docs/funding-accounts
• API 参考：https://docs.alpaca.markets/reference/createtransferforaccount
• 实时架构：alpaca-docs MCP → get-endpoint 标题 "Broker API"，路径 /v1/accounts/{account_id}/transfers

1. 资金模型

External bank ──(relationship: a persistent link)──┐
                                                    ├──> Transfer (the money movement) ──> Account cash
ACH relationship  (rail A: ACH, US domestic)        │
Bank relationship (rail B: wire, domestic + intl)   │
Funding wallet    (rail C: v1beta, multi-currency)  ┘

• 关联关系用于关联外部银行。它不会转移资金，并且有自己的状态；对于电汇，必须先达到 APPROVED 状态，转账才能继续。
• 转账通过 ID 引用关联关系并转移资金。一项关联关系可支持多笔转账。

渠道	transfer_type	方向	关联关系	备注
ACH	ach	INCOMING + OUTGOING	ACH 关联关系（relationship_id）	美国境内；通过 Plaid processor_token 设置（推荐）
电汇	wire	仅 OUTGOING	银行关联关系（bank_id）	境内和国际（SWIFT）。入账电汇由汇出银行发起并自动记账
资金钱包	（独立的 /v1beta API）	incoming / outgoing（小写）	资金钱包收款银行	多币种，swift_wire/local_rails
即时入金	（独立的 /v1/instant_funding API）	仅入账	无——由你自行收取款项	立即提高购买力，并于 T+1 通过电汇批量结算。参见 §8

2. 端点

方法	路径	用途
POST/GET/DELETE	/v1/accounts/{id}/ach_relationships[/{rel_id}]	管理 ACH 银行关联
POST/GET/DELETE	/v1/accounts/{id}/recipient_banks[/{bank_id}]	管理电汇收款银行
POST	/v1/accounts/{id}/transfers	创建转账（ACH 入金/出金，或电汇出金）
GET	/v1/accounts/{id}/transfers	列出转账
DELETE	/v1/accounts/{id}/transfers/{transfer_id}	请求取消
POST/GET	/v1beta/accounts/{id}/funding_wallet	创建 / 获取资金钱包
GET	/v1beta/accounts/{id}/funding_wallet/funding_details	钱包存款说明
POST/GET/DELETE	/v1beta/accounts/{id}/funding_wallet/recipient_bank	资金钱包收款银行
POST	/v1beta/accounts/{id}/funding_wallet/withdrawal	资金钱包提款
GET	/v1beta/accounts/{id}/funding_wallet/transfers[/{transfer_id}]	列出 / 获取钱包转账
POST/GET/DELETE	/v1/instant_funding[/{instant_funding_id}]	创建 / 获取 / 撤销即时入金转账
GET	/v1/instant_funding/limits	代理商级别限额（每个账户的限额见 /limits/accounts）
POST	/v1/instant_funding/settlements	触发已创建转账的结算
GET	/v2/events/funding/status	SSE — 统一资金状态流（参见 §6）

当前的电汇银行端点为 /recipient_banks（架构 Bank/CreateBankRequest）。旧名称 /banks 是兼容别名。

**钱包存款流程：**创建钱包 → 使用 GET .../funding_wallet/funding_details 获取要提供给客户的说明 → 客户发起资金转入（在沙盒环境中使用 POST /v1beta/demo/banking/funding）→ 轮询 GET .../funding_wallet/transfers。

3. 创建转账请求（POST /v1/accounts/{id}/transfers）

所有请求均必填：transfer_type、amount（十进制字符串，> 0）、direction。

// ACH deposit
{ "transfer_type": "ach", "relationship_id": "<uuid>", "amount": "100.00", "direction": "INCOMING" }

// Wire withdrawal
{ "transfer_type": "wire", "bank_id": "<uuid>", "amount": "500.00", "direction": "OUTGOING",
  "fee_payment_method": "user", "additional_information": "..." }

• relationship_id 仅在 ach 时必填；bank_id 仅在 wire 时必填（且另一个字段必须为空）。
• fee_payment_method（wire）：user（从 amount 中扣除费用；应在 UI 中提醒用户）或 invoice（按月向公司收费）。只有出金 wire 费用会自动处理。
• additional_information 仅适用于 wire——在非 wire 请求中发送该字段会返回 422。
• Transfer 响应会增加 id、status、fee、requested_amount（原始请求金额）、reason 和时间戳。

4. Wire 收款银行（POST /v1/accounts/{id}/recipient_banks）

必填：name、bank_code、bank_code_type、account_number。

• bank_code_type：ABA（9 位路由号码，境内）或 BIC（SWIFT，国际）。
• 使用 BIC 时，country、city、state_province、postal_code、street_address 为必填。
• extra_fields 用于传递中间行／代理行 BIC（intermediary_bank1_bic……）。国际 wire 若省略这些信息，可能导致自动选择、延误或额外费用——跨境转账应提前收集这些信息。
• 新银行的状态为 QUEUED；在针对该银行的 wire 转账继续处理前，状态必须变为 APPROVED。

5. 转账状态状态机

经典转账（TransferStatus）： QUEUED → APPROVAL_PENDING → PENDING → SENT_TO_CLEARING → (APPROVED) → COMPLETE，失败时则转为 REJECTED／CANCELED／RETURNED。

终态	含义
COMPLETE	已结算
REJECTED	已拒绝
CANCELED	客户发起取消
RETURNED	银行发起 ACH 退回

（SSE Transfer 实体也会报告 EXPIRED，它实际上也是终态。）

资金钱包转账： PENDING → EXECUTED → COMPLETE，其他退出状态包括 REJECTED（银行拒绝，通常是输入错误）和 FAILED（银行错误）。钱包转账不能取消；终态为 COMPLETE／REJECTED／FAILED。OpenAPI 的 FundingWalletTransferStatus 枚举仍列出 CANCELED，却遗漏了 REJECTED——请以指南为准，并将这两者都视为终态。注意，此处方向使用小写 incoming／outgoing——与经典转账的大小写不同。

6. 事件与轮询——关键的可靠性经验

经典转账有 SSE 流： GET /v2/events/funding/status。该流统一涵盖四种 entity_type 值——Transfer、BankRelationship、WireBank、FundingWallet——并可通过 since／until（时间戳）或 since_id／until_id（ULID）重放。经典 ACH／wire 状态应使用该流，而不是轮询。

资金钱包的单笔转账状态似乎不会推送——流中只有钱包级状态（active／pending）。单笔钱包转账状态（PENDING→EXECUTED→COMPLETE）必须通过 GET /v1beta/.../funding_wallet/transfers/{id} 轮询。

经验（来之不易）： 不同支付通道的事件覆盖范围各不相同。应针对每种通道决定使用 SSE 还是轮询，并为事件未覆盖的情况构建状态对账轮询器（即使已覆盖，也应作为安全保障——SSE 可能会丢失）。使用明确的查找表，将 Alpaca 的每种状态映射到你自己的内部状态；并且只轮询仍处于非终态的转账。参见 alpaca-broker-reconciliation-idempotency。

旧版注意事项：较旧的 us/sse-events“Transfer Events”负载使用整数 event_id 和小写状态；新版 /v2/events/funding/status 使用 ULID。请迁移到 v2。

7. 已记录的注意事项

• 电汇费用（自 2022-06-01 起）： 国内和国际出境电汇均会收费。在界面中反映 requested_amount 与 amount+fee 的区别。
• 入境电汇需要 FFC（For Further Credit，转入指定账户）指令才能自动入账；否则将由人工处理。
• Travel Rule： Alpaca 要求提供所有入金的汇款人/发起人信息，无论金额大小（包括低于通常的 FinCEN 3,000 美元门槛的金额）。创建结算时传入这些信息；信息至少保留 5 年。
• ACH 使用 Plaid： 通过 processor_token 传入银行。关联关系中有一个 instant 标志。账户类型仅限 CHECKING/SAVINGS。
• 权限错误： 账户无权存款或取款时会返回 403。错误消息会指出失败的权限（depositable_status / withdrawable_status）；账户对象上没有这些字段，因此无法预先检查——处理 403 并显示其错误消息。尝试入境电汇、关联关系与银行 ID 缺失或不匹配，或金额低于（未公开的）最低限额时会返回 422。
• 沙盒电汇行为： 全流程模拟，但为异步处理，且仅在工作日自动完成——周末提交的交易要到周一才会继续处理。（沙盒中的 ACH 会即时结算。）

8. 即时可用性：两种支持的模式

Alpaca 记录了两种方式，可让用户在现金到账前进行交易，但两者的结算义务不同。

现金池（综合账户 + 日记账）——文档称这是最常见的用例：先批量电汇至已预注资的公司账户，然后在收到用户付款时立即通过 JNLC 向用户入账；取款则反向操作。你预先注资，因此无需为每笔转账向 Alpaca 欠款。需要 Alpaca 审核，也可能需要当地的货币传输机构牌照。请参阅 alpaca-broker-journals。

即时注资——POST /v1/instant_funding 会在用户账户中增加购买力，无需预先注资，因此是 Alpaca 向你提供信用额度，你之后再结算。每个账户的限额默认为 1,000 美元，可申请提高；代理机构可用额度查询接口为 GET /v1/instant_funding/limits，每个账户可用额度查询接口为 GET /v1/instant_funding/limits/accounts?account_numbers=…。

结算由你负责，而且期限很紧。转账按 24 小时窗口批处理，窗口于美国东部时间晚上 8 点结束；你需向 SI 公司账户汇入一笔批量款项，然后在 T+1 的美国东部时间下午 1 点前调用 POST /v1/instant_funding/settlements（携带 Travel Rule 的 originator_* 字段）。逾期结算会按 FED UB + 8% 计收罚息，并按月开具账单。未对账的转账会在 T+1 的美国东部时间晚上 8 点自动取消；如果客户已使用这笔信用额度，其账户就会出现借方余额。完整流程：https://docs.alpaca.markets/us/docs/instant-funding。

相关技能： 内部现金划转 → alpaca-broker-journals；漏处理状态的恢复 → alpaca-broker-reconciliation-idempotency；金额格式化 → alpaca-broker-money-precision；实时状态 → alpaca-broker-sse-events。