How to Detect Unusual Options Activity with the Mboum API

Unusual Options Activity (UOA) refers to option contracts that exhibit trading volume significantly higher than their current open interest or historical average. This discrepancy often signals that institutional investors or "smart money" are taking large positions in anticipation of a significant price movement. By monitoring these anomalies, developers and traders can identify potential volatility events before they reflect in the stock price.

You can access institutional-grade options data to build these detection systems via the Mboum API:
https://mboum.com/pages/api

The API Strategy

To detect these market signals, we utilize the Unusual Options Activity endpoint. Unlike standard option chain endpoints that return all available contracts, this specific endpoint pre-filters the market for contracts exhibiting abnormal volume relative to open interest.

Endpoint

GET /v1/markets/options/unusual-options-activity

Documentation:
https://docs.mboum.com#stocks-options-GETapi-v1-markets-options-unusual-options-activity

This endpoint accepts a type parameter, allowing you to filter by asset class, such as STOCKS, ETFS, or INDICES. It returns a list of contracts where the volume aggressively exceeds the open interest, often serving as a leading indicator for directional moves.

Python Example: Filtering High-Conviction Trades

The following Python script demonstrates how to retrieve unusual options activity for stocks. We then implement a filtering mechanism to isolate "high conviction" trades, defined here as contracts with a volume-to-open-interest ratio greater than 5.

import requests
import json

# Configuration
url = "https://api.mboum.com/v1/markets/options/unusual-options-activity"
api_key = "{YOUR_AUTH_KEY}"
headers = {
    "Authorization": f"Bearer {api_key}"
}
params = {
    "type": "STOCKS",
    "page": "1"
}

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

    print(f"Total unusual contracts found: {data['meta']['total']}")

    # Filter for high conviction trades
    print("\n--- High Conviction Trades (Vol/OI > 5) ---")
    
    for contract in data.get('body', []):
        # Safely convert ratio to float, handling potential string formatting
        try:
            vol_oi_ratio = float(contract.get('volumeOpenInterestRatio', 0))
        except ValueError:
            continue

        if vol_oi_ratio > 5.0:
            print(f"Symbol: {contract['symbol']}")
            print(f"Type: {contract['symbolType']} | Strike: {contract['strikePrice']}")
            print(f"Vol/OI Ratio: {vol_oi_ratio}")
            print("-" * 30)

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

Analyzing the Response Data

The API returns a comprehensive JSON object for each contract. Understanding specific fields is critical for determining the significance of the trade.

Below is a snippet of a response object representing a Call option with high unusual activity:

{
    "symbol": "PANW|20240223|310.00C",
    "baseSymbol": "PANW",
    "symbolType": "Call",
    "strikePrice": "310.00",
    "expirationDate": "02/23/24",
    "lastPrice": "0.14",
    "volume": "2,445",
    "openInterest": "119",
    "volumeOpenInterestRatio": "20.55",
    "volatility": "151.81%",
    "tradeTime": "02/21/24"
}

Key Fields

• volumeOpenInterestRatio: 20.55
  This is the primary indicator of unusual activity. A value of 20.55 means the day's volume was more than 20 times the existing open interest. This indicates new positions are being opened aggressively.

• volume: 2,445
  The total number of contracts traded during the session. High volume confirms liquidity and conviction.

• openInterest: 119
  The number of outstanding contracts before the trading session began. A low open interest relative to volume confirms the activity is "unusual."

• volatility: 151.81%
  The implied volatility (IV). Extremely high IV indicates the market is pricing in a massive move, making the option expensive but potentially rewarding if the move occurs.

Practical Use Cases

Earnings Plays

Traders often use unusual activity to detect sentiment before an earnings report. If you see massive Call volume with a high volumeOpenInterestRatio on an out-of-the-money strike just days before earnings, it suggests an expectation of a positive surprise.

Merger and Acquisition (M&A) Rumors

M&A events are often preceded by information leakage. A sudden spike in volume for Call options on a typically quiet stock can be a precursor to a buyout announcement. By programmatically monitoring the GET /v1/markets/options/unusual-options-activity endpoint, you can alert yourself to these anomalies in real-time.

Conclusion

Detecting unusual options activity allows you to follow institutional footprints in the market. By integrating the Mboum API, you can automate the discovery of these high-volatility opportunities without manually scanning option chains.

To start building your own options analysis tools, get your API key here:
https://mboum.com/pages/api