alpaca-broker-funding-transfers
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.
alpacahq · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add alpacahq/alpaca-skills --skill alpaca-broker-funding-transfersAbout this skill
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 rails, and the model splits cleanly into bank links (persistent) and transfers (the actual money movement).
Read
alpaca-broker-integrationfirst. Broker API + HTTP Basic auth. For moving cash between accounts in your omnibus (vs. to/from the outside world), seealpaca-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-docsMCP →get-endpointtitle"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
APPROVEDbefore 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 |
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 |
| 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 |
| GET | /v2/events/funding/status | SSE — unified funding status stream (see §6) |
The current wire-bank endpoint is
/recipient_banks(schemaBank/CreateBankRequest). The older/banksname is a legacy alias.
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_idrequired iffach;bank_idrequired iffwire(and must be the other one's empty).fee_payment_method(wire):user(fee deducted fromamount; warn the user in UI) orinvoice(firm billed monthly). Only outgoing wire fees auto-process.additional_informationis wire-only — sending it on a non-wire request returns422.- The
Transferresponse addsid,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) orBIC(SWIFT, international).- When
BIC:country,city,state_province,postal_code,street_addressbecome required. extra_fieldscarries intermediary/correspondent BICs (intermediary_bank1_bic…). Omitting them on international wires can cause auto-selection, delays, or extra fees — gather them up front for cross-border.- A new bank starts
QUEUED; it must reachAPPROVEDbefore a wire transfer against it progresses.
5. Transfer status state machines
Classic transfers (TransferStatus):
QUEUED → APPROVAL_PENDING → PENDING → SENT_TO_CLEARING → (APPROVED) → COMPLETE, with REJECTED / CANCELED / RETURNED as failure exits.
| Terminal | Meaning |
|---|---|
COMPLETE | Settled |
REJECTED | Rejected |
CANCELED | Client-initiated cancel |
RETURNED | Bank issued an ACH return |
(The SSE Transfer entity also reports EXPIRED, which is effectively terminal.)
Funding-wallet transfers (FundingWalletTransferStatus): PENDING, EXECUTED, COMPLETE, CANCELED, FAILED (last three terminal). Note lowercase incoming/outgoing directions here — different casing from classic transfers.
6. Events vs polling — the key reliability lesson
Classic transfers HAVE an SSE stream: `GET /v2/events/
Read the complete source ↗