Alpaca Events API
The Events API from Alpaca — 4 operation(s) for events.
OpenAPI Specification
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