Real-time news

Get breaking stock market news the moment it is published. The Real-time news API sends each headline to your app over a WebSocket, as JSON with the headline text and its publication time. Use it to run a live news ticker or to alert your users to breaking news.

WSwss://api.roic.ai/v3.0.0/news/live/stream

Plan Access

Free

(Your plan)

Individual

$29/mo

Professional

$89/mo

Request
import asyncio
import json
import websockets

async def main():
    async with websockets.connect(
        "wss://api.roic.ai/v3.0.0/news/live/stream",
        additional_headers={"Authorization": "Bearer YOUR_API_KEY"},
    ) as socket:
        async for message in socket:
            frame = json.loads(message)
            if frame["type"] == "news":
                print(frame["data"])

asyncio.run(main())
Response
101 Switching Protocols
{
  "type": "news",
  "data": {
    "id": "lfi_Xk3PqT9vLm2RwA",
    "category": "breaking",
    "text": "Nvidia shares rise 4% in premarket trading after the company guides fourth-quarter revenue to $65 billion, above the $61.8 billion analysts expected.",
    "published_at": "2026-11-11T13:42:18.412Z"
  }
}

Activity

How many headlines the feed sends.

Parameters

Query parameters

categorystringoptional

Receive only the headlines of this category. Omit it to receive every category. New values can be added.

Values: breaking
sincestringoptional

ID of the last headline you received, beginning with lfi_. The server first sends the headlines saved after it, then new headlines. See Reconnect.

Example: lfi_Xk3PqT9vLm2RwA

Response

Response fields

typestring

Type of the frame: news for a headline, heartbeat for the frame the server sends every 30 seconds. New types can be added, so ignore a type you do not know.

dataobject

The headline.

+ Show child attributes
idstring

Unique identifier of the headline, beginning with lfi_. It never changes.

categorystring

Category of the news, currently always breaking. New values can be added, so your code must accept values it does not know.

textstring

One or two sentences of plain text that report the news.

published_atstring

Time the news was published, as an ISO 8601 UTC timestamp.

Keep the connection alive

Every 30 seconds, the server sends a WebSocket ping and a heartbeat frame on each connection. You do not have to enable them. The connection stays open when there are no new headlines.

{ "type": "heartbeat", "ts": "2026-11-11T13:42:30.000Z" }

The ping lets the server check your client. Your WebSocket library replies to each ping with a pong automatically. If the server receives no pong and no other data from your client between two pings, it closes the connection. It does not send a close frame, so your client sees code 1006.

The heartbeat frame lets your client check the server. Use a timer for this check:

  1. Start a 60-second timer when the connection opens.
  2. Restart the timer each time your client receives a frame, for example a heartbeat frame or a news frame.
  3. If the timer ends, the connection is dead. Close it and connect again.

Do not use the ping for this check. The built-in WebSocket in browsers, Node.js, Bun, Deno, and Cloudflare Workers does not show pings to your code.

Reconnect

A connection can close at any time. When it closes, connect again. To get the headlines that you missed, add the id of your last news frame to the URL as since, for example ?since=lfi_Xk3PqT9vLm2RwA.

The server first sends the missed headlines as normal news frames, oldest first. Then it sends new headlines. It does not skip or repeat a headline between the missed headlines and the new headlines. It sends a maximum of 500 missed headlines. If you missed more, you get the newest 500.

Follow these rules when you connect again:

  • Wait before each attempt. Start with 1 second. Double the wait after each failed attempt, to a maximum of 60 seconds. Add a small random delay.
  • If the server refuses the handshake with status 400 and the param field of the error is since, connect again without since.
  • If the server closes the connection with code 1013, connect again with the same since.
  • If the server closes the connection with code 4000, connect again with since immediately, without the wait. You do not lose headlines. The server closes each connection 24 hours after it opens, because it checks your API key and plan only at the handshake.

Handle a refused handshake

If the API refuses the handshake, it sends an HTTP response with the standard v3 error envelope and does not open the connection.