# 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.
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 {% tabs %} {% tab title="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);
});

{% endtab %} {% tab title="Python" %} ```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...") ``` {% endtab %} {% tab title="Go" %} ```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 } } } ``` {% endtab %} {% endtabs %} ## 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.pfd https://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** {% tabs %} {% tab title="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"
  }
}

{% endtab %} {% endtabs %} ### **Response Error** {% tabs %} {% tab title="400" %} ```json { "status": "ERROR", "code": 400, "msg": "error message" } ``` {% endtab %} {% tab title="500" %} ```json { "status": "ERROR", "code": 500, "msg": "Internal Error" }// Some code ``` {% endtab %} {% endtabs %} ## FAQ {% hint style="info" %} **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 `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. **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](https://discord.com/invite/mE5pEDMdWs) 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 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.
[\
]() {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.optiondata.io/websocket-data-api/realtime-option-data-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.