Alpaca Broker API provides replayable and real-time event streams via Server-Sent Event (SSE). The SSE protocol is a simple yet powerful protocol to satisfy a lot of your needs to build flawless user experience. Each endpoint can be queried by the event timestamp or monotonically incremental integer ID to seamlessly subscribe from the past point-in-time event to the real-time pushes with a simple HTTP request. While all SSE endpoints follow the same JSON object model as other REST endpoints, SSE protocol is a lightweight addition on top of the basic HTTP protocol which is a bit different from REST protocol. Please make sure your client program handles the SSE protocol correctly.

Why Use SSE?

Low Latency: Receive updates in real-time for timely decisions about your customers
Resource Efficiency: A single connection serves multiple updates and streamlines where you receive updates about your customers
Simplicity: Integration requires fewer lines of code compared to WebSockets.

Best Practices

Connection Health: Implement heartbeat checks.
Error Recovery: Code for auto-reconnection.
Selective Listening: Subscribe to specific event types relevant to your use case.

🛠️
Note about /v1 and /v2beta1
We are in the process of switching from integer IDs to ULIDs for our Events Streaming. ULIDs are designed to be lexicographically sortable, thanks to their structure that encodes a timestamp. This allows you to better sort and filter records based on when they occured. While they are more complex to read than integer IDs, they contain more information.
Currently only Admin Action Events and Trade Events leverage ULIDs, and over the next months we will be migrating the rest. Check back here to know which SSEs are on the new endpoint.
What Should You Do?
Legacy Events that still use an integer ID and have now an additional field called since_ulid and until_ulid. We highly recommend that you use those today so that you don't face any issues when we will eventually migrate the remaining events (account status, journal status, transfer status, trade status and non-trade-activity notifications) and deprecate the old ones.

Types of SSE Events

Account Status Events

Stay abreast of changes to account statuses. Learn more here.

You can find some sample responses below:

{
    "account_blocked": false,
    "account_id": "9ab15e44-569c-4c32-952c-b83ab7076549",
    "account_number": "",
    "admin_configurations": {
        "allow_instant_ach": true,
        "disable_shorting": true
    },
    "at": "2023-10-13T13:34:28.30629Z",
    "crypto_status_from": "",
    "crypto_status_to": "APPROVED",
    "event_id": 12627517,
    "event_ulid": "01HCMKXQYJ3ZBV66Q21KCT1CRR",
    "pattern_day_trader": false,
    "status_from": "",
    "status_to": "APPROVED",
    "trading_blocked": false
}

{
    "account_id": "50333df9-66f0-46b9-a083-4212b152f749",
    "account_number": "307137914",
    "at": "2023-10-13T13:34:29.668043Z",
    "event_id": 12627518,
    "event_ulid": "01HCMKXS94ST351NFGEZR57EHV",
    "status_from": "APPROVED",
    "status_to": "ACTIVE"
}

:heartbeat

{
    "account_id": "9ab15e44-569c-4c32-952c-b83ab7076549",
    "account_number": "307645030",
    "at": "2023-10-13T13:35:18.145917Z",
    "crypto_status_from": "APPROVED",
    "crypto_status_to": "ACTIVE",
    "event_id": 12627519,
    "event_ulid": "01HCMKZ8M2XPNC9Y8HE159P2WK",
    "status_from": "APPROVED",
    "status_to": "APPROVED"
}

:heartbeat

{
    "account_id": "9ab15e44-569c-4c32-952c-b83ab7076549",
    "account_number": "307645030",
    "at": "2023-10-13T13:40:17.417798Z",
    "event_id": 12627521,
    "event_ulid": "01HCMM8CWAQETWNM75VJKA0YX2",
    "status_from": "APPROVED",
    "status_to": "ACTIVE"
}

