/funding-transfers

name: alpaca-broker-funding-transfers
description: Move money between an Alpaca brokerage account and the EXTERNAL banking world via the Broker API — ACH relationships, wire recipient banks, classic transfers (deposits/withdrawals), the v1beta funding wallet (international/instant), transfer status lifecycles, and fees. Use when building deposit/withdrawal flows or connecting external bank accounts on Alpaca in any language. For moving cash/shares BETWEEN accounts inside your own omnibus, use journals instead.

Alpaca Broker API — Funding & Transfers

Getting cash into and out of end-user accounts. There are **three external rails** plus Instant Funding, and for the external rails the model splits cleanly into *bank links* (persistent) and *transfers* (the actual money movement).

> Read `alpaca-broker-integration` first for base URLs and auth (client-credentials Bearer token; legacy Basic still works). For moving cash *between* accounts in your omnibus (vs. to/from the outside world), see `alpaca-broker-journals` — that's a different mechanism.

Reference

• Guide: `https://docs.alpaca.markets/docs/funding-accounts`
• API ref: `https://docs.alpaca.markets/reference/createtransferforaccount`
• Live schema: `alpaca-docs` MCP → `get-endpoint` title `"Broker API"` path `/v1/accounts/{account_id}/transfers`

1. The funding model

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)  ┘

• A **relationship** links an external bank. It moves no money and has its own status; for wires it must be `APPROVED` before a transfer can progress.
• A **transfer** references a relationship by ID and moves the money. One relationship backs many transfers.

| Rail | `transfer_type` | Directions | Relationship | Notes | |------|-----------------|-----------|--------------|-------| | **ACH** | `ach` | `INCOMING` + `OUTGOING` | ACH relationship (`relationship_id`) | US domestic; set up via Plaid `processor_token` (recommended) | | **Wire** | `wire` | `OUTGOING` only | Bank relationship (`bank_id`) | Domestic + international (SWIFT). Incoming wires are pushed by the sending bank and booked automatically | | **Funding wallet** | (separate `/v1beta` API) | `incoming` / `outgoing` (lowercase) | Funding-wallet recipient bank | Multi-currency, `swift_wire`/`local_rails` | | **Instant Funding** | (separate `/v1/instant_funding` API) | credit only | none — you collect the payment yourself | Extends buying power immediately, settled in bulk by wire on T+1. See §8 |

2. Endpoints

| Method | Path | Purpose | |--------|------|---------| | POST/GET/DELETE | `/v1/accounts/{id}/ach_relationships[/{rel_id}]` | Manage ACH bank links | | POST/GET/DELETE | `/v1/accounts/{id}/recipient_banks[/{bank_id}]` | Manage wire recipient banks | | POST | `/v1/accounts/{id}/transfers` | Create transfer (ACH deposit/withdraw, or wire withdraw) | | GET | `/v1/accounts/{id}/transfers` | List transfers | | DELETE | `/v1/accounts/{id}/transfers/{transfer_id}` | Request cancel | | POST/GET | `/v1beta/accounts/{id}/funding_wallet` | Create / get funding wallet | | GET | `/v1beta/accounts/{id}/funding_wallet/funding_details` | Deposit instructions for the wallet | | POST/GET/DELETE | `/v1beta/accounts/{id}/funding_wallet/recipient_bank` | Funding-wallet recipient bank | | POST | `/v1beta/accounts/{id}/funding_wallet/withdrawal` | Funding-wallet withdrawal | | GET | `/v1beta/accounts/{id}/funding_wallet/transfers[/{transfer_id}]` | List / get wallet transfers | | POST/GET/DELETE | `/v1/instant_funding[/{instant_funding_id}]` | Create / get / reverse an instant funding transfer | | GET | `/v1/instant_funding/limits` | Correspondent-level limits (`/limits/accounts` for per-account) | | POST | `/v1/instant_funding/settlements` | Trigger settlement of created transfers | | GET | `/v2/events/funding/status` | **SSE** — unified funding status stream (see §6) |

> The current wire-bank endpoint is **`/recipient_banks`** (schema `Bank`/`CreateBankRequest`). The older `/banks` name is a legacy alias.

**Wallet deposit flow:** create the wallet → `GET .../funding_wallet/funding_details` for the instructions to hand the customer → customer pushes funds (in sandbox, `POST /v1beta/demo/banking/funding`) → poll `GET .../funding_wallet/transfers`.

3. Create-transfer request (`POST /v1/accounts/{id}/transfers`)

Required for all: `transfer_type`, `amount` (decimal **string**, > 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` required iff `ach`; `bank_id` required iff `wire` (and must be the *other* one's empty).
• `fee_payment_method` (wire): `user` (fee deducted from `amount`; warn the user in UI) or `invoice` (firm billed monthly). Only **outgoing** wire fees auto-process.
• `additional_information` is wire-only — sending it on a non-wire request returns `422`.
• The `Transfer` response adds `id`, `status`, `fee`, `requested_amount` (original ask), `reason`, timestamps.

4. Wire recipient bank (`POST /v1/accounts/{id}/recipient_banks`)

Required: `name`, `bank_code`, `bank_code_type`, `account_number`.

• `bank_code_type`: `ABA` (9-digit routing, domestic) or `BIC` (SWIFT, international).
• When `BIC`: `country`, `city`, `state_province`, `postal_code`, `street_address` become required.
• `extra_fields` carries intermediary/correspondent BICs (`intermediary_bank1_bic`…). **Omitting them on international wires can cause auto-selection, delays, or extra fees** — gather them up fron