Alpaca Funding Wallets API

openapi: 3.2.0
info:
  contact:
    email: support@alpaca.markets
    name: Alpaca Support
    url: https://alpaca.markets/support
  description: Open brokerage accounts, enable stock, options and crypto trading. Manage the ongoing user experience and brokerage customer lifecycle with the Alpaca Broker API
  termsOfService: https://s3.amazonaws.com/files.alpaca.markets/disclosures/library/TermsAndConditions.pdf
  title: Broker Funding Wallets API
  version: 1.1.1
servers:
- description: Sandbox endpoint
  url: https://broker-api.sandbox.alpaca.markets
- description: Production endpoint
  url: https://broker-api.alpaca.markets
security:
- BasicAuth: []
tags:
- name: Funding Wallets
paths:
  /v1beta/accounts/{account_id}/funding_wallet:
    get:
      description: Returns the funding wallet for the specified account. Responds with 404 if the account has not been onboarded to funding wallets or a wallet has not been created.
      operationId: getFundingWallet
      parameters:
      - description: UUID alpaca account ID
        in: path
        name: account_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundingWallet'
          description: funding wallet
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: error
      summary: Retrieve funding wallet
      tags:
      - Funding Wallets
    post:
      description: Creates a funding wallet for the specified account. The request is rejected if the account already has a funding wallet.
      operationId: createFundingWallet
      parameters:
      - description: UUID alpaca account ID
        in: path
        name: account_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundingWallet'
          description: funding wallet
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: error
      summary: Creates a funding wallet
      tags:
      - Funding Wallets
  /v1beta/accounts/{account_id}/funding_wallet/funding_details:
    get:
      description: Returns a list of funding details if it exists. Query parameters must be passed to create a new funding details object if none exist.
      operationId: listFundingDetails
      parameters:
      - description: UUID alpaca account ID
        in: path
        name: account_id
        required: true
        schema:
          type: string
      - description: The type of SSI to be returned, priority (SWIFT) or regular (local). A null value returns all payment types.
        in: query
        name: payment_type
        required: false
        schema:
          $ref: '#/components/schemas/FundingDetailPaymentType'
      - description: Should be provided in ISO 4217 standard
        in: query
        name: currency
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ListFundingDetails'
          description: list of wallets
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: error
      summary: Retrieve funding details
      tags:
      - Funding Wallets
  /v1beta/accounts/{account_id}/funding_wallet/recipient_bank:
    delete:
      description: deletes a recipient bank.
      operationId: deleteFundingWalletRecipientBank
      parameters:
      - description: UUID alpaca account ID
        in: path
        name: account_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: recipient bank
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Error response.
      summary: Delete a recipient bank
      tags:
      - Funding Wallets
    get:
      description: Returns the recipient bank registered against the specified account's funding wallet. Responds with 404 if no recipient bank has been registered for the account.
      operationId: getFundingWalletRecipientBank
      parameters:
      - description: UUID alpaca account ID
        in: path
        name: account_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: recipient bank
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Error response.
      summary: Retrieve recipient bank
      tags:
      - Funding Wallets
    post:
      description: Creates a new recipient bank. Returns the new recipient bank entity on success. entity.
      operationId: createFundingWalletRecipientBank
      parameters:
      - description: UUID alpaca account ID
        in: path
        name: account_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                account_number:
                  description: Bank account number.
                  type: string
                account_type:
                  description: Bank account type.
                  enum:
                  - checking
                  - savings
                  type: string
                bank_account_holder_name:
                  description: Bank account holder's name.
                  type: string
                bank_country:
                  description: Two-letter code for the country in which the beneficiary's bank account is held.
                  type: string
                bank_name:
                  type: string
                bic_swift:
                  description: BIC/SWIFT code
                  type: string
                city:
                  description: City
                  type: string
                currency:
                  description: Currency in which money is held in the beneficiary's bank account. ISO-3 currency code.
                  type: string
                iban:
                  description: IBAN code
                  type: string
                postal_code:
                  description: Postal code
                  type: string
                routing_code:
                  description: Routing code for routing_code_type. If supplied, routing_code_type should also be supplied.
                  type: string
                routing_code_type:
                  description: Local payment routing system. If supplied, routing_code should also be supplied.
                  enum:
                  - sort_code
                  - aba
                  - bsb_code
                  - institution_no
                  - bank_code
                  - branch_code
                  - clabe
                  - cnaps
                  - ifsc
                  type: string
                state_or_province:
                  description: State or province.
                  type: string
                street_address:
                  description: First line of address.
                  type: string
              required:
              - bank_country
              - currency
              - bank_name
              - street_address
              - city
              - account_number
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundingWalletRecipientBank'
          description: Success.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: error
      summary: Create a recipient bank
      tags:
      - Funding Wallets
  /v1beta/accounts/{account_id}/funding_wallet/transfers:
    get:
      description: Returns all funding wallet transfers (deposits and withdrawals) associated with the specified account.
      operationId: getFundingWalletTransfers
      parameters:
      - description: UUID alpaca account ID
        in: path
        name: account_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTransfersResponse'
          description: transfers
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: error
      summary: Retrieve funding wallet transfers
      tags:
      - Funding Wallets
  /v1beta/accounts/{account_id}/funding_wallet/transfers/{transfer_id}:
    get:
      description: Returns a single funding wallet transfer for the specified account by `transfer_id`. Responds with 404 if no matching transfer exists for the account.
      operationId: getFundingWalletTransferByID
      parameters:
      - description: Alpaca account UUID
        in: path
        name: account_id
        required: true
        schema:
          type: string
      - description: transfer UUID
        in: path
        name: transfer_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundingWalletTransfer'
          description: transfer response if found
        '404':
          description: error response if transfer is not found
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: error
      summary: Retrieve funding wallet transfer by ID
      tags:
      - Funding Wallets
  /v1beta/accounts/{account_id}/funding_wallet/withdrawal:
    post:
      description: Creates a withdrawal
      operationId: createFundingWalletWithdrawal
      parameters:
      - description: UUID alpaca account ID
        in: path
        name: account_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFundingWalletWithdrawalRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundingWalletTransfer'
          description: Transfer
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Error response.
      summary: Create a withdrawal
      tags:
      - Funding Wallets
  /v1beta/accounts/funding_wallet:
    post:
      description: Creates funding wallets for a list of accounts in a single request. Every `account_id` in the request must belong to your firm, and the request is rejected if a funding wallet already exists for any of the supplied accounts.
      operationId: batchCreateFundingWallets
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchCreateFundingWalletRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchCreateFundingWalletResponse'
          description: Funding wallets
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Error response.
      summary: Batch create funding wallets
      tags:
      - Funding Wallets
  /v1beta/demo/banking/funding:
    post:
      description: 'Simulates an inbound deposit into an account''s funding wallet for end-to-end testing of the deposit flow.


        The transfer can only credit accounts that belong to your firm. Available in non-production (sandbox) environments only.'
      operationId: demoDepositFunding
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DemoFundingTransfer'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DemoFundingTransfer'
          description: Demo deposit funding transfer
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Error response.
      summary: Create sandbox deposit transfer
      tags:
      - Funding Wallets