{
    "account_blocked": false,
    "account_id": "d16f0c84-2bcc-4caf-bd68-a97889986d74",
    "account_number": "",
    "admin_configurations": {
        "allow_instant_ach": true,
        "disable_shorting": true
    },
    "at": "2023-10-13T13:18:16.936397Z",
    "crypto_status_from": "",
    "crypto_status_to": "INACTIVE",
    "event_id": 12627496,
    "event_ulid": "01HCMK03B8JV4YDB8W2HZ0K6V2",
    "pattern_day_trader": false,
    "status_from": "",
    "status_to": "APPROVED",
    "trading_blocked": false
}

{
    "account_id": "d16f0c84-2bcc-4caf-bd68-a97889986d74",
    "account_number": "307781498",
    "at": "2023-10-13T13:18:18.472537Z",
    "event_id": 12627497,
    "event_ulid": "01HCMK04V979EMCGB96Z6T0H00",
    "status_from": "APPROVED",
    "status_to": "ACTIVE"
}

Journal Events

Stay notified on the status of journal transactions to make sure they have been executed and the cash has been moved from one account to another. More details here.

You can find a sample response below:

{
    "at": "2023-10-13T13:11:10.57913Z",
    "entry_type": "JNLC",
    "event_id": 11751531,
    "event_ulid": "01HCMJK2ZKCPTYXMJYS66T0QJJ",
    "journal_id": "ddd26344-86af-4ba7-ae6a-bcec63129808",
    "status_from": "",
    "status_to": "queued"
}

{
    "at": "2023-10-13T13:11:10.634443Z",
    "entry_type": "JNLC",
    "event_id": 11751532,
    "event_ulid": "01HCMJK31AVBME4WNSH3C8E4HJ",
    "journal_id": "ddd26344-86af-4ba7-ae6a-bcec63129808",
    "status_from": "queued",
    "status_to": "sent_to_clearing"
}

{
    "at": "2023-10-13T13:11:10.67241Z",
    "entry_type": "JNLC",
    "event_id": 11751533,
    "event_ulid": "01HCMJK32GSBH2QG92TKZKDRRV",
    "journal_id": "ddd26344-86af-4ba7-ae6a-bcec63129808",
    "status_from": "sent_to_clearing",
    "status_to": "executed"
}

Transfer Events

Be notified instantly when the statuses of deposits and withdrawals are updated. Read further here.

You can find a sample response below:

{
  "account_id":"8e00606a-c9ac-409a-ba45-f55e8f77984a",
  "at":"2021-06-10T19:49:12.579109Z",
  "event_id":15960,
  "status_from":"",
  "status_to":"queued",
  "transfer_id":"c4ed4206-697b-4859-ab71-b9de6649859d"
}


{
  "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"
}

{
  "account_id":"8e00606a-c9ac-409a-ba45-f55e8f77984a",
  "at":"2021-06-10T20:02:24.280178Z",
  "event_id":15962,
  "status_from":"sent_to_clearing",
  "status_to":"executed",
  "transfer_id":"c4ed4206-697b-4859-ab71-b9de6649859d"
}

Trade Events

Keep tabs on the status of orders, trades, and executions in real-time. Documentation here.

{
    "account_id": "aa4439c3-cf7d-4251-8689-a575a169d6d3",
    "at": "2023-10-13T13:28:58.387652Z",
    "event_id": "01HCMKKNRK7S5C1JYP50QGDECQ",
    "event": "new",
    "timestamp": "2023-10-13T13:28:58.37957033Z",
    "order": {
        "id": "bb2403bc-88ec-430b-b41c-f9ee80c8f0e1",
        "client_order_id": "508789e5-cea3-4235-b546-6c62ff92bd79",
        "created_at": "2023-10-13T13:28:58.361530031Z",
        "updated_at": "2023-10-13T13:28:58.386058029Z",
        "submitted_at": "2023-10-13T13:28:58.360070731Z",
        "filled_at": null,
        "expired_at": null,
        "cancel_requested_at": null,
        "canceled_at": null,
        "failed_at": null,
        "replaced_at": null,
        "replaced_by": null,
        "replaces": null,
        "asset_id": "b0b6dd9d-8b9b-48a9-ba46-b9d54906e415",
        "symbol": "AAPL",
        "asset_class": "us_equity",
        "notional": "10",
        "qty": null,
        "filled_qty": "0",
        "filled_avg_price": null,
        "order_class": "",
        "order_type": "market",
        "type": "market",
        "side": "buy",
        "time_in_force": "day",
        "limit_price": null,
        "stop_price": null,
        "status": "new",
        "extended_hours": false,
        "legs": null,
        "trail_percent": null,
        "trail_price": null,
        "hwm": null,
        "commission": "0"
    },
    "execution_id": "7922ab44-5b33-4049-ab9a-0cfd805ba989"
}

