Skip to main content

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​

ParameterTypeDescription
typestringMust be equal to hello.
heartbeatboolWhen true, the server will emit a heartbeat message every second whenever no other messages are produced. Defaults to false.

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.