/sse-events

name: alpaca-broker-sse-events
description: Consume Alpaca Broker API real-time event streams over Server-Sent Events (SSE) — account status, journal, transfer/funding, trade, and non-trade-activity events — reliably. Covers connection, auth, replay cursors (since / since_id / since_ulid), heartbeat and comment lines, reconnection/backoff, ordering, and idempotent processing. Use when building an event consumer for Alpaca lifecycle events in any language.

Alpaca Broker API — Real-Time Events (SSE)

Alpaca pushes brokerage lifecycle events over **Server-Sent Events**: a long-lived HTTP GET that streams `text/event-stream`. This is *not* the market-data WebSocket (`alpaca-broker-market-data`) — different transport, different auth, different reliability model.

> Read `alpaca-broker-integration` first for base URLs and auth (client-credentials Bearer token; legacy Basic still works).

Reference

• Guide: `https://docs.alpaca.markets/docs/sse-events`
• Live: `alpaca-docs` MCP → `search` "SSE Events", then `fetch us/sse-events`

1. Why SSE (and why it's simpler than it looks)

SSE is plain HTTP. You don't need a special client: open a GET, keep the connection open, and read the body line-by-line. Each event is a `data:` line containing a JSON object. It is **replayable** — you can ask for events from a point in the past and seamlessly catch up to live, which makes it far better than naive polling for lifecycle state.

2. Event streams

| Stream | Path | Carries | |--------|------|---------| | Account status | `GET /v1/events/accounts/status` | Account-property changes: `status`/`crypto_status` (`SUBMITTED`→`ACTIVE`, `ACTION_REQUIRED`, `REJECTED`), plus `kyc_results`, `account_blocked`, `trading_blocked`, `cash_interest`, `options` | | Journal status | `GET /v2/events/journals/status` | JNLC/JNLS lifecycle (`queued`→`executed`, `correct`…) | | Funding/transfer status | `GET /v2/events/funding/status` | Unified: `Transfer`, `BankRelationship`, `WireBank`, `FundingWallet` entities (switch on `entity_type`) | | Trade updates | `GET /v2/events/trades` | Order events in the `event` field: `new`, `fill`, `partial_fill`, `canceled`, `rejected`, `held`, `trade_bust`, `trade_correct`… (richer than order `status`) | | Activities | `GET /v2beta1/events/activities` | Every financial activity in one stream: fills, corporate actions, fees, journals, transfers. `activity_type` (`TRD` = trade fill) + `activity_subtype` + a `details` object; ULID `event_id`, UUID `ref_id` | | Non-trade activities (legacy) | `GET /v1/events/nta` | Dividends, interest, fees, splits, ACATs, cash disbursements. `entry_type` e.g. `JNLC`/`FEE`/`INT`/`DIVNRA`/`CSD`; `status` ∈ `executed`/`correct`/`canceled` |

> **Paths & versions are NOT uniform — verify each.** This is exactly the kind of cross-stream inconsistency Alpaca's docs under-communicate: > - **The Activity SSE fully replaces `/v1/events/nta` and `GET /v1/accounts/activities`** for activities booked after **2026-02-11**; older history still needs the REST endpoint. New partners should not use the legacy endpoints. It does **not** replace `/v2/events/trades`: fills, corrections and busts appear on both, but non-fill lifecycle events (`accepted`, `canceled`, `expired`, `replaced`) are not activities and never appear on it. > - **`/v1/events/trades` is gone** (fully deprecated, no longer available). `/v1/events/journals/status` is legacy — migrate to `/v2`. > - **`/v1`** events carry an integer `event_id` *and* a ULID `event_ulid`; **`/v2`/`/v2beta1`** carry a ULID `event_id`. §4 says which cursor to pass. > > Field shapes differ per stream — there is no universal envelope. Check each schema.

3. Connection

GET /v2/events/journals/status?since_id=<last-ulid-you-saw> HTTP/1.1
Host: broker-api.alpaca.markets
Authorization: Bearer <access-token>
Accept: text/event-stream

`Authorization: Basic <base64(key:secret)>` also works. Nothing documents whether an open stream survives token expiry, so treat a mid-stream `401` as just another drop and reconnect with your cursor.

Read the response stream and parse `data: {…}` frames as they arrive. In most languages an off-the-shelf EventSource/SSE client works — **just make sure it lets you set the `Authorization` header** on the initial request (the browser `EventSource` API famously does *not*; use a server-side SSE library instead).

4. Replay cursors — the feature that prevents data loss

Every stream supports point-in-time replay:

| Param | Meaning | |-------|---------| | `since` / `until` | RFC3339 or `YYYY-MM-DD` timestamps (date-only on some `/v1` streams). **URL-encode `+`** in offsets as `%2B`. | | `since_id` / `until_id` | **v2 / v2beta1 streams — ULID values.** On `/v1/events/*` these are the *legacy integer* cursors: available only to select broker partners and sunset **2027-02-15**. Don't build on them. | | `since_ulid` / `until_ulid` | **v1 streams** (accounts/status, nta, and the legacy `/v1` journals stream) — the ULID cursors, available to all partners. Use these on v1; they don't exist on v2. |

Rules: `since` is required if `until` is set; `since_id` required if `until_id` set (same for `since_ulid`/`until_ulid`); you **can't mix** `since`, `since_id`, and `since_ulid`. On `/v2beta1/events/activities` the dependency flips: **`since` requires `until`**, and only `since_id` can be left open-ended for live tailing. **Without any since cursor, no history is returned** — you only get live pushes from now on. Reaching the `until` bound ends the stream with a `200`.

**This is the single most important reliability lesson:** persist the ID of the last event you *successfully processed*. On every (re)connect, pass it as your since cursor — **`since_id` on v2/v2beta1, `since_ulid` on v1** — so Alpaca replays anything you missed during the gap. A consumer that reconnects **without** a cursor silently drops every event that occurred while it was down.

5. Ordering caveat

Within a millisecon