:heartbeat

{
    "account_id": "aa4439c3-cf7d-4251-8689-a575a169d6d3",
    "at": "2023-10-13T13:30:00.664778Z",
    "event_id": "01HCMKNJJRJ4E3RNFA1XR8CX7R",
    "event": "fill",
    "timestamp": "2023-10-13T13:30:00.658443088Z",
    "order": {
        "id": "db04069d-2e5a-48d4-a42f-6a0dea8ea0b8",
        "client_order_id": "be139e2d-8153-4ae8-83ee-7b98b4e17419",
        "created_at": "2023-10-13T13:22:21.887914Z",
        "updated_at": "2023-10-13T13:30:00.661902331Z",
        "submitted_at": "2023-10-13T13:23:05.411141Z",
        "filled_at": "2023-10-13T13:30:00.658443088Z",
        "expired_at": null,
        "cancel_requested_at": null,
        "canceled_at": null,
        "failed_at": null,
        "replaced_at": null,
        "replaced_by": null,
        "replaces": null,
        "asset_id": "b0b6dd9d-8b9b-48a9-ba46-b9d54906e415",
        "symbol": "AAPL",
        "asset_class": "us_equity",
        "notional": "10",
        "qty": null,
        "filled_qty": "0.05513895",
        "filled_avg_price": "181.36",
        "order_class": "",
        "order_type": "market",
        "type": "market",
        "side": "buy",
        "time_in_force": "day",
        "limit_price": null,
        "stop_price": null,
        "status": "filled",
        "extended_hours": false,
        "legs": null,
        "trail_percent": null,
        "trail_price": null,
        "hwm": null,
        "commission": "0"
    },
    "price": "181.36",
    "qty": "0.05513895",
    "position_qty": "0.05513895",
    "execution_id": "a958bb42-b034-4d17-bf07-805cf0820ffe"
}

{
    "account_id": "aa4439c3-cf7d-4251-8689-a575a169d6d3",
    "at": "2023-10-13T13:30:00.673857Z",
    "event_id": "01HCMKNJK1Y0R7VF6Q6CAC3SH7",
    "event": "fill",
    "timestamp": "2023-10-13T13:30:00.658388668Z",
    "order": {
        "id": "bb2403bc-88ec-430b-b41c-f9ee80c8f0e1",
        "client_order_id": "508789e5-cea3-4235-b546-6c62ff92bd79",
        "created_at": "2023-10-13T13:28:58.361530031Z",
        "updated_at": "2023-10-13T13:30:00.665807961Z",
        "submitted_at": "2023-10-13T13:28:58.360070731Z",
        "filled_at": "2023-10-13T13:30:00.658388668Z",
        "expired_at": null,
        "cancel_requested_at": null,
        "canceled_at": null,
        "failed_at": null,
        "replaced_at": null,
        "replaced_by": null,
        "replaces": null,
        "asset_id": "b0b6dd9d-8b9b-48a9-ba46-b9d54906e415",
        "symbol": "AAPL",
        "asset_class": "us_equity",
        "notional": "10",
        "qty": null,
        "filled_qty": "0.05513895",
        "filled_avg_price": "181.36",
        "order_class": "",
        "order_type": "market",
        "type": "market",
        "side": "buy",
        "time_in_force": "day",
        "limit_price": null,
        "stop_price": null,
        "status": "filled",
        "extended_hours": false,
        "legs": null,
        "trail_percent": null,
        "trail_price": null,
        "hwm": null,
        "commission": "0"
    },
    "price": "181.36",
    "qty": "0.05513895",
    "position_qty": "0.1102779",
    "execution_id": "33cbb614-bfc0-468b-b4d0-ccf08588ef77"
}

