How to Build an Unusual Options Activity Scanner in Python Using the Mboum API

You can pull one page of unusual options activity in a few lines. A real scanner needs more. It has to page through the list, parse numbers that arrive as strings, and filter by the things you care about: a Vol/OI multiple, how far the strike sits from the stock, how soon the contract expires, and how much premium traded. This tutorial builds that scanner in Python and saves the results to CSV.

What you will build

A script that:

  • Fetches several pages from the Mboum unusual options activity endpoint
  • Parses the formatted strings into numbers
  • Computes moneyness and traded value for each contract
  • Filters by Vol/OI, days to expiration, moneyness and value
  • Writes the survivors to a CSV file

Prerequisites

  • Python 3 and the requests library
  • A Mboum API key (free key)

The endpoint

GET https://api.mboum.com/v1/markets/options/unusual-options-activity has weight 2 per call. Documented parameters are type (STOCKS, ETFS or INDICES), ticker (or symbol), date (a past list, YYYY-MM-DD), price_min and page. Each page holds 20 contracts. The endpoint has no parameters for DTE, moneyness or premium, so the scanner applies those filters itself. See the endpoint docs.

The list is pre-filtered to weekly and monthly contracts expiring within 30 days, with volume of at least 500, open interest of at least 100, a last price of at least $0.10 and Vol/OI of at least 1.24. Your filters narrow it further.

Step 1: fetch pages and parse safely

Numbers arrive as strings such as "2,445" and "151.81%". Some failures return HTTP 200 with a message and no body list, so check the body, not only the status code. Stop paging when a page comes back empty.

import csv
import time
import requests

URL = "https://api.mboum.com/v1/markets/options/unusual-options-activity"
HEADERS = {"Authorization": "Bearer YOUR_MBOUM_API_KEY"}


def num(value):
    return float(str(value).replace(",", "").replace("%", "").replace("+", ""))


def fetch_pages(asset_type="STOCKS", max_pages=3):
    rows, seen = [], set()
    for page in range(1, max_pages + 1):
        resp = requests.get(URL, headers=HEADERS,
                            params={"type": asset_type, "page": page}, timeout=30)
        data = resp.json()
        body = data.get("body")
        if resp.status_code != 200 or not isinstance(body, list) or not body:
            print(f"Stopped at page {page}: {str(data)[:120]}")
            break
        for row in body:
            if row["symbol"] not in seen:
                seen.add(row["symbol"])
                rows.append(row)
        time.sleep(0.2)  # stay well under 10 requests per second
    return rows

Step 2: add moneyness and traded value

The response gives the stock price (baseLastPrice) and the strike (strikePrice), so you can compute moneyness yourself. This version is positive when the contract is in the money and negative when it is out of the money. Traded value is volume × last price × 100 shares per contract.

def moneyness_pct(row):
    spot, strike = num(row["baseLastPrice"]), num(row["strikePrice"])
    diff = spot - strike if row["symbolType"] == "Call" else strike - spot
    return diff / strike * 100


def traded_value(row):
    return num(row["volume"]) * num(row["lastPrice"]) * 100

Step 3: filter

def scan(rows, min_ratio=10, max_dte=5, min_m=-10, max_m=5, min_value=250_000):
    hits = []
    for r in rows:
        m, value = moneyness_pct(r), traded_value(r)
        if (num(r["volumeOpenInterestRatio"]) >= min_ratio
                and num(r["daysToExpiration"]) <= max_dte
                and min_m <= m <= max_m
                and value >= min_value):
            hits.append({
                "symbol": r["symbol"], "type": r["symbolType"],
                "dte": r["daysToExpiration"], "vol_oi": r["volumeOpenInterestRatio"],
                "moneyness_pct": round(m, 1), "value": round(value),
            })
    return sorted(hits, key=lambda h: h["value"], reverse=True)

The defaults keep contracts with Vol/OI of 10 or more, five days or fewer to expiration, a strike between 10% out of the money and 5% in the money, and at least $250,000 of premium traded. Change them to fit your own screen.

Step 4: write the CSV and run it

if __name__ == "__main__":
    hits = scan(fetch_pages(max_pages=3))
    with open("unusual_options.csv", "w", newline="") as f:
        writer = csv.DictWriter(f, fieldnames=["symbol", "type", "dte", "vol_oi", "moneyness_pct", "value"])
        writer.writeheader()
        writer.writerows(hits)
    print(f"{len(hits)} contracts saved")

Scan one ticker or a past date

To scan one underlying, add "ticker": "TSLA" to the request params in fetch_pages. To read a list recorded on an earlier day, add "date": "YYYY-MM-DD". The docs say the volume, open interest and Vol/OI minimums apply when you leave date out, so expect different row counts when you use it. Both options keep the same response shape, so the rest of the script does not change.

The CSV is sorted by traded value, largest first. Treat each row as a lead. Before you act on one, pull its expiration from the options chain endpoint (/v3/markets/options) and check the bid-ask spread. A big print on a wide spread is a poor guide.

Sample response

A trimmed row from the docs example, with the fields the scanner reads:

{
  "symbol": "PANW|20240223|310.00C",
  "baseSymbol": "PANW",
  "baseLastPrice": "261.97",
  "symbolType": "Call",
  "strikePrice": "310.00",
  "daysToExpiration": "1",
  "lastPrice": "0.14",
  "volume": "2,445",
  "openInterest": "119",
  "volumeOpenInterestRatio": "20.55"
}

This row would not survive the filters. Its strike is about 15% out of the money, and 2,445 × $0.14 × 100 is about $34,000 of premium.

Best practices

  • Budget your pages. Every call has weight 2, and only HTTP 200 responses count. Three pages cost 6 requests. A full list is far more, so cap max_pages.
  • Check the body. A 200 response can carry an error message. The script stops when body is not a list.
  • Respect the rate limit. The limit is 10 requests per second, and over it returns HTTP 429. Keep the sleep between pages, and back off on a 429.
  • Remember volume has no side. This list does not say who bought. For sized trades with a side, use the options-flow endpoint.

Next steps

You now have a scanner that pages, parses, filters and exports. Tune the thresholds, then schedule it to run during market hours. This is a screening tool, not investment advice.

Claim your free API key and see the Mboum docs for Python, PHP, JavaScript and Bash samples.