SSE Streaming

Deep dive into the Server-Sent Events streaming API.

Connection

The Events API uses standard SSE protocol over HTTP/2:

GET /api/stream
Accept: text/event-stream

Event Types

The stream emits different event types:

Event Type	Description
filing	SEC EDGAR filing notification
trade	Form 4 insider trade event
news	RSS news article
heartbeat	Keep-alive ping (every 30s)

Filtering

Filter events by type using query parameters:

// Only receive Form 4 trades
const eventSource = new EventSource('/api/stream?types=trade');

// Multiple types
const eventSource = new EventSource('/api/stream?types=trade,filing');

Reconnection

The SSE protocol handles reconnection automatically. The server sends id fields that the browser uses for resumption:

eventSource.addEventListener('error', (event) => {
  if (eventSource.readyState === EventSource.CONNECTING) {
    console.log('Reconnecting...');
  }
});

Backpressure

If the client falls behind, the server may drop events. Monitor the Last-Event-ID header to detect gaps.

Example: React Hook

import { useEffect, useState } from 'react';

interface Event {
  eventType: string;
  issuer: string;
  filedAt: string;
}

export function useEventStream() {
  const [events, setEvents] = useState<Event[]>([]);

  useEffect(() => {
    const source = new EventSource('/api/stream');

    source.onmessage = (e) => {
      const event = JSON.parse(e.data);
      setEvents((prev) => [event, ...prev].slice(0, 100));
    };

    return () => source.close();
  }, []);

  return events;
}