# SSE Events

> Subscribe to MyStocks Server-Sent Events for order, wallet, KYC, dividend, market, and incident updates.

`GET /stream` is a Server-Sent Events feed for partner-facing state changes. Use it for live application updates; use signed webhooks for durable server-to-server processing and reconciliation.

## Connect

The stream uses the same partner base URL and authentication model as REST:

```javascript
const source = new EventSource(
  'https://mystocks.africa/api/v1/partner/stream?access_token=ms_oauth_<short-lived-token>'
);

const receive = (message) => {
  const event = JSON.parse(message.data);
  // Persist the business identity when processing; the cursor only tracks replay position.
  console.log(event.eventId ?? event.id, event.event, event.data, message.lastEventId);
};
const businessEvents = ["order.pending", "order.triggered", "order.filled", "order.rejected", "order.cancelled", "order.replaced", "trade.settled", "trade.rejected", "deposit.confirmed", "withdraw.confirmed", "wallet.credited", "wallet.converted", "wallet.transferred", "wallet.policy.updated", "topup.confirmed", "payout.processed", "credit_limit.approved", "float.low", "kyc.updated", "account.frozen", "account.closed", "dividend.paid", "corporateaction.declared", "corporateaction.split", "corporateaction.suspension", "corporateaction.delisting", "corporateaction.rights_issue", "corporateaction.symbol_changed", "quote.expired", "price.alert", "market.status", "incident.declared", "incident.resolved"];
for (const name of businessEvents) source.addEventListener(name, receive);
source.addEventListener('stream_gap', (message) => {
  source.close();
  console.warn('Reconcile REST state before reconnecting:', JSON.parse(message.data));
});
source.addEventListener('stream_timeout', () => console.log('Expected reconnect; preserve the last cursor.'));

```

Use a backend proxy for customer browsers; never expose an organization-wide trading credential as a customer session. A short-lived token is still a partner credential and must be scoped appropriately to its consumer. Refresh expired credentials on your backend and recreate the stream with the persisted cursor. For server clients, send the normal `Authorization: Bearer` header.

## Resume and reconnect

Each frame carries an opaque `timestamp:documentId` stream cursor so events sharing a timestamp remain replayable. Legacy millisecond cursors are accepted. Persist the last `id:` value and reconnect with `Last-Event-ID` or `?since=` after a network interruption. The connection may close after approximately 110 seconds; reconnect is expected. Heartbeat comments are sent periodically and should reset your idle timer.

```text
id: 1842:document_42
event: order.filled
data: {"id":"document_42","eventId":"evt_42","ts":1842,"event":"order.filled","data":{...}}
```

Replay is limited to the **last hour**. An older, invalid or future cursor produces a named `stream_gap` control frame with `replayComplete: false`. Reconcile current orders, transactions and holdings plus webhook delivery records before reconnecting. The stream is not an unlimited event archive.

## Delivery semantics

- Events are at-least-once and can be duplicated.
- Events can arrive out of order; derive state from the event payload and current REST state.
- New frames include the same business `eventId` used by signed webhook delivery. Keep legacy `id` as a compatibility storage identifier. Older records without a business ID fall back to `id`; cross-channel deduplication cannot be assumed for those legacy records. Deduplicate business events durably, not by cursor alone.
- SSE is not a tick-by-tick market-price stream.
- A stream reconnect does not replace daily reconciliation.

The same business events can be delivered through [signed webhooks](/partners/docs/webhooks). See [Trading lifecycles](/partners/docs/lifecycles) for order transitions and [Daily Reconciliation](/partners/docs/daily-reconciliation) for the durable operating record.
