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