{
    "account_id": "aa4439c3-cf7d-4251-8689-a575a169d6d3",
    "at": "2023-10-13T13:22:21.927554Z",
    "event": "accepted",
    "event_id": 10676063,
    "event_ulid": "01HCMK7JJ3EJD9P4JSM1M0HTZ0",
    "order": {
        "asset_class": "us_equity",
        "asset_id": "b0b6dd9d-8b9b-48a9-ba46-b9d54906e415",
        "cancel_requested_at": null,
        "canceled_at": null,
        "client_order_id": "be139e2d-8153-4ae8-83ee-7b98b4e17419",
        "commission": "0",
        "created_at": "2023-10-13T09:22:21.887913787-04:00",
        "expired_at": null,
        "extended_hours": false,
        "failed_at": null,
        "filled_at": null,
        "filled_avg_price": null,
        "filled_qty": "0",
        "hwm": null,
        "id": "db04069d-2e5a-48d4-a42f-6a0dea8ea0b8",
        "legs": null,
        "limit_price": null,
        "notional": "10",
        "order_class": "",
        "order_type": "market",
        "qty": null,
        "replaced_at": null,
        "replaced_by": null,
        "replaces": null,
        "side": "buy",
        "status": "accepted",
        "stop_price": null,
        "submitted_at": "2023-10-13T09:22:21.886066537-04:00",
        "symbol": "AAPL",
        "time_in_force": "day",
        "trail_percent": null,
        "trail_price": null,
        "type": "market",
        "updated_at": "2023-10-13T09:22:21.887913787-04:00"
    },
    "timestamp": "2023-10-13T09:22:21.888053477-04:00"
}

:heartbeat

{
    "account_id": "aa4439c3-cf7d-4251-8689-a575a169d6d3",
    "at": "2023-10-13T13:30:01.118487Z",
    "event": "fill",
    "event_id": 10676567,
    "event_ulid": "01HCMKNJJRJ4E3RNFA1XR8CX7R",
    "execution_id": "a958bb42-b034-4d17-bf07-805cf0820ffe",
    "order": {
        "asset_class": "us_equity",
        "asset_id": "b0b6dd9d-8b9b-48a9-ba46-b9d54906e415",
        "cancel_requested_at": null,
        "canceled_at": null,
        "client_order_id": "be139e2d-8153-4ae8-83ee-7b98b4e17419",
        "commission": "0",
        "created_at": "2023-10-13T13:22:21.887914Z",
        "expired_at": null,
        "extended_hours": false,
        "failed_at": null,
        "filled_at": "2023-10-13T13:30:00.658443088Z",
        "filled_avg_price": "181.36",
        "filled_qty": "0.05513895",
        "hwm": null,
        "id": "db04069d-2e5a-48d4-a42f-6a0dea8ea0b8",
        "legs": null,
        "limit_price": null,
        "notional": "10",
        "order_class": "",
        "order_type": "market",
        "qty": null,
        "replaced_at": null,
        "replaced_by": null,
        "replaces": null,
        "side": "buy",
        "status": "filled",
        "stop_price": null,
        "submitted_at": "2023-10-13T13:23:05.411141Z",
        "symbol": "AAPL",
        "time_in_force": "day",
        "trail_percent": null,
        "trail_price": null,
        "type": "market",
        "updated_at": "2023-10-13T09:30:00.661902331-04:00"
    },
    "position_qty": "0.05513895",
    "price": "181.36",
    "qty": "0.05513895",
    "timestamp": "2023-10-13T13:30:00.658443088Z"
}

