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.
wss://api.roic.ai/v3.0.0/news/live/streamPlan Access
Free
(Your plan)
Individual
$29/mo
Professional
$89/mo
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()){
"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
categorystringoptionalReceive only the headlines of this category. Omit it to receive every category. New values can be added.
breakingsincestringoptionalID of the last headline you received, beginning with lfi_. The server first sends the headlines saved after it, then new headlines. See Reconnect.
lfi_Xk3PqT9vLm2RwAResponse
Response fields
typestringType 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.
dataobjectThe headline.
+ Show child attributes- Hide child attributes
idstringUnique identifier of the headline, beginning with lfi_. It never changes.
categorystringCategory of the news, currently always breaking. New values can be added, so your code must accept values it does not know.
textstringOne or two sentences of plain text that report the news.
published_atstringTime 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:
- Start a 60-second timer when the connection opens.
- Restart the timer each time your client receives a frame, for example a
heartbeatframe or anewsframe. - 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
400and theparamfield of the error issince, connect again withoutsince. - If the server closes the connection with code
1013, connect again with the samesince. - If the server closes the connection with code
4000, connect again withsinceimmediately, 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.