components:
  schemas:
    ListFundingDetails:
      properties:
        funding_details:
          items:
            $ref: '#/components/schemas/FundingDetail'
          type: array
      type: object
    BatchCreateFundingWalletResponse:
      properties:
        funding_wallets:
          items:
            $ref: '#/components/schemas/FundingWallet'
          type: array
      type: object
    Error:
      properties:
        code:
          description: Alpaca error code, such as `40310000`. Usually the HTTP status code followed by a five-digit suffix. Several errors can share the same code, so check `message` for the specific reason.
          type: number
        message:
          description: Human-readable reason for the rejection.
          type: string
      required:
      - code
      - message
      title: Error
      type: object
    FundingDetailRoutingCodeType:
      description: "Status:\n * `BIC`: bic_swift\n * `ACH`: ach_routing_code\n * `ABA`: aba\n * `ROUTING`: routing_code\n * `SORT_CODE`: sort_code\n"
      enum:
      - BIC
      - ACH_ROUTING
      - ABA
      - ROUTING
      - SORT_CODE
      type: string
    CreateFundingWalletWithdrawalRequest:
      properties:
        desired_currency:
          type: string
        fee_inclusive:
          default: false
          description: 'When true, fees are deducted from `usd_amount` instead of being added on top, so the total amount debited from the account equals `usd_amount` exactly (the beneficiary receives `usd_amount` minus fees). This lets the account be drained to zero: pass the account''s full available cash as `usd_amount`. The request is rejected if `usd_amount` is less than or equal to the fees. Defaults to false (fees added on top of `usd_amount`).

            '
          type: boolean
        payment_type:
          $ref: '#/components/schemas/FundingDetailPaymentType'
        usd_amount:
          format: decimal
          type: string
      type: object
    FundingDetailPaymentType:
      description: "Status:\n * `swift_wire`: SWIFT wire\n * `local_rails`: Local scheme\n"
      enum:
      - swift_wire
      - local_rails
      type: string
    ListTransfersResponse:
      properties:
        transfers:
          items:
            $ref: '#/components/schemas/FundingWalletTransfer'
          type: array
      type: object
    DemoFundingTransfer:
      properties:
        amount:
          format: decimal
          type: string
        currency:
          type: string
        receiver_account_number:
          type: string
        receiver_routing_code:
          type: string
      type: object
    FundingWalletTransferDirection:
      description: "Status:\n * `incoming`: incoming amount\n * `outgoing`: outgoing amount\n"
      enum:
      - incoming
      - outgoing
      type: string
    FundingWalletStatus:
      description: "Status:\n * `active`: The funding wallet is ready\n * `pending`: The funding wallet is being processed\n * `disabled`: The funding wallet is disabled\n"
      enum:
      - active
      - pending
      - disabled
      type: string
    FundingWalletTransferStatus:
      description: "Status:\n * `PENDING`: Created and waiting to be processed\n * `CANCELED`: Canceled\n * `FAILED`: Failed mostly due to technical reasons\n * `COMPLETE`: Transfer has settled\n"
      enum:
      - PENDING
      - CANCELED
      - EXECUTED
      - FAILED
      - COMPLETE
      type: string
    FeePaymentType:
      description: "Status:\n * `invoice`\n"
      enum:
      - invoice
      type: string
    TransferFee:
      properties:
        amount:
          format: decimal
          type: string
        currency:
          $ref: '#/components/schemas/Currency'
        payment_type:
          $ref: '#/components/schemas/FeePaymentType'
        type:
          $ref: '#/components/schemas/FeeType'
      required:
      - type
      - amount
      - currency
      - payment_type
      type: object
    FundingWallet:
      properties:
        account_id:
          format: uuid
          type: string
        created_at:
          format: date-time
          type: string
        status:
          $ref: '#/components/schemas/FundingWalletStatus'
      required:
      - account_id
      - status
      - created_at
      type: object
    FundingWalletRecipientBank:
      properties:
        account_number:
          description: Bank account number.
          type: string
        bic_swift:
          description: BIC/SWIFT code
          type: string
        city:
          description: City
          type: string
        company_name:
          type: string
        country:
          description: Two-letter ISO country code.
          type: string
        created_at:
          description: Date the beneficiary record was created.
          format: date-time
          type: string
        currency:
          description: Currency in which money is held in the beneficiary's bank account. Three-digit currency code.
          type: string
        first_name:
          type: string
        iban:
          description: IBAN code
          type: string
        id:
          format: uuid
          type: string
        last_name:
          type: string
        payment_types:
          items:
            $ref: '#/components/schemas/FundingDetailPaymentType'
          type: array
        postal_code:
          description: Postal code
          type: string
        routing_code:
          description: Value for "routing_code_type".
          type: string
        routing_code_type:
          description: Local payment routing system.
          type: string
        state_or_province:
          description: State or province.
          type: string
        street_address:
          type: string
        updated_at:
          description: Date the beneficiary record was last updated.
          format: date-time
          type: string
      type: object
    FeeType:
      description: "Status:\n  * `withdrawal_fee`: Withdrawal fee\n  * `fx_fee`: FX Fee\n  * `network_fee`\n  * `deposit_fee`\n  * `ach_return_fee`\n  * `parnter_fee`\n  * `alpaca_fee`\n"
      enum:
      - withdrawal_fee
      - fx_fee
      - network_fee
      - deposit_fee
      - ach_return_fee
      - parnter_fee
      - alpaca_fee
      type: string
    FundingDetail:
      description: 'Gets funding details that can be used to settle and collect funds in each available currency.

        '
      properties:
        account_holder_name:
          type: string
        account_number:
          type: string
        account_number_type:
          type: string
        bank_address:
          type: string
        bank_country:
          type: string
        bank_name:
          type: string
        currency:
          type: string
        payment_type:
          $ref: '#/components/schemas/FundingDetailPaymentType'
        routing_code:
          type: string
        routing_code_type:
          $ref: '#/components/schemas/FundingDetailRoutingCodeType'
      type: object
    Currency:
      description: '"USD" // US Dollar

        "JPY" // Japanese Yen

        "EUR" // Euro

        "CAD" // Canadian Dollar

        "GBP" // British Pound Sterling

        "CHF" // Swiss Franc

        "TRY" // Turkish Lira

        "AUD" // Australian Dollar

        "CZK" // Czech Koruna

        "SEK" // Swedish Krona

        "DKK" // Danish Krone

        "SGD" // Singapore Dollar

        "HKD" // Hong Kong Dollar

        "HUF" // Hungarian Forint

        "NZD" // New Zealand Dollar

        "NOK" // Norwegian Krone

        "PLN" // Poland Złoty'
      title: Currency
      type: string
    FundingWalletTransfer:
      properties:
        account_id:
          format: uuid
          type: string
        created_at:
          format: date-time
          type: string
        direction:
          $ref: '#/components/schemas/FundingWalletTransferDirection'
        fees:
          items:
            $ref: '#/components/schemas/TransferFee'
          type: array
        id:
          format: uuid
          type: string
        original_amount:
          deprecated: true
          description: '**Deprecation notice:**

            Use `total_amount` for the actual amount debited from the account.


            Since: 2026-09-22

            Sunset: 2026-12-21


            ---


            The amount you should expect to receive, calculated as requested amount - fees.'
          format: decimal
          type: string
          x-deprecation:
            reason: Use `total_amount` for the actual amount debited from the account.
            since: '2026-09-22'
            sunset: '2026-12-21'
        original_currency:
          description: The currency of the withdrawn amount, 3-letter ISO code
          type: string
        payment_type:
          $ref: '#/components/schemas/FundingDetailPaymentType'
        requested_amount:
          description: The amount requested when the transfer was created.
          format: decimal
          type: string
        status:
          $ref: '#/components/schemas/FundingWalletTransferStatus'
        total_amount:
          description: The total amount moved for the transfer. For outgoing transfers with fees added on top, this is the requested amount plus fees (the total debited from the account). For fee-inclusive outgoing withdrawals, fees are taken out of the requested amount, so this equals requested_amount. For incoming transfers, this is the requested amount credited to the account.
          format: decimal
          type: string
        updated_at:
          format: date-time
          type: string
        usd:
          $ref: '#/components/schemas/Usd'
      type: object
    Usd:
      properties:
        amount:
          format: decimal
          type: string
      required:
      - amount
      type: object
    BatchCreateFundingWalletRequest:
      properties:
        account_ids:
          description: list of UUID account ids which will have funding wallets created
          items:
            type: string
          type: array
      type: object
  securitySchemes:
    BasicAuth:
      scheme: basic
      type: http
x-readme:
  explorer-enabled: true
  proxy-enabled: false