openapi: 3.0.0
info:
  title: Broker Account Activities Funding API
  description: Open brokerage accounts, enable crypto and stock trading, and manage the ongoing user experience with Alpaca Broker API
  version: 1.0.0
  contact:
    name: Alpaca Support
    email: support@alpaca.markets
    url: https://alpaca.markets/support
  termsOfService: https://s3.amazonaws.com/files.alpaca.markets/disclosures/library/TermsAndConditions.pdf
servers:
- url: https://broker-api.sandbox.alpaca.markets
  description: Sandbox endpoint
- url: https://broker-api.alpaca.markets
  description: Production endpoint
security:
- BasicAuth: []
tags:
- name: Funding
paths:
  /v1/accounts/{account_id}/recipient_banks:
    parameters:
    - $ref: '#/components/parameters/AccountID'
    get:
      tags:
      - Funding
      summary: Retrieve bank relationships for an account
      parameters:
      - name: status
        in: query
        schema:
          type: string
          enum:
          - ACTIVE
          - INACTIVE
          example: ACTIVE
      - name: bank_name
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Success. Returns the bank relationship model.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Bank'
        '400':
          description: Bad request. The body in the request is not valid.
      operationId: getRecipientBanks
      description: Retrieves Bank Relationships for an account
    post:
      tags:
      - Funding
      summary: Create a Bank Relationship for an account
      parameters:
      - $ref: '#/components/parameters/AccountID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBankRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bank'
        '400':
          description: Bad Request
        '409':
          description: Conflict
      operationId: createRecipientBank
      description: If successful, retrieves Bank Relationships for an account
  /v1/accounts/{account_id}/recipient_banks/{bank_id}:
    parameters:
    - $ref: '#/components/parameters/AccountID'
    - name: bank_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    delete:
      tags:
      - Funding
      summary: Delete a Bank Relationship for an account
      responses:
        '204':
          description: Success (No Content)
        '400':
          description: Bad Request
        '404':
          description: Bank Not Found
      operationId: deleteRecipientBank
      description: If successful, deletes Bank Relationship for an account
  /v1/accounts/{account_id}/transfers:
    parameters:
    - $ref: '#/components/parameters/AccountID'
    get:
      summary: Return a list of transfers for an account.
      tags:
      - Funding
      description: 'You can query a list of transfers for an account.



        You can filter requested transfers by values such as direction and status.

        '
      parameters:
      - name: direction
        in: query
        schema:
          enum:
          - INCOMING
          - OUTGOING
          type: string
        description: INCOMING or OUTGOING
      - name: limit
        in: query
        schema:
          type: integer
          format: int32
      - name: offset
        in: query
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Transfer'
              examples:
                example-1:
                  value:
                  - id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
                    relationship_id: 81412018-ffa2-43f9-a3eb-d39f1c5e0f87
                    bank_id: f1ae96de-94c1-468e-93a3-6b7213930ca8
                    account_id: 449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65
                    type: ach
                    status: QUEUED
                    reason: string
                    amount: string
                    direction: INCOMING
                    created_at: '2019-08-24T14:15:22Z'
                    updated_at: '2019-08-24T14:15:22Z'
                    expires_at: '2019-08-24T14:15:22Z'
                    additional_information: string
                example-2:
                  value:
                  - id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
                    relationship_id: 81412018-ffa2-43f9-a3eb-d39f1c5e0f87
                    bank_id: f1ae96de-94c1-468e-93a3-6b7213930ca8
                    account_id: 449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65
                    type: ach
                    status: QUEUED
                    reason: string
                    amount: string
                    direction: INCOMING
                    created_at: '2019-08-24T14:15:22Z'
                    updated_at: '2019-08-24T14:15:22Z'
                    expires_at: '2019-08-24T14:15:22Z'
                    additional_information: string
      operationId: getTransfersForAccount
    post:
      summary: Request a new transfer
      tags:
      - Funding
      description: 'Create a new transfer to an account to fund it.


        In the sandbox environment, you can instantly deposit to or withdraw from an account with a virtual money amount. In the production environment, this endpoint is used only for requesting an outgoing (withdrawal) wire transfer at this moment. For the wire transfer (in production), you need to create a bank resource first using the Bank API. For more on how to fund an account in sandbox please check out this tutorial [here](https://alpaca.markets/learn/fund-broker-api/).'
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTransferRequest'
      responses:
        '200':
          description: Successfully requested a transfer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transfer'
      operationId: createTransferForAccount
  /v1/accounts/{account_id}/transfers/{transfer_id}:
    parameters:
    - $ref: '#/components/parameters/AccountID'
    - schema:
        type: string
        format: uuid
      name: transfer_id
      in: path
      required: true
      description: Tranfer identifier
    delete:
      summary: Request to close a transfer
      operationId: deleteTransfer
      responses:
        '204':
          description: Success (No Content)
        '404':
          $ref: '#/components/responses/NotFound'
      description: Request to close a transfer
      tags:
      - Funding
  /v1/accounts/{account_id}/ach_relationships:
    parameters:
    - $ref: '#/components/parameters/AccountID'
    get:
      summary: Retrieve ACH Relationships for an account
      tags:
      - Funding
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ACHRelationship'
      operationId: getAccountACHRelationships
      description: Returns a list of ACH Relationships for an account
      parameters:
      - schema:
          type: string
        in: query
        name: statuses
        description: Comma-separated status values
    post:
      summary: Create an ACH Relationship
      operationId: createACHRelationshipForAccount
      responses:
        '200':
          description: returns the newly created ACH Relationship entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ACHRelationship'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/NotAuthorized'
        '409':
          description: The account already has an active relationship.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: 'Create a new ACHRelationship for an account


        If successful, will return 200 code with a newly created ACH Relationship entity.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateACHRelationshipRequest'
        description: 'Create ACH Relationship '
      tags:
      - Funding
  /v1/accounts/{account_id}/ach_relationships/{ach_relationship_id}:
    parameters:
    - $ref: '#/components/parameters/AccountID'
    - schema:
        type: string
        format: uuid
      name: ach_relationship_id
      in: path
      description: ACH relationship identifier
      required: true
    delete:
      summary: Delete an existing ACH relationship
      operationId: deleteACHRelationshipFromAccount
      responses:
        '204':
          description: Success (No Content)
        '400':
          description: the passed in account_id or relationship_id were invalid
        '404':
          $ref: '#/components/responses/NotFound'
      description: Delete an existing ACH relationship for an account
      tags:
      - Funding
  /v1/events/transfers/status:
    parameters: []
    get:
      summary: Subscribe to Transfer Events (SSE)
      tags:
      - Funding
      responses:
        '200':
          description: Connected. Events will now start streaming as long as you keep the connection open.
          content:
            text/event-stream:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TransferStatusEvent'
      parameters:
      - name: since
        in: query
        schema:
          type: string
          format: date-time
        description: 'Format: YYYY-MM-DD'
      - name: until
        in: query
        schema:
          type: string
          format: date-time
        description: 'Format: YYYY-MM-DD'
      - name: since_id
        in: query
        schema:
          type: integer
      - name: until_id
        in: query
        schema:
          type: integer
      operationId: subscribeToTransferStatusSSE
      description: 'The Events API provides event push as well as historical queries via SSE (server sent events).


        You can listen to transfer status updates as they get processed by our backoffice, for both end-user and firm accounts.


        Historical events are streamed immediately if queried, and updates are pushed as events occur.


        Query Params Rules:

        - `since` required if `until` specified

        - `since_id` required if `until_id` specified

        - `since` and `since_id` can’t be used at the same time

        Behavior:

        - if `since` or `since_id` not specified this will not return any historic data

        - if `until` or `until_id` reached stream will end (status 200)


        ---


        Note for people using the clients generated from this OAS spec. Currently OAS-3 doesn''t have full support for representing SSE style responses from an API, so if you are using a generated client and don''t specify a `since` and `until` there is a good chance the generated clients will hang waiting for the response to end.


        If you require the streaming capabilities we recommend not using the generated clients for this specific usecase until the OAS-3 standards come to a consensus on how to represent this correcting in OAS-3.'
components:
  schemas:
    Transfer:
      title: Transfer
      type: object
      x-examples:
        example-1:
          id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
          relationship_id: 81412018-ffa2-43f9-a3eb-d39f1c5e0f87
          bank_id: f1ae96de-94c1-468e-93a3-6b7213930ca8
          account_id: 449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65
          type: ach
          status: QUEUED
          reason: string
          amount: string
          direction: INCOMING
          created_at: '2019-08-24T14:15:22Z'
          updated_at: '2019-08-24T14:15:22Z'
          expires_at: '2019-08-24T14:15:22Z'
          additional_information: string
      description: 'Transfers allow you to transfer money/balance into your end customers'' account (deposits) or out (withdrawal).


        [Main docs here](https://alpaca.markets/docs/api-references/broker-api/funding/transfers/#the-transfer-object)'
      properties:
        id:
          type: string
          format: uuid
          description: The transfer ID
        relationship_id:
          type: string
          format: uuid
          description: The ACH relationship ID only present if type = "ach"
        bank_id:
          type: string
          format: uuid
          description: The ID of the Bank, only present if type = "wire"
        account_id:
          type: string
          format: uuid
          description: The account ID
        type:
          $ref: '#/components/schemas/TransferType'
        status:
          $ref: '#/components/schemas/TransferStatus'
        reason:
          type: string
          description: Cause of the status
          nullable: true
        amount:
          type: string
          description: Must be > 0.00
          format: decimal
        direction:
          $ref: '#/components/schemas/TransferDirection'
        created_at:
          type: string
          format: date-time
          description: Timedate when transfer was created
        updated_at:
          type: string
          format: date-time
          description: Timedate when transfer was updated
        expires_at:
          type: string
          format: date-time
          description: Timedate when transfer was expired
        additional_information:
          type: string
          description: Additional information. Only applies when type = "wire".
          nullable: true
        hold_until:
          type: string
          format: date-time
        instant_amount:
          type: string
      required:
      - id
      - account_id
      - type
      - status
      - amount
      - direction
      - created_at
    TransferDirection:
      type: string
      example: INCOMING
      enum:
      - INCOMING
      - OUTGOING
      description: '- **INCOMING**

        Funds incoming to user’s account (deposit).

        - **OUTGOING**

        Funds outgoing from user’s account (withdrawal).

        '
    TransferStatus:
      type: string
      example: QUEUED
      enum:
      - QUEUED
      - APPROVAL_PENDING
      - PENDING
      - SENT_TO_CLEARING
      - REJECTED
      - CANCELED
      - APPROVED
      - COMPLETE
      - RETURNED
      description: '- **QUEUED**

        Transfer is in queue to be processed.

        - **APPROVAL_PENDING**

        Transfer is pending approval.

        - **PENDING**

        Transfer is pending processing.

        - **SENT_TO_CLEARING**

        Transfer is being processed by the clearing firm.

        - **REJECTED**

        Transfer is rejected.

        - **CANCELED**

        Client initiated transfer cancellation.

        - **APPROVED**

        Transfer is approved.

        - **COMPLETE**

        Transfer is completed.

        - **RETURNED**

        The bank issued an ACH return for the transfer.

        '
    ACHRelationship:
      title: ACHRelationship
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 61e69015-8549-4bfd-b9c3-01e75843f47d
        created_at:
          type: string
          format: date-time
          example: '2021-03-16T18:38:01.942282Z'
          description: 'Format: 2020-01-01T01:01:01Z'
        updated_at:
          type: string
          format: date-time
          example: '2021-03-16T18:38:01.942282Z'
          description: 'Format: 2020-01-01T01:01:01Z'
        account_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - QUEUED
          - APPROVED
          - PENDING
          - CANCEL_REQUESTED
        account_owner_name:
          type: string
          minLength: 1
          description: Name of the account owner
        bank_account_type:
          type: string
          minLength: 1
          enum:
          - CHECKING
          - SAVINGS
          description: Must be CHECKING or SAVINGS
        bank_account_number:
          type: string
          minLength: 1
        bank_routing_number:
          type: string
          minLength: 1
        nickname:
          type: string
          minLength: 1
      required:
      - id
      - created_at
      - updated_at
      - account_id
      - status
      - account_owner_name
    TransferType:
      type: string
      example: ach
      enum:
      - ach
      - instant_ach
      - wire
      description: '**NOTE:** The Sandbox environment currently only supports `ach`


        - **ach**

        Transfer via ACH (US Only).

        - **wire**

        Transfer via wire (international).

        '
      title: TransferType
    CreateACHRelationshipRequest:
      description: 'Represents the fields used in creation of a new ACHRelationship.


        You can create an ACHRelationship by passing the required fields here or if you have an account with Plaid you can use our integration with Plaid to create a relationship.


        Please see the documentation [here](https://alpaca.markets/docs/api-references/broker-api/funding/ach/#plaid-integration-for-bank-transfers) for more info on using Plaid with Alpaca'
      type: object
      title: CreateACHRelationshipRequest
      properties:
        account_owner_name:
          type: string
          minLength: 1
        bank_account_type:
          type: string
          minLength: 1
          enum:
          - CHECKING
          - SAVINGS
          description: Must be CHECKING or SAVINGS
        bank_account_number:
          type: string
          minLength: 1
          description: In sandbox, this still must be a valid format
        bank_routing_number:
          type: string
          minLength: 1
          description: In sandbox, this still must be a valid format
        nickname:
          type: string
          minLength: 1
        processor_token:
          type: string
          description: 'If using Plaid, you can specify a Plaid processor token here '
      required:
      - account_owner_name
      - bank_account_type
      - bank_account_number
      - bank_routing_number
    Bank:
      type: object
      x-examples:
        example-1:
          id: 8475c676-68e3-4cfc-a683-9ca2f47a6172
          account_id: 56712986-9ff7-4d8f-8e52-077e099e533e
          name: Bank XYZ
          status: QUEUED
          country: ''
          state_province: ''
          postal_code: ''
          city: ''
          street_address: ''
          account_number: 123456789abc
          bank_code: '123456789'
          bank_code_type: ABA
          created_at: '2022-02-11T21:35:19.268681613Z'
          updated_at: '2022-02-11T21:35:19.268681613Z'
      properties:
        id:
          type: string
          format: uuid
          example: 61e69015-8549-4bfd-b9c3-01e75843f47d
        created_at:
          type: string
          format: date-time
          example: '2021-03-16T18:38:01.942282Z'
          description: 'Format: 2020-01-01T01:01:01Z'
        updated_at:
          type: string
          format: date-time
          example: '2021-03-16T18:38:01.942282Z'
          description: 'Format: 2020-01-01T01:01:01Z'
        account_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - QUEUED
          - SENT_TO_CLEARING
          - APPROVED
          - CANCELED
          description: QUEUED, SENT_TO_CLEARING, APPROVED, CANCELED
        name:
          type: string
          description: Name of recipient bank
        bank_code:
          type: string
          description: 9-Digit ABA RTN (Routing Number) or BIC
        bank_code_type:
          type: string
          enum:
          - ABA
          - BIC
          description: ABA (Domestic) or BIC (International)
        country:
          type: string
          description: Only for international banks
        state_province:
          type: string
          description: Only for international banks
        postal_code:
          type: string
          description: Only for international banks
        city:
          type: string
          description: Only for international banks
        street_address:
          type: string
          description: Only for international banks
        account_number:
          type: string
      required:
      - id
      - created_at
      - updated_at
      - name
      - bank_code
      - bank_code_type
      - account_number
    CreateTransferRequest:
      title: CreateTransferRequest
      type: object
      properties:
        transfer_type:
          $ref: '#/components/schemas/TransferType'
        relationship_id:
          type: string
          format: uuid
          description: 'Required if type = `ach`


            The ach_relationship created for the account_id [here](https://alpaca.markets/docs/api-references/broker-api/funding/ach/#creating-an-ach-relationship)'
        bank_id:
          type: string
          format: uuid
          description: 'Required if type = `wire`


            The bank_relationship created for the account_id [here](https://alpaca.markets/docs/api-references/broker-api/funding/bank/#creating-a-new-bank-relationship)'
        amount:
          type: string
          format: decimal
          description: Must be > 0.00
        direction:
          $ref: '#/components/schemas/TransferDirection'
        timing:
          $ref: '#/components/schemas/TransferTiming'
        additional_information:
          type: string
          description: Additional details for when type = `wire`
          nullable: true
      required:
      - transfer_type
      - amount
      - direction
      - timing
      description: '[See main docs here](https://alpaca.markets/docs/api-references/broker-api/funding/transfers/#creating-a-transfer-entity)'
    CreateBankRequest:
      title: CreateBankRequest
      type: object
      properties:
        name:
          type: string
          description: Name of recipient bank
        bank_code:
          type: string
          description: 9-Digit ABA RTN (Routing Number) or BIC
        bank_code_type:
          type: string
          enum:
          - ABA
          - BIC
          description: ABA (Domestic) or BIC (International)
        country:
          type: string
          description: Only for international banks
        state_province:
          type: string
          description: Only for international banks
        postal_code:
          type: string
          description: Only for international banks
        city:
          type: string
          description: Only for international banks
        street_address:
          type: string
          description: Only for international banks
        account_number:
          type: string
      required:
      - name
      - bank_code
      - bank_code_type
      - account_number
      description: Represents the possible fields to send when creating a new associated Bank resource for an account
    TransferTiming:
      type: string
      example: immediate
      enum:
      - immediate
      description: 'Only `immediate` is currently supported.


        values:


        - **immediate**


        - **next_day**'
    Error:
      title: Error
      type: object
      properties:
        code:
          type: number
        message:
          type: string
      required:
      - code
      - message
    TransferStatusEvent:
      description: Represents a change in a Transfer's status, sent over the events streaming api.
      type: object
      x-examples:
        example-1:
          account_id: 8e00606a-c9ac-409a-ba45-f55e8f77984a
          at: '2021-06-10T19:52:24.066998Z'
          event_id: 15961
          status_from: QUEUED
          status_to: SENT_TO_CLEARING
          transfer_id: c4ed4206-697b-4859-ab71-b9de6649859d
        example-2:
          account_id: 8e00606a-c9ac-409a-ba45-f55e8f77984a
          at: '2021-06-10T20:02:24.280178Z'
          event_id: 15962
          status_from: SENT_TO_CLEARING
          status_to: COMPLETE
          transfer_id: c4ed4206-697b-4859-ab71-b9de6649859d
      title: TransferStatusEvent
      properties:
        account_id:
          type: string
          minLength: 1
          description: Account UUID
          format: uuid
        at:
          type: string
          minLength: 1
          description: Timedate of when the transfer status changed
          format: date-time
        event_id:
          type: integer
          description: Monotonically increasing 64bit integer
        status_from:
          $ref: '#/components/schemas/TransferStatus'
        status_to:
          $ref: '#/components/schemas/TransferStatus'
        transfer_id:
          type: string
          minLength: 1
          description: Transfer UUID
          format: uuid
      required:
      - account_id
      - at
      - event_id
      - status_from
      - status_to
      - transfer_id
  responses:
    BadRequest:
      description: Malformed input.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotAuthorized:
      description: Client is not authorized for this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    AccountID:
      name: account_id
      in: path
      required: true
      description: Account identifier.
      schema:
        type: string
        format: uuid
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic