WebSocket and SSE

WebSocket

Connect to:

ws://127.0.0.1:8787/api/ws
ws://127.0.0.1:8787/api/ws?launch=0x...

The server immediately sends:

{
  "type": "snapshot",
  "data": { "summary": {}, "launch": "0x... or null" },
  "meta": { "chainId": 11155111, "stale": false }
}

Later protocol notifications use:

{
  "type": "activity",
  "data": {
    "event": { "eventName": "RoundCommitted", "txHash": "0x..." },
    "meta": { "chainId": 11155111, "stale": false }
  }
}

The server pings clients every 25 seconds and terminates clients that stop replying. Client messages are unsupported and close the connection.

SSE

Connect to /api/stream with the same optional launch filter. The stream sends an initial snapshot event, activity events, and comment heartbeats every 25 seconds.

No replay guarantee

WebSocket and SSE are notifications, not durable event logs. A client can miss messages while disconnected or backgrounded. Correct client behavior is:

1. load full REST state on first render;
2. establish the realtime channel;
3. on a notification, coalesce a REST refresh;
4. after reconnect, fetch REST again;
5. when a hidden tab becomes visible, fetch REST again; and
6. retain low-frequency API safety refreshes for time-derived phase boundaries.

Those safety refreshes call the D17 API in API mode. They do not poll Ethereum from the browser.

Event policy

Default public ingestion excludes Swap, Sync, Transfer, and Approval; pair contracts are not watched by default. D17 lifecycle events, official pool creation, vault settlement, and late-liquidity events remain.

includeNoisyEvents=1 (or includeMarketEvents=1) only affects event types retained but silent-by-default in a profile that permits them. It cannot expose event families excluded at ingestion.