Realtime Option Trades API

The Realtime Option Trades API provides streaming access to option trade data.

• WebSocket URL: wss://ws.optiondata.io

Request

Parameters

Sample Code

import WebSocket from 'ws';

const url = "wss://ws.optiondata.io?symbols=AAPL,SPX&token=cus_xxxx&premium=[300000,null]";

// Create a new WebSocket instance
const ws = new WebSocket(url);

// Event handler for connection open
ws.on('open', function open() {
  console.log('WebSocket connection opened');
});

// Event handler for incoming messages
ws.on('message', function incoming(data) {
  console.log('Received message:', data);
  // You can parse and handle the data here
  try {
    const receivedData = JSON.parse(data.toString());
    console.log('Parsed data:', receivedData);
    // Further processing of receivedData
  } catch (error) {
    console.error('Error parsing received data:', error);
  }
});

// Event handler for connection close
ws.on('close', function close() {
  console.log('WebSocket connection closed');
});

// Event handler for errors
ws.on('error', function error(err) {
  console.error('WebSocket error:', err);
});

import asyncio
import websockets
import json
import datetime
from asyncio import Queue

# Set your WebSocket URL here
url = "wss://ws.optiondata.io?token=YOUR_API_TOKEN"

# Create a global queue for demonstration
data_queue = Queue()

async def connect():
    """Connect to WebSocket and process messages."""
    while True:
        try:
            async with websockets.connect(url, ping_interval=10, ping_timeout=15) as websocket:
                print(f'[{datetime.datetime.utcnow()}]  WebSocket connection opened')

                try:
                    while True:
                        message = await websocket.recv()
                        print(f"[{datetime.datetime.utcnow()}] Message received: {message[:200]}{'...' if len(message) > 200 else ''}")
                        try:
                            received_data = json.loads(message)
                            option_symbol = received_data.get('option_symbol')

                            if received_data.get('daily_volume', 0) > 1000 and (
                                (received_data.get('price', 0) > 0.02 and option_symbol != "SPY")
                                or option_symbol == "SPY"
                            ):
                                if option_symbol:
                                    await data_queue.put(received_data)  # Push to queue
                                    print(f"[{datetime.datetime.utcnow()}] Queued data for option_symbol: {option_symbol}")

                        except json.JSONDecodeError as e:
                            print(f"[{datetime.datetime.utcnow()}]  Error parsing received data: {e}")

                except websockets.exceptions.ConnectionClosed as e:
                    print(f"[{datetime.datetime.utcnow()}] WebSocket connection closed: {e}, reconnecting immediately.")

        except websockets.exceptions.WebSocketException as e:
            print(f"[{datetime.datetime.utcnow()}] WebSocket error: {e}, reconnecting immediately.")
        except Exception as e:
            print(f"[{datetime.datetime.utcnow()}] Unexpected error: {e}, reconnecting immediately.")

        print(f"[{datetime.datetime.utcnow()}] Waiting 2 seconds before reconnecting...")
        await asyncio.sleep(2)  # Backoff before reconnecting to avoid hammering the server

if __name__ == "__main__":
    try:
        asyncio.run(connect())
    except KeyboardInterrupt:
        print("Shutting down...")

package main

import (
	"fmt"
	"log"
	"os"
	"os/signal"

	"github.com/gorilla/websocket"
)

