General

Connection flow

1. Establish a WebSocket connection to wss://api.sec.finfeedapi.com.
2. (Optional) Send a Hello message to enable Heartbeat messages (see below).
3. The server delivers a short backlog of recently discovered SEC filings first (is_historical = true).
4. As soon as the backlog is complete, every new filing is pushed to you in real-time with ≈ 100 ms latency (is_historical = false).
5. The connection remains open until it is closed by the client or a Reconnect instruction is received from the server.

Hello OUT

Sending the Hello message is optional. It is required only when you want to receive periodic Heartbeat messages.

{
  "type": "hello",
  "heartbeat": true
}

Message parameters

Error handling

If the server detects an invalid message, it responds with a JSON object of type error and immediately closes the connection.

{
  "type": "error",
  "message": "Invalid API key"
}

Always log error messages for later inspection and re-establish the connection once the problem has been fixed.

Data buffering and flow control

The server streams data as fast as your network connection permits. If the client cannot read messages quickly enough, TCP back-pressure will cause the server to build an internal buffer. When that buffer becomes full the server closes the connection using an error message similar to the one below:

{
  "type": "error",
  "message": "Reached maximum allowed buffered messages for this connection."
}

To avoid disconnects:

• Make sure your receiving thread reads from the socket without doing any heavy processing.
• Off-load parsing and business logic to another thread or process.
• Monitor the delay between the discovered_time in the messages and your local clock – a growing gap indicates the client is falling behind.

The default per-connection buffer size is 131 072 messages.