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.

[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.

[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.

size

[155,2000]// minimum size is 155, maximum open interest is 200

[0,null] // // minimum size is 0, no maximum limit on size.

[null,300] // minimum size is 0, maximum size is 300.

Optional field,

leave it blank means no filtering

Filter for the total order size. The first number represents the minimum size, with a default value of 0 if null is provided. The second number is the maximum size if null is provided, there is no limit at the maximium size. default value is [0,null] with minimum size is 0, and no limit on the maximum size.

Sample Code

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

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

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

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.pfd https://assets.website-files.com/5ba40927ac854d8c97bc92d7/628bc18445cf7ec41d21ddfa_OPRA%20Pillar%20Output%20Specification.pdf

underlying_type

string

Indicates underlying is Common Stock, ETF, ETN, etc.

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

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

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

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

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.

PreviousChange Logs NextHistorical Option Data API

Last updated 5 months ago

hashtagRequest

hashtagParameters

hashtagSample Code

hashtagResponse

hashtagSchema

hashtagSample response

hashtagResponse Error

hashtagFAQ

Request

Parameters

Sample Code

Response

Schema

Sample response

Response Error

FAQ