openapi: 3.0.0 info: title: Broker Account Activities Events 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: Events paths: /v1/events/accounts/status: get: summary: Subscribe to account status events (SSE). tags: - Events description: 'Events API provide event push as well as historical queries via SSE (server sent events). 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. ' parameters: - name: since in: query schema: type: string format: date description: 'Format: YYYY-MM-DD' - name: until in: query schema: type: string format: date description: 'Format: YYYY-MM-DD' - name: since_id in: query schema: type: integer - name: until_id in: query schema: type: integer 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/AccountStatusEvent' examples: {} operationId: suscribeToAccountStatusSSE /v1/events/journals/status: get: summary: Subscribe to journal events (SSE). tags: - Events description: 'The Events API provides event push as well as historical queries via SSE (server sent events). You can listen to journal status updates as they get processed by our backoffice. 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.' 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 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/JournalStatusEvent' operationId: subscribeToJournalStatusSSE /v1/events/transfers/status: parameters: [] get: summary: Subscribe to Transfer Events (SSE) tags: - Events 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.' /v1/events/trades: parameters: [] get: summary: Subscribe to Trade Events (SSE) tags: - Events 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/TradeUpdateEvent' 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: subscribeToTradeSSE description: 'The Events API provides event push as well as historical queries via SSE (server sent events). You can listen to events related to trade updates. Most market trades sent during market hours are filled instantly; you can listen to limit order updates through this endpoint. 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: JournalEntryType: type: string title: '' description: "This enum represents the various kinds of Journal alpaca supports.\n\nCurrent values are:\n\n- **JNLC**\n\n Journal Cash between accounts\n\n- **JNLS**\n\n Journal Securities between accounts" enum: - JNLC - JNLS 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. ' AccountStatusEvent: description: 'Represents a change in an Account''s status, sent over the events streaming api. For partners who utilize Alpaca’s KYC service for opening brokerage accounts an additional `kyc_results` object is represented in the account status update events.' type: object x-examples: example-1: account_id: 4db36989-6565-4011-9126-39fe6b3d9bf6 account_number: '' at: '2021-06-14T09:59:15.232782Z' event_id: 122039 kyc_results: null status_from: '' status_to: APPROVED title: AccountStatusEvent properties: account_id: type: string minLength: 1 account_number: type: string minLength: 1 status_from: $ref: '#/components/schemas/AccountStatus' status_to: $ref: '#/components/schemas/AccountStatus' reason: type: string minLength: 1 description: Optional at: type: string minLength: 1 description: Timestamp of event kyc_result: $ref: '#/components/schemas/KYCResult' event_id: type: integer description: monotonically increasing 64bit integer required: - account_id - account_number - status_from - status_to - reason - at - event_id OrderType: type: string enum: - market - limit - stop - stop_limit - trailing_stop example: stop TimeInForce: type: string enum: - day - gtc - opg - cls - ioc - fok example: gtc TradeUpdateEventType: type: string description: "**Common events**\n\nThese are the events that are the expected results of actions you may have taken by sending API requests.\n\nThe meaning of the `timestamp` field changes for each type; the meanings have been specified here for which types the\ntimestamp field will be present.\n\n- `new`: Sent when an order has been routed to exchanges for execution.\n- `fill`: Sent when your order has been completely filled.\n - `timestamp`: The time at which the order was filled.\n- `partial_fill`: Sent when a number of shares less than the total remaining quantity on your order has been filled.\n - `timestamp`: The time at which the shares were filled.\n- `canceled`: Sent when your requested cancellation of an order is processed.\n - `timestamp`: The time at which the order was canceled.\n- `expired`: Sent when an order has reached the end of its lifespan, as determined by the order’s time in force value.\n - `timestamp`: The time at which the order expired.\n- `done_for_day`: Sent when the order is done executing for the day, and will not receive further updates until the next trading day.\n- `replaced`: Sent when your requested replacement of an order is processed.\n - `timestamp`: The time at which the order was replaced.\n\n**Rarer events**\n\nThese are events that may rarely be sent due to unexpected circumstances on the exchanges. It is unlikely you will need to design your code around them, but you may still wish to account for the possibility that they will occur.\n\n- `rejected`: Sent when your order has been rejected.\n - `timestamp`: The time at which the rejection occurred.\n- `pending_new`: Sent when the order has been received by Alpaca and routed to the exchanges, but has not yet been accepted for execution.\n- `stopped`: Sent when your order has been stopped, and a trade is guaranteed for the order, usually at a stated price or better, but has not yet occurred.\n- `pending_cancel`: Sent when the order is awaiting cancellation. Most cancellations will occur without the order entering this state.\n- `pending_replace`: Sent when the order is awaiting replacement.\n- `calculated`: Sent when the order has been completed for the day - it is either `filled` or `done_for_day` - but remaining settlement calculations are still pending.\n- `suspended`: Sent when the order has been suspended and is not eligible for trading.\n- `order_replace_rejected`: Sent when the order replace has been rejected.\n- `order_cancel_rejected`: Sent when the order cancel has been rejected.\n" enum: - new - fill - partial_fill - canceled - expired - done_for_day - replaced - rejected - pending_new - stopped - pending_cancel - pending_replace - calculated - suspended - order_replace_rejected - order_cancel_rejected JournalStatus: type: string enum: - pending - canceled - executed - queued - rejected - deleted description: "Represents the status that a Journal instance can be in.\n\nCurrent Values:\n - pending\n - canceled\n - executed\n - queued\n - rejected\n - deleted" JournalStatusEvent: description: 'Represents a change in a Journal''s status, sent over the events streaming api. ' type: object x-examples: example-1: at: '2021-05-07T10:28:23.163857Z' entry_type: JNLC event_id: 1406 journal_id: 2f144d2a-91e6-46ff-8e37-959a701cc58d status_from: '' status_to: queued title: JournalStatusEvent properties: at: type: string minLength: 1 description: Timestamp of event format: date-time entry_type: $ref: '#/components/schemas/JournalEntryType' event_id: type: integer description: Monotonically increasing 64bit integer journal_id: type: string description: The UUID of the related Journal format: uuid status_from: $ref: '#/components/schemas/JournalStatus' status_to: $ref: '#/components/schemas/JournalStatus' required: - at - entry_type - event_id - journal_id - status_from - status_to Order: type: object properties: id: type: string format: uuid example: 61e69015-8549-4bfd-b9c3-01e75843f47d client_order_id: type: string example: 61e69015-8549-4bfd-b9c3-01e75843f47d created_at: type: string format: date-time example: '2021-03-16T18:38:01.942282Z' updated_at: type: string format: date-time example: '2021-03-16T18:38:01.942282Z' submitted_at: type: string format: date-time example: '2021-03-16T18:38:01.942282Z' filled_at: nullable: true type: string format: date-time example: '2021-03-16T18:38:01.942282Z' expired_at: nullable: true type: string format: date-time example: '2021-03-16T18:38:01.942282Z' canceled_at: nullable: true type: string format: date-time example: '2021-03-16T18:38:01.942282Z' failed_at: nullable: true type: string format: date-time example: '2021-03-16T18:38:01.942282Z' replaced_at: nullable: true type: string format: date-time example: '2021-03-16T18:38:01.942282Z' replaced_by: nullable: true type: string format: uuid example: 61e69015-8549-4bfd-b9c3-01e75843f47d replaces: nullable: true type: string format: uuid example: 61e69015-8549-4bfd-b9c3-01e75843f47d asset_id: type: string format: uuid example: 61e69015-8549-4bfd-b9c3-01e75843f47d symbol: type: string example: AALP asset_class: $ref: '#/components/schemas/AssetClass' notional: nullable: true type: string format: decimal example: '4.2' qty: nullable: true type: string format: decimal example: '4.2' filled_qty: type: string format: decimal example: '4.2' filled_avg_price: nullable: true type: string format: decimal example: '4.2' order_class: $ref: '#/components/schemas/OrderClass' order_type: $ref: '#/components/schemas/OrderType' type: $ref: '#/components/schemas/OrderType' side: $ref: '#/components/schemas/OrderSide' time_in_force: $ref: '#/components/schemas/TimeInForce' limit_price: nullable: true type: string format: decimal example: '3.14' stop_price: nullable: true type: string format: decimal example: '3.14' status: $ref: '#/components/schemas/OrderStatus' extended_hours: type: boolean example: true legs: nullable: true type: array items: $ref: '#/components/schemas/Order' trail_price: nullable: true type: string format: decimal example: '3.14' trail_percent: nullable: true type: string format: decimal example: '5.0' hwm: nullable: true type: string format: decimal example: '3.14' commission: type: string format: decimal example: '3.14' required: - id - symbol AccountStatus: type: string example: ACTIVE enum: - ONBOARDING - SUBMITTED - RESUBMITTED - SUBMISSION_FAILED - ACTION_REQUIRED - EDITED - ACCOUNT_UPDATED - APPROVAL_PENDING - REAPPROVAL_PENDING - SIGNED_UP - KYC_SUBMITTED - LIMITED - AML_REVIEW - APPROVED - REJECTED - ACTIVE - DISABLED - DISABLE_PENDING - ACCOUNT_CLOSED - PAPER_ONLY description: 'Designates the current status of this account Possible Values: - **ONBOARDING** An application is expected for this user, but has not been submitted yet. - **SUBMITTED** The application has been submitted and in process. - **RESUBMITTED** Resubmitted is used to display when request has been re-submitted to Apex after account update - **SUBMISSION_FAILED** Used to display if failure on submission - **ACTION_REQUIRED** The application requires manual action. - **EDITED** Application was edited (e.g. to match info from uploaded docs). This is a transient status. - **ACCOUNT_UPDATED** Used to display when Account has been modified by user - **APPROVAL_PENDING** Initial value. The application approval process is in process. - **REAPPROVAL_PENDING** This is a transient status used to display once apex approves a re-submission - **SIGNED_UP** Users who were directed to and competed the [first stage](https://app.alpaca.markets/signup) of v2 registration - **KYC_SUBMITTED** Users that have had their KYC submitted to the routed KYC Provider - **LIMITED** Limited Users that pass KYC but are missing financial_information and employment_details - **AML_REVIEW** Users that pass KYC but from a restricted/high risk country and need manual AML approval - **APPROVED** The account application has been approved, and waiting to be ACTIVE - **REJECTED** The account application is rejected for some reason - **ACTIVE** The account is fully active. Trading and funding are processed under this status. - **DISABLED** The account is disabled after ACTIVE status. - **DISABLE_PENDING** DisablePending is used for accounts which requested to be disabled, but have not been processed yet. - **ACCOUNT_CLOSED** The account is closed. - **PAPER_ONLY** Used to display when only paper trading is allowed for this account ' 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 TradeUpdateEvent: description: Represents an update to an order/trade, sent over the events streaming api. type: object title: TradeUpdateEvent x-examples: example-1: account_id: 529248ad-c4cc-4a50-bea4-6bfd2953f83a at: '2022-04-19T14:12:30.656741Z' event: new event_id: 37782 execution_id: 7e544af3-3104-4e1a-8cbc-dab2624949ff order: asset_class: us_equity asset_id: a4778bc8-fad1-47b7-87fe-d5cde10d43f4 cancel_requested_at: null canceled_at: null client_order_id: 6d873193-dac6-4f72-8e13-c57853a9339d commission: '1' created_at: '2022-04-19T10:12:30.57117938-04:00' expired_at: null extended_hours: false failed_at: null filled_at: null filled_avg_price: null filled_qty: '0' hwm: null id: edada91a-8b55-4916-a153-8c7a9817e708 legs: null limit_price: '700' notional: null order_class: '' order_type: limit qty: '4' replaced_at: null replaced_by: null replaces: null side: buy status: new stop_price: null submitted_at: '2022-04-19T10:12:30.403135025-04:00' symbol: TSLA time_in_force: day trail_percent: null trail_price: null type: limit updated_at: '2022-04-19T10:12:30.609783218-04:00' timestamp: '2022-04-19T14:12:30.602193534Z' properties: account_id: type: string minLength: 1 description: Account UUID format: uuid at: type: string minLength: 1 description: Timestamp of event format: date-time event: $ref: '#/components/schemas/TradeUpdateEventType' event_id: type: integer format: int64 description: Monotonically increasing 64bit integer execution_id: type: string description: Corresponding execution of an order. If an order gets filled over two executions (a partial_fill for example), you will receive two events with different IDs. format: uuid order: $ref: '#/components/schemas/Order' timestamp: type: string description: 'Has various different meanings depending on the value of `event`, please see the [Trading Events](https://alpaca.markets/docs/api-references/broker-api/events/#trade-events) Enum in the documentation or the TradeUpdateEventType model for more details on when it means different things. ' format: date-time required: - account_id - at - event - event_id - execution_id - order - timestamp AssetClass: type: string enum: - us_equity - crypto OrderStatus: type: string enum: - new - partially_filled - filled - done_for_day - canceled - expired - replaced - pending_cancel - pending_replace - accepted - pending_new - accepted_for_bidding - stopped - rejected - suspended - calculated example: filled OrderClass: type: string enum: - simple - bracket - oco - oto example: bracket OrderSide: type: string enum: - buy - sell - buy_minus - sell_plus - sell_short - sell_short_exempt - undisclosed - cross - cross_short example: buy description: Represents what side of the transaction an order was on. KYCResult: type: object description: Hold information about the result of KYC. Please see the documentation [here](https://alpaca.markets/docs/api-references/broker-api/events/#kyc-results) for more indepth details properties: reject: type: object accept: type: object indeterminate: type: object addidional_information: type: string securitySchemes: BasicAuth: type: http scheme: basic