func main() {
	// Define the URL of the WebSocket server
	url := "wss://ws.optiondata.io?symbols=AAPL,SPX&token=cus_xxxx&premium=[300000,null]"

	// Connect to the WebSocket server
	c, _, err := websocket.DefaultDialer.Dial(url, nil)
	if err != nil {
		log.Fatalf("Failed to connect to WebSocket server: %v", err)
	}
	defer c.Close()

	// Handle interrupt signals to terminate gracefully
	interrupt := make(chan os.Signal, 1)
	signal.Notify(interrupt, os.Interrupt)

	fmt.Println("WebSocket connection opened")

	done := make(chan struct{})

	// Goroutine for reading messages
	go func() {
		defer close(done)
		for {
			_, message, err := c.ReadMessage()
			if err != nil {
				log.Println("Error reading message:", err)
				return
			}
			fmt.Printf("Received message: %s\n", message)
			// Ideally, you would parse and handle the JSON message here
		}
	}()

	// Main loop for handling program exit
	for {
		select {
		case <-done:
			return
		case <-interrupt:
			log.Println("Interrupt received, closing WebSocket connection...")
			// To cleanly close the connection, send a close message and wait for the server to close the connection
			err := c.WriteMessage(websocket.CloseMessage, websocket.FormatCloseMessage(websocket.CloseNormalClosure, ""))
			if err != nil {
				log.Println("Error during closing WebSocket connection:", err)
				return
			}
			select {
			case <-done:
			}
			return
		}
	}
}

Response

Schema

Message format

When the WebSocket connects, the server sends a single connection success message. After that, each trade record is sent as an individual JSON message: the message body is the trade object itself (no status or data wrapper). Parse each incoming message as JSON; if it has a status field, treat it as control (e.g. SUCCESS); otherwise treat it as a trade record.

Sample response

When WebSocket connected (one-time):

{
  "status": "SUCCESS",
  "msg": "Connection established with id: 159b4576-70ec-476f-8a1d-b061fdca0fb8",
  "data": {
    "connection_id": "1707123456789-a1b2c3d4e5f6"
  }
}

When streaming data is received (each message is a plain trade object):

{
  "id": "13k7t4e",
  "date": "2025-05-02",
  "time": "2025-05-02 09:53:51",
  "symbol": "TSLA",
  "put_call": "CALL",
  "strike": 280,
  "expiration_date": "2025-05-02",
  "size": 7,
  "price": 4.44,
  "premium": 3109,
  "bid": 4.38,
  "ask": 4.5,
  "underlying_price": 281.77,
  "side": "MID",
  "sentiment": "NEUTRAL",
  "moneyness": "ITM",
  "expiry_days": 0,
  "option_symbol": "TSLA250502C00280000",
  "trade_count": 2,
  "dex": 413,
  "dei": 0.00239,
  "iv": 0.588,
  "delta": 0.589,
  "gamma": 0.0449,
  "oi": 14410,
  "daily_volume": 8352,
  "underlying_type": "STOCK",
  "option_activity_type": "SLAN",
  "earning_date": "2025-07-21",
  "market_cap": 900485935542,
  "updated_timestamp": 1746194031262
}

Response Error

401 Unauthorized (missing or invalid token, before WebSocket upgrade)

{
  "status": "ERROR",
  "code": 401,
  "msg": "Unauthorized, please login to https://optiondata.io get a valid API subscription plan first"
}

500 Internal Error

{
  "status": "ERROR",
  "code": 500,
  "msg": "Internal Error"
}

Heartbeat

The server sends a ping message every 20 seconds to keep the connection alive:

{ "type": "ping", "ts": 1707123456789 }

Clients can optionally respond with a pong: { "type": "pong", "ts": 1707123456789 }. If the client sends {"type": "ping"}, the server responds with {"type": "pong", "ts": ...}.

Connection limits

Each API token is limited to 5 concurrent WebSocket connections. If the limit is exceeded, the oldest connection for that token is closed with WebSocket close code 1008 and reason "Too many concurrent connections for this token".

Test mode

Use test_mode=true to validate your integration without live market data. No token is required.

• URL example: wss://ws.optiondata.io?test_mode=true&aggregation_mode=AGGREGATED&symbols=TSLA
• After sending the connection success message, the server streams pre-loaded sample trade records (with your filters applied), then closes the connection with code 1000 and reason "test_snapshot_complete".
• No heartbeat pings are sent in test mode. Connection limits are not enforced.

FAQ

What is an Aggregation Mode?

