Realtime Option Data API

Request

WEBSOCKET wss://ws.optiondata.io

Parameters

Name	Example	Required?	Description
token	cus_xxxxxxxxxx(Get Your API token here: portal.optiondata.io )	Required	Get API token here: https://portal.optiondata.io
aggregation_mode	AGGREGATED or RAW	Optional field, default value is AGGREGATED if leave blank	Determine how the option trades are aggregated by our algorithm. In AGGREGATED mode, the modified real-time feed combines option trades executed simultaneously for the same option symbol. In contrast, RAW mode keep the option trades in their original form without any modifications. For more details, more details.
symbols	SPY,TSLA,SPX or AAPL	Optional field, leave it blank means no filtering	A list of symols in upper case seperated by comma. Using the * wildcard or don't provide it to subscribe to all symbols.
premium	[100000,250000]//min premium is $100000, max premium is 250000 [100,null]//min premium is $100, no max limit	Optional field, leave it blank means no filtering	The filter for minimum premium. The first value represents the minimum premium, while the second value indicates the maximum premium. If not provided, [0,null] will be the default value.
sentiment	BULLISH,BEARISH,NEUTRUAL OR BULLISH	Optional field, leave it blank means no filtering	The filter for sentiment includes potential values of BULLISH, BEARISH, and NEUTRUAL. You can combine multiple selections by separating them with commas, such as NEUTRUAL,BEARISH.
underlying_type	STOCK,ETF,INDEX or STOCK or ETF or INDEX	Optional field, leave it blank means no filtering	The filter for underlying_type includes potential values of INDEX, STOCK, and ETF. You can combine multiple selections by separating them with commas, such as INDEX,STOCK.
delta	[-0.9,0.98] or [-1,0.9]	Optional field, leave it blank means no filtering	The filter for delta has a default range of [-1, 1]. The first value represents the minimum delta, while the second value indicates the maximum delta. The range must remain within [-1, 1]
moneyness	ITM,OTM,ATM or ITM	Optional field, leave it blank means no filtering	The filter for moneyness includes potential values of ITM, ATM, and OTM. You can combine multiple selections by separating them with commas, such as ITM,OTM.
expiry_days	[15,20]// minimum expiry days is 15, maximum expiry day is 20 days [0,null] // // minimum expiry days is 15, no maximum expiry days [null,30] // minimum expiry days is 0, maximum expiry day is 30 days	Optional field, leave it blank means no filtering	The days remaining until the expiration date. The first number represents the minimum expiration days, with a default value of 0 if null is provided. The second number is the maximum expiration days; if null is provided, there is no limit.
is_recent_earning_only	true	Optional field, leave it blank means no filtering	Filter for symbols with incoming earning reports(earning_date is not null).
put_call	CALL , or PUT	Optional field, leave it blank means no filtering	Filter to identify whether this option trade is PUT or CALL
side	ASK,AASK or ASK,BID	Optional field, leave it blank means no filtering	Identify the side on which this trade is executed on
strike	[15.5,20]// minimum strike price is $15.5, maximum strike price is $20 [0,null] // // minimum expiry days is $0, no maximum limit on strike price. [null,30] // minimum strike price is $0, maximum strike price is $30.	Optional field, leave it blank means no filtering	Identity the range of the Strike price of the option trade. The first number represents the minimum strike price, with a default value of 0 if null is provided. The second number is the maximum strike price. if null is provided, there is no limit at the maximium strike price. default value is [0,null] with minimum strike price is $0, and no limit on the maximum strike price.
oi	[155,2000]// minimum open interest is 155, maximum open interest is 200 [0,null] // // minimum open interest is 0, no maximum limit on open interest. [null,300] // minimum open interest is 0, maximum open interest is 300.	Optional field, leave it blank means no filtering	The total number of this options contract that are still open. The first number represents the minimum OI, with a default value of 0 if null is provided. The second number is the maximum OI. if null is provided, there is no limit at the maximium OI. default value is [0,null] with minimum OI is 0, and no limit on the maximum OI.
iv	[0.1,1.1]// minimum iv is 0.1, maximum iv is 1.1 [0,null] // // minimum iv is 0, no maximum limit. [null,1.1] // minimum iv is 0, maximum iv is 1.1	Optional field, leave it blank means no filtering	Implied Volatility which reflects the market's expectations of the future volatility of the underlying asset's price. The first number represents the minimum IV, with a default value of 0 if null is provided. The second number is the maximum IV. if null is provided, there is no limit at the maximium IV. default value is [0,null] with minimum IV is 0, and no limit on the maximum IV.
option_activity_type	AUTO // single choice AUTO,SLAN,SLAI// multiple choices	Optional field, leave it blank means no filtering	how is the trade excuted. All relevant code can be found at Link
trade_count	[1,1]//only block trads [2,null]//only aggregated trades [2,10]// aggregated trades that aggregates 2 to 10 trades	Optional field, leave it blank means no filtering	Number of trades involved in the sweep or trade. Use [1,1] to filter for block trades only, and [2,null] to filter for aggregated trades.
is_opening_only	true	Optional field, leave it blank means no filtering	Filter for trades that are opening trades, with a size greater than the sum of open interest and daily volume, minus the trade size.
test_mode	true	Optional	If test_mode is set to true and it is not market time, the WebSocket will stream data from three days ago until today. This feature is useful for developers who want to continue testing the WebSocket stream connection after the market closes.

Sample Code

Typescript

// Some code
import WebSocket from 'ws';

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

