How to Detect Unusual Options Activity with the SteadyAPI Options API

Unusual Options Activity (UOA) refers to options contracts trading at volumes significantly higher than their current Open Interest (OI). This Volume/Open Interest ratio is a critical metric for traders because it often signals "smart money" positioning. When institutional investors or hedge funds act on non-public information or strong conviction, they often utilize the options market to leverage their capital. Detecting these anomalies in real-time allows developers and analysts to spot potential breakouts or reversals before they reflect in the stock price.

Obtain API key:
Get your SteadyAPI key

The Unusual Options Activity Endpoint

The GET /v1/markets/options/unusual-options-activity endpoint provides a direct feed of these anomalies. Instead of calculating ratios manually across the entire market, this endpoint returns a curated list of contracts where current volume typically exceeds open interest or meets specific volatility criteria.

Documentation:
SteadyAPI Unusual Options Activity Endpoint Documentation

Detailed Parameter Analysis

To effectively use this endpoint, you must understand how to filter the stream of data to match your specific analysis criteria.

• type
  This parameter filters the asset class. Accepted values are STOCKS, ETFS, or INDICES. For detecting corporate insider movements, you would typically set this to STOCKS. For broader market sentiment, INDICES or ETFS are more appropriate.
• price_min
  This allows you to filter the underlying asset by price. This is useful for filtering out penny stocks or low-cap assets that may be prone to manipulation or lack liquidity. Setting a price_min of 10 or 20 ensures you are analyzing companies with established valuations.
• ticker
  If you are monitoring a specific watchlist, you can pass a ticker symbol (e.g., AAPL) to see if there is any unusual activity for that specific company. If omitted, the API returns market-wide activity.

Python Example: Filtering for High Conviction Trades

The following Python script demonstrates how to fetch UOA data and programmatically filter for "high conviction" trades. In this context, we define high conviction as a volumeOpenInterestRatio greater than 3.0, meaning the volume traded today is at least three times the total existing open interest.

import requests

# Configuration
url = "https://api.steadyapi.com/v1/markets/options/unusual-options-activity"
api_key = "YOUR_AUTH_KEY"  # Replace with your actual key

headers = {
    "Authorization": f"Bearer {api_key}"
}

# Request parameters
params = {
    "type": "STOCKS",
    "price_min": "15",  # Filter out stocks under $15
    "page": "1"
}

try:
    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    data = response.json()

    print(f"Scanning {len(data['body'])} contracts for high conviction...")

    # Filter for Volume/OI Ratio > 3.0
    for trade in data['body']:
        # volumeOpenInterestRatio is returned as a string in the API
        vol_oi_ratio = float(trade.get('volumeOpenInterestRatio', 0))
        
        if vol_oi_ratio > 3.0:
            print(f"High Conviction Alert: {trade['baseSymbol']}")
            print(f"Contract: {trade['symbol']}")
            print(f"Type: {trade['symbolType']} | Strike: {trade['strikePrice']}")
            print(f"Vol/OI Ratio: {vol_oi_ratio}")
            print(f"Implied Volatility: {trade['volatility']}")
            print("-" * 30)

except requests.exceptions.RequestException as e:
    print(f"Error fetching data: {e}")

Understanding the Response

The API returns a JSON response containing metadata and a body of trade objects.

{
  "meta": {
    "version": "v1.0",
    "status": 200,
    "copywrite": "https://steadyapi.com",
    "count": 20,
    "total": 1736,
    "page": "3"
  },
  "body": [
    {
      "symbol": "PANW|20240223|310.00C",
      "baseSymbol": "PANW",
      "baseLastPrice": "261.97",
      "symbolType": "Call",
      "strikePrice": "310.00",
      "expirationDate": "02/23/24",
      "volume": "2,445",
      "openInterest": "119",
      "volumeOpenInterestRatio": "20.55",
      "volatility": "151.81%",
      "tradeTime": "02/21/24"
    }
  ]
}

Key Fields Analysis

• volumeOpenInterestRatio
  This is the primary indicator of "unusual" behavior. A ratio significantly greater than 1.0 indicates aggressive positioning. In the example above, a ratio of 20.55 implies extreme interest, as volume is over 20 times the open interest.
• strikePrice
  The price target for the option. Comparing this to the baseLastPrice helps determine if the activity is betting on a massive move (Out of the Money) or a safer directional bet (In the Money).
• expirationDate
  Short-term expirations with high UOA often suggest an expectation of immediate news or price action, whereas long-term expirations indicate a fundamental shift in valuation outlook.
• volatility
  The Implied Volatility (IV). High IV indicates expensive premiums, meaning traders are willing to pay more to enter the position, further validating the strength of the sentiment.
• symbolType
  Indicates whether the unusual activity is a Call (bullish betting) or a Put (bearish betting/hedging).

Practical Use Cases

Real-Time Volatility Scanners

Developers can build dashboards that alert users instantly when a Vol/OI ratio spikes above a certain threshold (e.g., > 5.0) on stocks with upcoming earnings, signaling potential insider confidence.

Institutional Sentiment Indicators

By aggregating the UOA data over a week, you can create a "Sentiment Score" for specific sectors. If the technology sector shows 80% Call flow in UOA data, it indicates strong institutional bullishness despite broader market noise.

Learn more or explore other endpoints:
SteadyAPI Stock and Options Data API