A: Real-time Option Trades in AGGREGATED mode consolidates trades with the same option symbol executed simultaneously (at the second level) into a single aggregate trade. This approach simplifies the identification of large trades that have been divided into multiple smaller transactions. If you want to see the original trades without any modification, please use RAW mode, the major differences between the two data feeds:

• The trade_count for option trades in RAW mode is always 1. In AGGREGATED mode, the trade_count can be either 1 or greater than 1. If it is greater than 1, this indicates that the option trade record aggregates multiple original option trades with the same option symbol that was executed simultaneously.
• The average daily volume for Real-time Option Trades in AGGREGATED mode is 4 million rows of records, while the average daily volume for RAW is around 7 million rows of records.

How to choose between AGGREGATED mode and RAW mode?

A: Institutional players often divide large trades into smaller ones and execute them simultaneously. They do this either to hide their intentions or due to a lack of liquidity or market depth at the moment of execution. This is the background for why we introduced AGGREGATED mode, for the case that you need to identify significant block trades in real-time, you can select AGGREGATED mode, allowing our aggregation services to combine these trades. If you prefer no modifications to the trades, you can choose RAW mode instead. By default, the API uses AGGREGATED mode unless you specify a different value for the aggregation_mode field. Please note that this is an assumption that trades executed simultaneously are sent by the same trader/institution, otherwise, you can choose RAW mode instead.

Can you give me some examples?

A: Let's say there are two records in real-time option trades with RAW mode like below:

// RAW MODE
date        time      symbol  strike  put_call expiration_date premium size trade_count
2025-02-01  09:32:02  TSLA    330     CALL     2025-02-15       1000    2    1
2025-02-01  09:32:02  TSLA    330     CALL     2025-02-15       2000    3    1

These two trades will be aggregated into one trade since they are executed at the same time with the same option symbol.

// AGGREGATED MODE
date        time      symbol  strike  put_call expiration_date premium size trade_count
2025-02-01  09:32:02  TSLA    330     CALL     2025-02-15       3000    5    2

For the example above, the size of trade in the AGGREGATED mode is equal to the sum of the size of the trades in the RAW mode(5 = 3 + 2), the trade size of trade in the AGGREGATED mode is equal to the sum of the trade_size in the RAW mode. For other data fields in AGGREGATED mode (eg: delta, iv, gamma, theta) is the average value of the related data field in the RAW mode.

Is there a delay in the data?

A: On average, We process around 20,000 records per minute during daily market open times. Due to the initial surge of data when the market opens, there may be delays during this period.

How to get started?

A: Please register at https://optiondata.io to get a 14-day free trial without a credit card required. Please reach out to us to help you set up the API connection.

What happens when the market closes?

A: When the market closes (5:00 PM ET), your WebSocket connection stays open. Data streaming stops, but heartbeat pings continue every 20 seconds. When the market reopens (9:30 AM ET, next trading day), data automatically resumes on the same connection -- no reconnection needed. If you connect outside market hours, authentication succeeds normally and you receive the connection success message, but no trade data is sent until the market opens. For historical data analysis outside market hours, please consider using our Historical Option Data API.

What are the refund and trial policies for different APIs?

A: Real-time Option Data API:

• 14-day free trial available
• Historical SQL included; trial SQL responses are capped at 10 rows
• Option Chain REST API included for trialing and active realtime users
• 30-day money-back guarantee
• No questions asked refund policy

Historical SQL and Option Chain:

• Included with the realtime plan
• Paid realtime subscriptions unlock larger historical SQL responses
• Endpoint: POST https://www.optiondata.io/api/historical/sql
• Option Chain endpoint: POST https://www.optiondata.io/api/option-chain

How do I request a refund?

A: For subscription purchases, simply send an email to support@optiondata.io using your login email address within 30 days of purchase. We will process your refund promptly and get back to you with confirmation.

The 30-day money-back guarantee applies to both real-time and historical API subscriptions. https://discord.com/invite/mE5pEDMdWs