{
    "account_id": "aa4439c3-cf7d-4251-8689-a575a169d6d3",
    "at": "2023-10-13T13:30:02.667443Z",
    "event": "fill",
    "event_id": 10676601,
    "event_ulid": "01HCMKNJK1Y0R7VF6Q6CAC3SH7",
    "execution_id": "33cbb614-bfc0-468b-b4d0-ccf08588ef77",
    "order": {
        "asset_class": "us_equity",
        "asset_id": "b0b6dd9d-8b9b-48a9-ba46-b9d54906e415",
        "cancel_requested_at": null,
        "canceled_at": null,
        "client_order_id": "508789e5-cea3-4235-b546-6c62ff92bd79",
        "commission": "0",
        "created_at": "2023-10-13T09:28:58.361530031-04:00",
        "expired_at": null,
        "extended_hours": false,
        "failed_at": null,
        "filled_at": "2023-10-13T13:30:00.658388668Z",
        "filled_avg_price": "181.36",
        "filled_qty": "0.05513895",
        "hwm": null,
        "id": "bb2403bc-88ec-430b-b41c-f9ee80c8f0e1",
        "legs": null,
        "limit_price": null,
        "notional": "10",
        "order_class": "",
        "order_type": "market",
        "qty": null,
        "replaced_at": null,
        "replaced_by": null,
        "replaces": null,
        "side": "buy",
        "status": "filled",
        "stop_price": null,
        "submitted_at": "2023-10-13T09:28:58.360070731-04:00",
        "symbol": "AAPL",
        "time_in_force": "day",
        "trail_percent": null,
        "trail_price": null,
        "type": "market",
        "updated_at": "2023-10-13T09:30:00.665807961-04:00"
    },
    "position_qty": "0.1102779",
    "price": "181.36",
    "qty": "0.05513895",
    "timestamp": "2023-10-13T13:30:00.658388668Z"
}

Message Ordering

For the messages received on the SSE stream we guarantee that the order of the received events is the same as the order they were happening on a per account basis.

Example: if event E1 has been received earlier then another event E2 for the same account, then E1 happened before E2 according to our bookkeeping.

We do not have this guarantee across accounts: if two events for different accounts are received it is the consumer’s responsibility to decide which event happened first based on the timestamp/ulid fields of the event.

Example: E1 happened for account A1 before E2 which was affecting A2. The streaming endpoint might return the events in E1, E2 or E2, E1 ordering. Both responses should be considered valid.

Note: since ULIDs contain a random part other events might have arrived in the same millisecond as the last event received being lexiographicly less than the previous event.

If the stream is used for recon purposes, we recommend to restart the stream from a since that is a few mintues before the time of latest event received.

This approach means that the consumer will receive some events twice when restarting a stream: it is the consumer’s responsibility to process the recevied messages in an idempotent manner so that duplicate messages get ignored on the consumer side.

Note: since and until parameters are parsing as RFC3339 where timezone can be specified (e.g 2006-01-02T15:04:05+07:00), however plus sign character (+) is a special character in HTTP, so use the URL encoded version instead, e.g. ...events/trades?since=2006-01-02T15:04:05%2B07:00

Admin Action Events

These events pertain to administrative actions like account suspensions and liquidations performed by Alpaca Administrators. See more here.

[
  {
    "event_id": "01GTVS4FVS2KJDTPYH2WM6NAXF",
    "at": "2023-09-21T10:52:38.429059991Z",
    "note": "Status changed to REJECTED.", 
    "type": "legacy_note_admin_event", 
    "context": {}, 
    "category": "other", 
    "event_id": "03HBVNXKMWYGFTKTGNVR5R41F2", 
    "correspondent": "ABCD", 
    "belongs_to_kind": "account", 
    "created_by_kind": "admin", 
    "belongs_to_id_reference": "b4fe44b0-e51c-48f4-b674-990bea6cf8d7", 
    "created_by_id_reference": "f0e150df-94ad-48f9-8b0f-05433a3b53c3"
  }
]

Non-Trade Activities Events

Covering non-trade activities like dividends, stock splits, and other corporate actions. Read more here.