// 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);
});

Python

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...")

Go

// Some code
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&test_mode=true"

	// 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

Name	Type	Description
id	string	unique id for this option trade record
symbol	string	Ticker Symbol (TSLA, MSFT, etc...)
date	string	the date the trade was executed, the date format is YYYY-MM-DD
time	string	The time the trade was created. Format is YYYY-MM-DD HH:MM:SS
put_call	string	Indicates whether this trade is PUT or CALL
strike	float	Strike price of the option trade
expiration_date	string	The date on which the Option expires. The Option becomes invalid after this date and cannot be exercised ex: 2022-04-05
option_activity_type	string	Please refer to https://assets.website-files.com/5ba40927ac854d8c97bc92d7/5bf419828984e605fe3ba2e7_proposed_opra_trade_codes.pfdhttps://assets.website-files.com/5ba40927ac854d8c97bc92d7/628bc18445cf7ec41d21ddfa_OPRA%20Pillar%20Output%20Specification.pdf
underlying_type	string	Indicates underlying is Common Stock, ETF, ETN, etc.
oi	integer	Open Interest. The total number of this options contract that are still open.
size	integer	Total order size (either of the 1 trade for the trade of SINGLE or REPEATED, or the sum of trade sizes for a AGGREGATED trade)
price	float	Last price of a trade, or last price of last trade in a sweep.
underlying_price	float	Current stock price of the underlying asset
bid	float	Option contract best bid
bid_size	integer	Option contract bid size on exchange with best bid
ask_size	integer	Option contract bid size on exchange with best ask
ask	float	Option contract best ask
iv	float	Implied volatility (IV) is an estimate of the future volatility of the underlying stock based on options prices.
premium	float	Cost in dollar of the entire sweep or block option trade
sentiment	string	BULLISH, BEARISH, or NEUTRAL The sentiment is estimated based on whether the trade was executed at the bid, ask, or spot price.
trade_count	integer	Number of trades involved in the sweep.
expiry_days	integer	The days left to expiration date.
delta	float	Delta is a measure of the change in an option's price
vega	float	Vega is a Greek that measures how sensitive an option's price is to changes in the implied volatility of the underlying stock
exchange	string	Exchange where the trade executed
daily_volume	integer	Day volume for this option contract including this trade
earning_date	string	next earning date for the underlying asset.
updated_timestamp	string	the UTC timestamp that this data record is created in our system
theta	float	measures the rate at which an option's price decreases as it approaches its expiration date, commonly referred to as "time decay."
rho	float	measures the sensitivity of an option’s price to changes in interest rates.
market_cap	Int	market capitalization, company's total market value, represented in dollars, and calculated by multiplying the current share price by the total number of outstanding shares
option_symbol	string	Option Contract Symbol, for example:TSLA240430P00508000, this refers to a put option contract with a strike price of $508 and an expiration date of April 30, 2024.

Sample response

200

//When websocket connected
{
  "status": "SUCCESS",
  "msg": "{ message: `Connection established with id: 159b4576-70ec-476f-8a1d-b061fdca0fb8"
}

//When Streaming data received
{
  "status": "SUCCESS",
  "data": {
    "id": "m3d9eur5",
    "date": "2024-11-11",
    "size": 10,
    "price": 15.24,
    "premium": 15240,
    "bid": 13.85,
    "ask": 15.85,
    "time": "2024-11-11 11:50:20",
    "symbol": "HOOD",
    "put_call": "CALL",
    "strike": 27,
    "expiration_date": "2027-01-15",
    "underlying_type": "STOCK",
    "option_activity_type": "AGGREGATED",
    "oi": 710,
    "underlying_price": 33.77,
    "sentiment": "NEUTRAL",
    "expiry_days": 795,
    "side": "MID",
    "moneyness": "ITM",
    "iv": 0.67,
    "delta": 0.7664,
    "option_symbol": "HOOD270115C00027000",
    "gamma": 0.0092,
    "daily_volume": 25,
    "earning_date": "1970-01-01",
    "trade_count": 2,
    "updated_timestamp": "1731343820218",
    "ask_size": "18",
    "bid_size": "3",
    "exchange": "EDGO",
    "vega": 0.152656,
    "theta": -0.006518,
    "rho": 0.231765,
    "market_cap": "25953526229"
  }
}

Response Error

400

{
  "status": "ERROR",
  "code": 400,
  "msg": "error message"
}

500

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

FAQ

Q: 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.

Q: 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.

Q: 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 RAWmode(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.

Q: 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.

Q: How to get started?

A: Please register at https://portal.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.

Q: Is there still streaming data after market close, and if not, how can I test it?

A: By default, there is no streaming data available after market close. However, if you set the test_mode parameter to true, the WebSocket will stream data from three days ago until today. This feature enables developers to continue testing the WebSocket stream connection even after the market has closed. Please note that during market hours, if test_mode is set to true, the WebSocket will still stream real-time data instead of historical data from the past three days.

Q: What are the refund and trial policies for different APIs?

A: Real-time Option Data API:

• 14-day free trial available

• 30-day money back guarantee

• No questions asked refund policy

Historical Option Data API:

• No free trial available

• No refund policy (all sales final)

• Contact support for any technical issues

Q: How do I request a refund for real-time API?

A: For real-time API subscriptions, simply send an email to [email protected] using your login email address within 30 days of purchase. We'll process your refund promptly and get back to you with confirmation. Note: Refunds are only available for real-time API subscriptions, not historical data purchases.