Scanning the unusual options list by hand means refreshing a page and hoping you're looking when something prints. A small script can do the watching. This weekend project polls Mboum's unusual options activity endpoint during market hours, keeps the contracts with a high volume-to-open-interest ratio (Vol/OI), and posts them to a private Discord channel through a webhook.
One note on the word "sweeps". A sweep is a large order split across several exchanges, and this list doesn't show how a trade was executed. It shows contracts where today's volume is high compared with open interest. The bot alerts on that, and it doesn't claim to catch sweeps. For individual large trades with a side and a trade condition, see the options-flow endpoint.
What you will build
- A script that fetches the unusual options activity list once per run
- A filter on Vol/OI, days to expiration and premium traded
- A small state file so the same contract isn't posted again and again
- A Discord webhook message with the survivors
- A schedule that runs it every few minutes during market hours
Prerequisites
- Python 3.9 or newer and the
requestslibrary - A Mboum API key (free key)
- A Discord webhook URL: in your server, open Channel Settings, then Integrations, then Webhooks, and create one for a private channel
Treat the webhook URL like a password. Anyone who has it can post to your channel. Keep both secrets in environment variables, not in the script.
The endpoint
GET https://api.mboum.com/v1/markets/options/unusual-options-activity has weight 2 per call and returns 20 contracts per page. The list covers weekly and monthly contracts expiring in under 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. The bot reads page 1 only, so each run costs 2. See the endpoint docs.
The same list is on the Unusual Options Activity page. Use it to compare what the bot posts with what you see.
The script
Values arrive as strings such as "2,445", so the num() helper cleans them. Some failures return HTTP 200 with a message and no body list, so fetch() checks the body.
import json
import os
import time
from datetime import datetime
from pathlib import Path
from zoneinfo import ZoneInfo
import requests
API_URL = "https://api.mboum.com/v1/markets/options/unusual-options-activity"
API_KEY = os.environ["MBOUM_API_KEY"]
WEBHOOK = os.environ["DISCORD_WEBHOOK_URL"]
STATE = Path("seen.json")
NY = ZoneInfo("America/New_York")
MIN_RATIO, MIN_VALUE, MAX_DTE = 10, 250_000, 5
def num(value):
return float(str(value).replace(",", "").replace("%", "").replace("+", ""))
def market_open(now):
return now.weekday() < 5 and (9, 30) <= (now.hour, now.minute) <= (16, 0)
def fetch():
resp = requests.get(API_URL, headers={"Authorization": f"Bearer {API_KEY}"},
params={"type": "STOCKS"}, timeout=30)
data = resp.json()
body = data.get("body")
if resp.status_code != 200 or not isinstance(body, list):
print(f"No rows: {str(data)[:120]}")
return []
return body
def post_discord(text):
for _ in range(3):
resp = requests.post(WEBHOOK, json={"content": text[:2000]}, timeout=15)
if resp.status_code == 429: # rate limited: wait as long as Discord asks
time.sleep(float(resp.json().get("retry_after", 1)) + 0.5)
continue
return resp.status_code in (200, 204)
return False
def main():
now = datetime.now(NY)
if not market_open(now):
return
seen = json.loads(STATE.read_text()) if STATE.exists() else {}
if seen.get("_day") != now.date().isoformat(): # start fresh each day
seen = {"_day": now.date().isoformat()}
lines = []
for r in fetch():
volume = num(r["volume"])
value = volume * num(r["lastPrice"]) * 100
if (num(r["volumeOpenInterestRatio"]) >= MIN_RATIO
and num(r["daysToExpiration"]) <= MAX_DTE
and value >= MIN_VALUE
and volume >= seen.get(r["symbol"], 0) * 1.5): # new, or volume up 50%
seen[r["symbol"]] = volume
lines.append(f"{r['baseSymbol']} {r['symbolType']} {r['strikePrice']} "
f"exp {r['expirationDate']} | Vol/OI {r['volumeOpenInterestRatio']} "
f"| vol {r['volume']} | ~${value:,.0f} traded")
if lines and post_discord("Unusual options activity\n" + "\n".join(lines[:15])):
STATE.write_text(json.dumps(seen))
if __name__ == "__main__":
main()
Here is how it works:
- Market hours. It exits outside 9:30 AM to 4:00 PM New York time on weekdays. It doesn't know about holidays, so on a closed day it will fetch and find nothing new.
- De-duplication. The state file maps each contract to the volume it last alerted on. A contract alerts again only when its volume is 50% higher. The file resets each day.
- Retry on failure. It saves state only after Discord accepts the message, so a failed post is retried on the next run.
- Webhook details. A message is a JSON body with a
contentfield, up to 2,000 characters. Discord returns 204 on success. A 429 response includesretry_after, which the script respects.
Schedule it
Run the script once every five minutes with cron. The script checks market hours itself, so the schedule can be simple:
*/5 * * * 1-5 MBOUM_API_KEY=your_key DISCORD_WEBHOOK_URL=your_webhook /usr/bin/python3 /path/to/alert_bot.py
Cron uses the server's time zone, but the script converts to New York time itself, so that part is safe. A five-minute schedule means about 78 runs over the 6.5-hour session, or 156 weight if every run gets HTTP 200. Choose the interval to fit your plan. Check how often the list changes before you poll faster, because more runs only help if the data moves.
Sample response
A trimmed row from the docs example, with the fields the bot reads:
{
"symbol": "PANW|20240223|310.00C",
"baseSymbol": "PANW",
"symbolType": "Call",
"strikePrice": "310.00",
"expirationDate": "02/23/24",
"daysToExpiration": "1",
"lastPrice": "0.14",
"volume": "2,445",
"volumeOpenInterestRatio": "20.55"
}
This row would not alert. Its Vol/OI of 20.55 passes, but 2,445 × $0.14 × 100 is about $34,000 of premium, under the $250,000 minimum.
Best practices
- Keep secrets out of code. Use environment variables for the API key and webhook, and never commit them.
- Check the body. A 200 response can carry an error message. The bot logs it and posts nothing.
- Respect the rate limit. The API allows 10 requests per second, and over it returns HTTP 429. Only HTTP 200 responses count toward weight. One request per run is far below that.
- Tune the thresholds. Raise
MIN_VALUEif the channel is noisy. Small contracts with a tiny open interest can show huge ratios, so premium traded is the better filter. - Treat alerts as leads. Volume doesn't show who bought or whether positions opened or closed. Check the chain and the news before you act.
Next steps
Add a ticker allow-list, send an embed instead of plain text, or add a second alert for the options-flow endpoint. This is a research tool, not investment advice.
Claim your free API key and see the Mboum docs for Python, PHP, JavaScript and Bash samples.