Basics

The Finlight.me WebSocket API provides a continuous, real-time stream of financial news articles, delivered the moment they become available. Unlike traditional REST endpoints that require periodic polling, the WebSocket approach allows you to maintain a persistent connection and receive updates without making repeated requests. This leads to faster data delivery, efficient resource usage, and an enhanced user experience.

In this guide, you’ll learn the fundamental steps to connect, authenticate, and keep the connection alive with the Finlight.me WebSocket API.

Note: To use websocket features, you need to have a paid subscription. The free tier does not include the WebSocket feature. You need at least a subscription with WebSocket features.

Connecting to the WebSocket

To start receiving real-time financial news updates, you need to establish a WebSocket connection to the Finlight.me server. This connection remains open until either you or the server closes it. As soon as the connection is established, you can begin subscribing to article streams and receive messages as new articles are published.

NOTE: The WebSocket API technically disconnects after 2 hours. However, our typescript or python client library handles this automatically by reconnecting for you. You can also manually reconnect if needed.

  • WebSocket Endpoint:

    wss://wss.finlight.me

Key Points:

  • Real-Time Data: The WebSocket protocol enables a full-duplex connection, meaning data can flow to and from the server in real-time.
  • Publish/Subscribe Model: Once connected, you can specify your query (e.g., query: "nvidia") and the server will immediately send the latest matching article, followed by any new articles as they become available.
  • No Repeated Polling: Rather than continuously polling the server for new data, the server pushes new articles to you, reducing overhead and latency.

Authentication

To ensure secure and authorized access, all WebSocket connections to Finlight.me must be authenticated using your API key. This key verifies that you have the necessary permissions and access rights to receive real-time content.

Include your API key in the initial WebSocket handshake request headers. Most WebSocket client libraries allow you to specify additional headers when creating the connection.

  • Header:

    x-api-key: YOUR_API_KEY

How to Get an API Key:

Code Snippet (Node.js Example):

const WebSocket = require('ws')

const socket = new WebSocket('wss://wss.finlight.me', {
  headers: {
    'x-api-key': 'YOUR_API_KEY',
  },
})

socket.on('open', () => {
  console.log('Connected to Finlight.me WebSocket!')
  // You can now send a subscription request to start receiving articles
})

socket.on('error', (err) => {
  console.error('WebSocket error:', err)
})

Keeping the Connection Alive (Ping/Pong Mechanism)

WebSocket connections can remain open for extended periods, but network conditions, proxies, and firewalls may drop inactive connections. To mitigate this, Finlight.me supports a ping/pong keep-alive mechanism.

How It Works:

  • Client Sends ping: At regular intervals (e.g., every 8 minutes), the client sends a ping message to the server.
  • Server Responds pong: The server replies with a pong message, indicating the connection is still alive.
  • No Response Handling: If the client doesn’t receive a pong within a certain timeframe, it can assume the connection is lost and attempt to reconnect.

This simple heartbeat ensures that both the client and server know the connection is still active and can exchange data without interruption.

Example (Node.js with setInterval):

socket.on('open', () => {
  console.log('Connected to Finlight WebSocket')

  // Send a ping every 8 minutes
  const pingInterval = setInterval(
    () => {
      if (socket.readyState === WebSocket.OPEN) {
        console.log('Sending ping...')
        socket.send(JSON.stringify({ action: 'ping' }))
      }
    },
    8 * 60 * 1000,
  ) // 8 minutes in milliseconds

  socket.on('message', (data) => {
    const message = JSON.parse(data)
    if (message.action === 'pong') {
      console.log('Received pong, connection is alive.')
    } else {
      // Handle other messages, such as incoming articles
      console.log('Received message:', message)
    }
  })

  socket.on('close', () => {
    clearInterval(pingInterval)
    console.log('WebSocket connection closed.')
  })
})

Why is Ping/Pong Important?

  • Long-Running Connections: Many applications rely on continuously running WebSocket connections. Without a keep-alive mechanism, these connections may silently fail.
  • Network Reliability: Ping/pong checks ensure that transient network issues don’t cause the client to remain unaware of a broken connection.
  • Resource Efficiency: Quickly detecting a lost connection helps the client conserve resources by not waiting indefinitely for new data that will never arrive.

Connection Duration Limits

Finlight.me’s WebSocket infrastructure is powered by AWS API Gateway, which imposes a hard 2-hour maximum connection duration per WebSocket session. This is a platform-level limit — regardless of activity, all connections are closed after 2 hours by AWS.

What This Means for You

  • Your connection will be closed automatically after 2 hours, even if it’s actively receiving data or sending pings.
  • This behavior is expected and not indicative of an error or network issue.
  • To maintain a seamless experience, you need to reconnect after each 2-hour window.

We've Got You Covered

Both our Python and TypeScript client libraries handle this transparently:

  • When the server closes the connection after 2 hours, the client detects the disconnect.
  • It then automatically attempts to reconnect, preserving your stream with minimal interruption.
  • This ensures continuous data flow without manual intervention.

If you’re building your own client without using our libraries, be sure to implement reconnect logic on your end to handle the 2-hour limit gracefully.

By understanding these basics—connecting securely, authenticating your requests, and maintaining the connection with a ping/pong heartbeat—you’re well on your way to efficiently integrating Finlight.me’s WebSocket API into your application. From here, you can explore subscription messages, filters like source or language, and handle incoming articles to build rich, real-time financial news experiences.

Was this page helpful?