Streaming Financial Data in Real-Time with Finlight’s WebSocket API

4 min readApr 23, 2025

Looking to supercharge your financial applications with real-time news updates? Whether you’re building trading dashboards, market monitoring tools, or alert systems, Finlight’s WebSocket API has you covered.

Finlight is a powerful API platform for delivering real-time financial, market, and geopolitical news, designed for developers who want fast, filtered, and flexible access to the stories that move markets.

✨ What You’ll Learn

In this guide, you’ll learn how to:

Connect to Finlight’s WebSocket API
Authenticate securely
Subscribe to live news streams
Keep your connection healthy with ping-pong
Understand how it compares to REST

By the end, you’ll have a working real-time stream of relevant financial news — perfect for trading, analytics, or alerts.

Setup & Requirements

Before we dive in, here’s what you need:

✅ A Finlight API Key — grab one from your dashboard at app.finlight.me
✅ Basic JavaScript or WebSocket knowledge
✅ Node.js (if using the SDK) or your preferred WebSocket-compatible language

You can use our official SDKs or roll your own integration:

npm: finlight-client
Python: finlight-client

🔍 REST API vs WebSocket

Here’s how the two options compare — choose the one that fits your real-time needs best:

REST API

Data Access: Fetch articles on demand via HTTP requests
Sorting: Articles are returned sorted by their publishDate (i.e., when the news provider originally published them)
Delayed Articles: Late-arriving stories (e.g., from aggregators like Yahoo) appear in the past based on their original publish date
Real-Time Capable? Yes — if polled frequently and tracked carefully
Best For: Custom polling systems, historical queries, or hybrid real-time setups

WebSocket API

Data Access: Stream new articles in real time as they are ingested into Finlight
Sorting: No manual sorting needed — articles are pushed in the order they enter the system
Delayed Articles: Even late stories appear immediately upon arrival (regardless of publish date)
Real-Time Capable? Yes — native real-time by design, no polling required
Best For: Dashboards, trading bots, alert systems, or anything needing instant updates

💡 Key Insight: REST is great if you need on-demand control or history.
But if you want true push-based real-time without manual effort, WebSocket is the way to go.

🔐 Authentication

Every WebSocket connection must include your API key in the header:

headers: {
  'x-api-key': '<your-api-key>',
}

💡 You can find your API key at https://app.finlight.me

WebSocket Endpoint

Connect to:

wss://wss.finlight.me

Real-Time News in Action (Node.js Example)

Here’s how easy it is to stream live financial news using our npm client:

import { FinlightApi } from "finlight-client";

const client = new FinlightApi({
  apiKey: "<your-api-key>",
});
client.websocket.connect(
  {
    // 'query' is optional – if omitted, you receive all incoming articles
    query: "Tesla",
    language: "en",
    extended: true,
  },
  article => {
    console.log(article);
  }
);

Available Query Parameters

You can filter the incoming stream by these optional parameters:

{
  query?: string;          // e.g., "interest rates" – omit to receive all articles
  sources?: string[];      // e.g., ["www.reuters.com", "www.ft.com"]
  language?: string;       // default: "en"
  extended?: boolean;      // full article text if true
}

Highlights:

query is optional — leave it out to stream everything
sources supports multiple domains
extended: true gives you full article text (if available), summaries are provided in both versions

Keeping the Connection Alive (Ping & Reconnect)

Finlight’s WebSocket API is powered by AWS API Gateway WebSockets, which means:

Connections are automatically closed after 2 hours
The server will disconnect you after 10 minutes of inactivity

Send Pings Every ~8 Minutes

Send this JSON message to keep your connection alive:

{ "action": "ping" }

You’ll receive:

{ "action": "pong" }

Example:

setInterval(() => {
  if (socket.readyState === WebSocket.OPEN) {
    socket.send(JSON.stringify({ action: "ping" }));
  }
}, 8 * 60 * 1000);

Reconnect Gracefully

If the server closes the connection (after 2h or inactivity), reconnect:

socket.onclose = () => {
  console.log("Connection closed. Reconnecting...");
  setTimeout(() => {
    connectWebSocket(); // your connection logic here
  }, 1000);
};

Make sure to restart your ping interval after reconnecting.

Example Article Response

{
  "title": "Trump tariffs could lead to a summer drop-off...",
  "source": "www.cnbc.com",
  "publishDate": "2025-04-20T18:02:08.000Z",
  "language": "en",
  "confidence": 0.9999,
  "sentiment": "negative",
  "summary": "...",
  "content": "Full article content if `extended` is true..."
}

💳 WebSocket Pricing & Connection Limits

Your Finlight subscription tier determines how many simultaneous WebSocket connections you can use:

Pro Standard — Includes 1 WebSocket connection
Pro Scale — Includes 3 WebSocket connections
Custom Tier — Supports custom limits, ideal for enterprise or high-volume setups

Final Thoughts & Use Cases

With Finlight’s WebSocket API, you can build:

📊 Live trading dashboards
🚨 Real-time alert systems
🧠 News sentiment analytics
🤖 Automated trading or LLM agents

Explore more:

Got questions? Curious to see more examples? Want to share what you’re building?

Tell me here or at our Discord.