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:

🔍 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': '',
}

💡 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: "",
});
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.