Websocket
Trade ideas, market commentary, and session signals pushed as they happen
Instead of polling the REST API, your program can hold one websocket connection to Optionomics and be pushed each item the moment it is made: a trade idea as it opens and again as it resolves, each market commentary as it is published, and every session signal.
The websocket carries Optionomics’ own readings. It never carries raw exchange prints.
Availability: Developer Pro only. A key on any other plan, Developer included, is refused when the connection opens. See Subscription Plans.
Connecting
| Address | wss://optionomics.ai/socket/websocket |
| Authentication | your API key, sent as the token query parameter |
| Full URL | wss://optionomics.ai/socket/websocket?token=YOUR_API_KEY |
Use the same API key you use for the REST API and the MCP server. You can copy the address from the Where the key goes panel at optionomics.ai/developers/keys.
- A missing, expired, or revoked key is refused when the connection opens (the handshake fails with HTTP
403), and so is a key on any plan other than Developer Pro. - Connect from a program—a server, a script, a bot—not from a web page on another website. Browsers on other sites are refused.
- Keep the key out of source code: read it from an environment variable, as the examples below do.
Topics
After connecting, you join one or more topics. Developer Pro includes all three. An unknown topic refuses the join with the reason unauthorized; the connection itself stays open, and the other topics keep working.
| Topic | Event | When it arrives |
|---|---|---|
trade_ideas |
trade_idea |
When a trade idea opens, and again when it resolves |
market_commentaries |
commentary |
When a market commentary is published |
readings:signals |
signal, signal_retired |
During the session (09:00–16:59 ET), as each session signal is published, restated, or retired |
trade_ideas
Each message is event trade_idea, with the same item the trade ideas REST endpoint returns: the idea’s id, symbol, strategy, levels, status, track record, timestamps, and so on. An opening and a resolution use the same event and the same shape—read the idea’s status to tell which one you received.
market_commentaries
Each message is event commentary:
| Field | Meaning |
|---|---|
id |
The commentary’s id |
category |
The commentary category |
severity |
info, notable, or critical |
headline |
The headline |
body |
The full text |
symbols |
The symbols it mentions (a list, possibly empty) |
generated_at |
When it was written, ISO 8601 |
return_pct, peak_return_pct |
Follow-up performance figures, when there are any |
readings:signals
Session signals are standing statements about a stock or the market—such as a stock touching the edge of its priced move, its priced move repricing far from its norm, or implied volatility’s premium reaching an extreme—each backed by a measurement. They are the same signals the starter alerts fire on. Like every Optionomics reading they are about size, odds, and cost, never direction.
Event signal carries:
| Field | Meaning |
|---|---|
id |
The signal’s id—stable for the life of the signal |
kind |
What kind of signal it is, for example expected_move_touch or expected_move_repricing |
lane |
Its family: vol, event, flow, execution, or regime |
horizon |
What it bears on: right now, the rest of the session, the next few weeks, or a dated event such as a report (for example intraday) |
evidence_class |
How it is backed, for example measured |
symbol |
The stock it is about, or none for a market-wide signal |
score |
Its strength, 0 to 100 |
half_life_s |
How fast its strength fades, in seconds |
facts |
The numbers behind the statement; the contents depend on the kind |
revision |
Starts at 1 |
session_date |
The session it belongs to |
observed_at, emitted_at, expires_at |
When it was observed, published, and when it expires |
When a signal’s facts change, the same signal is sent again with the same id and a higher revision—replace your copy rather than adding a new one. When a signal expires, event signal_retired arrives with only its id.
The frame format
The server speaks a small JSON protocol that any language can implement. Every frame, in both directions, is a JSON array of five elements:
[join_ref, ref, topic, event, payload]
| Position | Name | What it is |
|---|---|---|
| 1 | join_ref |
A string you choose when you join a topic, repeated on that topic’s frames. null for heartbeats and for server pushes. |
| 2 | ref |
A string you choose for each message you send, unique on the connection (a counter works). The server’s reply carries the same ref. Server pushes have null. |
| 3 | topic |
The topic, for example trade_ideas. Heartbeats use the topic system. |
| 4 | event |
What the frame is: join to join, heartbeat, reply for the server’s answer, or a data event such as trade_idea or signal. |
| 5 | payload |
A JSON object: {} for a join or heartbeat, the data for a push. |
The rules:
- Join a topic by sending
[join_ref, ref, topic, "join", {}]. - The server answers with event
replyand a payload of{"status": "ok", "response": {}}, or{"status": "error", "response": {"reason": "unauthorized"}}for a topic that does not exist. - Data arrives as
[null, null, topic, event, payload]. - Heartbeat every 30 seconds by sending
[null, ref, "system", "heartbeat", {}]. If the server hears nothing from you for 60 seconds, it closes the connection. - If the connection drops, reconnect and join your topics again. Items published while you were disconnected are not replayed—use the REST API to catch up.
Node.js example
Node.js 22 and later have WebSocket built in, so this needs no packages:
// Node.js 22 or later: WebSocket is built in, no packages needed.
const url =
"wss://optionomics.ai/socket/websocket?token=" + process.env.OPTIONOMICS_API_KEY
const ws = new WebSocket(url)
let ref = 0
const send = (topic, event, payload = {}, joinRef = null) =>
ws.send(JSON.stringify([joinRef, String(++ref), topic, event, payload]))
ws.onopen = () => {
for (const topic of ["trade_ideas", "market_commentaries", "readings:signals"])
send(topic, "join", {}, topic)
setInterval(() => send("system", "heartbeat"), 30_000)
}
ws.onmessage = ({ data }) => {
const [, , topic, event, payload] = JSON.parse(data)
if (event === "reply") {
if (payload.status !== "ok") console.error("join refused:", topic, payload.response)
return
}
console.log(topic, event, payload)
}
Run it with OPTIONOMICS_API_KEY=your-key node stream.js.
Python example
This uses the websockets package (pip install websockets):
import asyncio
import itertools
import json
import os
from urllib.parse import urlencode
import websockets
URL = "wss://optionomics.ai/socket/websocket?" + urlencode(
{"token": os.environ["OPTIONOMICS_API_KEY"]}
)
TOPICS = ["trade_ideas", "market_commentaries", "readings:signals"]
async def main():
refs = itertools.count(1)
async with websockets.connect(URL) as ws:
async def send(topic, event, payload=None, join_ref=None):
frame = [join_ref, str(next(refs)), topic, event, payload or {}]
await ws.send(json.dumps(frame))
async def heartbeat():
while True:
await asyncio.sleep(30)
await send("system", "heartbeat")
for topic in TOPICS:
await send(topic, "join", join_ref=topic)
beating = asyncio.create_task(heartbeat())
try:
async for raw in ws:
_join_ref, _ref, topic, event, payload = json.loads(raw)
if event == "reply":
if payload["status"] != "ok":
print("join refused:", topic, payload["response"])
continue
print(topic, event, payload)
finally:
beating.cancel()
asyncio.run(main())
Run it with OPTIONOMICS_API_KEY=your-key python stream.py.
Tips
- Signals are updated in place. Keep signals in a dictionary keyed by
id; overwrite on eachsignaland delete onsignal_retired. - Plan changes take effect on the next connection. If your plan changes, reconnect so the server checks your topics again.
- Requests made over the websocket do not count against your REST/MCP per-minute allowance; only the REST API and MCP server are rate limited.