custom alerts demo
In [1]:
import os
import requests
import polars as pl
from datetime import datetime
from rich import print as rprint
The newly-added "alerts" endpoints give us access to all the Custom Alerts associated with our account:
https://api.unusualwhales.com/docs#/operations/PublicApi.AlertsController.alerts
But we can also reach the "configs" endpoint, which will give us some details about the existing Custom Alerts:
https://api.unusualwhales.com/docs#/operations/PublicApi.AlertsController.configs
Let's try the "configs" endpoint first to get a better idea about which Custom Alerts we want to selectively bring back:
In [2]:
uw_token = os.environ['UW_TOKEN']
headers = {'Accept': 'application/json, text/plain', 'Authorization': uw_token}
In [3]:
configs_url = r'https://api.unusualwhales.com/api/alerts/configuration'
configs_rsp = requests.get(configs_url, headers=headers)
configs_rsp.status_code
Out[3]:
200
Cool, configs_rsp.json() gives us a collection of
dictionaries describing the Custom Alerts like this:
{'data': [{'config': {'issue_types': ['Common Stock', 'ADR', 'ETF'],
'max_multileg_volume_ratio': 0.2,
'min_bid_perc': 0.8,
'min_dte': 6,
'min_premium': 250000,
'minute': [10],
'symbols': 'all',
'type': 'put',
'vol_greater_oi': True},
'created_at': '2024-12-16T16:07:23Z',
'id': '9657ed04-81c4-4bfe-8a46-47013b3c4356',
'mobile_only': False,
'name': '250K Put Seller Stock or ETF Custom Alert',
'noti_type': 'option_contract_interval',
'status': 'active'},
...
{'config': {'interval_opening_flow': True,
'is_otm': True,
'issue_types': ['Common Stock', 'ADR'],
'max_ask_perc': 1,
'max_dte': '183',
'max_iv': 1,
'max_multileg_volume_ratio': 0.1,
'min_ask_perc': 0.8,
'min_dte': '6',
'min_premium': '500000',
'minute': [5],
'symbols': 'all',
'type': 'call'},
'created_at': '2024-12-12T01:36:33Z',
'id': 'a98f6c2b-25b6-4b60-a42f-e92aa9d77690',
'mobile_only': False,
'name': '500K OTM Call Buyer Custom Alert',
'noti_type': 'option_contract_interval',
'status': 'active'}]}
Fortunately polars can accomodate this kind of "nested" format,
so I'm just going to pull the entire response into a DataFrame
then drop the config sub-dictionary:
In [4]:
pl.Config.set_fmt_str_lengths(100)
raw_configs_df = pl.DataFrame(configs_rsp.json()['data'])
desired_columns = ['name', 'id', 'status', 'noti_type', 'created_at']
configs_df = (
raw_configs_df.select(desired_columns)
)
configs_df
Out[4]:
shape: (6, 5)
| name | id | status | noti_type | created_at |
|---|---|---|---|---|
| str | str | str | str | str |
| "500K OTM Call Buyer Custom Alert" | "a98f6c2b-25b6-4b60-a42f-e92aa9d77690" | "active" | "option_contract_interval" | "2024-12-20T05:36:07Z" |
| "250K Put Seller Stock or ETF Custom Alert" | "9657ed04-81c4-4bfe-8a46-47013b3c4356" | "active" | "option_contract_interval" | "2024-12-16T16:07:23Z" |
| "3X over 30d avg option volume Call emphasis $100K" | "ec5bb6b0-6f21-4311-bcca-54b1314eeb93" | "active" | "stock" | "2024-10-22T21:25:01Z" |
| "Low Volume 3x Avg 10K Bets" | "2bb448e5-ed87-4015-9ec8-def1d7fff30a" | "active" | "stock" | "2024-10-08T04:27:18Z" |
| "ITM Put Sellers in Industrial Metals and Sand WL" | "357df1a6-347a-489f-bd26-69b0df42ad39" | "active" | "option_contract" | "2023-11-13T05:26:56Z" |
| "For ON when there is an option contract" | "a1dd5f42-b9a6-4b74-beb2-4e1fadd0de7d" | "active" | "option_contract" | "2023-11-13T05:03:58Z" |
The first Custom Alert in the group, "250K Put Seller Stock or ETF Custom Alert", is potentially quite interesting given the context: today is Thursday Dec 19th, 2024. Yesterday was an FOMC day and the SPY was down a horrendous -2.98% with the VIX trading up from its previous close of 15.88 to 27.61... suffice it to say yesterday was about as textbook a correlation 1.0 sell-off as you could ask for.
Let's examine the trades that were flagged yesterday to see
where market participants were "rushing into a burning building"
to sell Puts in size by obtaining the id associated
with this Custom Alert then hitting the Alerts endpoint:
https://api.unusualwhales.com/docs#/operations/PublicApi.AlertsController.alerts
In [5]:
put_seller_id = (
configs_df
.filter(pl.col('name') == '250K Put Seller Stock or ETF Custom Alert')
.select('id')
.item()
)
alerts_url = f'https://api.unusualwhales.com/api/alerts'
alerts_params = {
'config_ids[]': put_seller_id,
'limit': 200
}
alerts_rsp = requests.get(alerts_url, headers=headers, params=alerts_params)
alerts_rsp.status_code
Out[5]:
200
Nice, now alerts_rsp.json() gives us a collection
of alert dictionaries like this:
{'data': [{'created_at': '2024-12-19T16:16:36Z',
'id': 'c44fafce-b07f-4f15-980f-c102a62f637e',
'meta': {'ask_volume': 0,
'avg_fill': '6.1000',
'bid_volume': 614,
'close': '6.10',
'diff': '-0.3646',
'minute': 10,
'multi_leg_vol_ratio': '0',
'open_interest': 2,
'rounded_tape_time': 1734624600000,
'total_premium': '374543',
'underlying_symbol': 'IREN',
'vol_oi_ratio': '307',
'volume': 614},
'name': '250K Put Seller Stock or ETF Custom Alert',
'noti_type': 'option_contract_interval',
'symbol': 'IREN250718P00016000',
'symbol_type': 'option_chain',
'tape_time': '2024-12-19T16:16:34Z',
'user_noti_config_id': '9657ed04-81c4-4bfe-8a46-47013b3c4356'},
...
{'created_at': '2024-12-16T16:16:42Z',
'id': 'b518e9f3-dfe1-406b-89b8-261c606bc6fc',
'meta': {'ask_volume': 49,
'avg_fill': '8.2976',
'bid_volume': 274,
'close': '8.30',
'diff': '0.3020',
'minute': 10,
'multi_leg_vol_ratio': '0.1300',
'open_interest': 140,
'rounded_tape_time': 1734365400000,
'total_premium': '268013',
'underlying_symbol': 'IONQ',
'vol_oi_ratio': '2.3071',
'volume': 323},
'name': '250K Put Seller Stock or ETF Custom Alert',
'noti_type': 'option_contract_interval',
'symbol': 'IONQ260116P00025000',
'symbol_type': 'option_chain',
'tape_time': '2024-12-16T16:16:41Z',
'user_noti_config_id': '9657ed04-81c4-4bfe-8a46-47013b3c4356'}]}
OK this time we actually need to do a bit of nested dictionary unfolding to end up with the best polars DataFrame possible, so let's get to it:
In [6]:
flattened_json = [
{
**{k: v for k, v in d.items() if k != 'meta'},
**{f'alert_{k}': v for k, v in d['meta'].items()}
} for d in alerts_rsp.json()['data']
]
flattened_json[0]
Out[6]:
{'created_at': '2024-12-19T21:10:47Z',
'id': 'ebd031b9-6139-4ae4-9c99-70dafff592a4',
'name': '250K Put Seller Stock or ETF Custom Alert',
'noti_type': 'option_contract_interval',
'symbol': 'EWZ250117P00031000',
'symbol_type': 'option_chain',
'tape_time': '2024-12-19T21:10:34Z',
'user_noti_config_id': '9657ed04-81c4-4bfe-8a46-47013b3c4356',
'alert_ask_volume': 0,
'alert_avg_fill': '7.10',
'alert_bid_volume': 7557,
'alert_close': '7.10',
'alert_diff': '-0.3561',
'alert_minute': 10,
'alert_multi_leg_vol_ratio': '0',
'alert_open_interest': 3504,
'alert_rounded_tape_time': 1734642600000,
'alert_total_premium': '5365470',
'alert_underlying_symbol': 'EWZ',
'alert_vol_oi_ratio': '2.1567',
'alert_volume': 7557}
Much better... now let's compile all these custom alerts into a single DataFrame for additional transformation and analysis:
In [7]:
pl.Config.set_fmt_str_lengths(50)
raw_alerts_df = pl.DataFrame(flattened_json)
raw_alerts_df.head(5)
Out[7]:
shape: (5, 21)
| created_at | id | name | noti_type | symbol | symbol_type | tape_time | user_noti_config_id | alert_ask_volume | alert_avg_fill | alert_bid_volume | alert_close | alert_diff | alert_minute | alert_multi_leg_vol_ratio | alert_open_interest | alert_rounded_tape_time | alert_total_premium | alert_underlying_symbol | alert_vol_oi_ratio | alert_volume |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| str | str | str | str | str | str | str | str | i64 | str | i64 | str | str | i64 | str | i64 | i64 | str | str | str | i64 |
| "2024-12-19T21:10:47Z" | "ebd031b9-6139-4ae4-9c99-70dafff592a4" | "250K Put Seller Stock or ETF Custom Alert" | "option_contract_interval" | "EWZ250117P00031000" | "option_chain" | "2024-12-19T21:10:34Z" | "9657ed04-81c4-4bfe-8a46-47013b3c4356" | 0 | "7.10" | 7557 | "7.10" | "-0.3561" | 10 | "0" | 3504 | 1734642600000 | "5365470" | "EWZ" | "2.1567" | 7557 |
| "2024-12-19T21:10:47Z" | "fa54357d-0d51-4064-b295-245dfc16bfbc" | "250K Put Seller Stock or ETF Custom Alert" | "option_contract_interval" | "EWZ250117P00030000" | "option_chain" | "2024-12-19T21:10:34Z" | "9657ed04-81c4-4bfe-8a46-47013b3c4356" | 0 | "5.85" | 1563 | "5.85" | "-0.3123" | 10 | "0" | 770 | 1734642600000 | "914355" | "EWZ" | "2.0299" | 1563 |
| "2024-12-19T21:10:47Z" | "5b3a0939-60eb-43ca-9cfe-ce20495574d4" | "250K Put Seller Stock or ETF Custom Alert" | "option_contract_interval" | "EWZ250321P00032000" | "option_chain" | "2024-12-19T21:10:34Z" | "9657ed04-81c4-4bfe-8a46-47013b3c4356" | 0 | "8.10" | 20722 | "8.10" | "-0.3998" | 10 | "0" | 10001 | 1734642600000 | "16784820" | "EWZ" | "2.0720" | 20722 |
| "2024-12-19T20:56:33Z" | "9c6a3d1e-e79e-4047-9351-619e28e8e7b6" | "250K Put Seller Stock or ETF Custom Alert" | "option_contract_interval" | "TOL250117P00155000" | "option_chain" | "2024-12-19T20:56:32Z" | "9657ed04-81c4-4bfe-8a46-47013b3c4356" | 0 | "30.90" | 306 | "30.90" | "-0.2537" | 10 | "0" | 225 | 1734641400000 | "945540" | "TOL" | "1.36" | 306 |
| "2024-12-19T20:52:40Z" | "929718d6-aaf9-48f2-8476-698b3ca6d106" | "250K Put Seller Stock or ETF Custom Alert" | "option_contract_interval" | "DOW250117P00060000" | "option_chain" | "2024-12-19T20:52:39Z" | "9657ed04-81c4-4bfe-8a46-47013b3c4356" | 0 | "20.30" | 590 | "20.30" | "-0.5302" | 10 | "0" | 289 | 1734641400000 | "1197700" | "DOW" | "2.0415" | 590 |
OK, let's parse these results into a concise message for the trading floor, maybe something like this:
Opening Put Seller: 3095x SPY 566P 2/28/2025 (64dte 3.74% OTM) @ -9.4828 avg for $2.94M credit at 11:09AM
Let's get to it:
In [8]:
def format_total_premium(x: int) -> str:
if x >= 1_000_000:
return f'${x/1_000_000:.1f}M'
elif x >= 1_000:
return f'${x/1_000:.1f}K'
else:
return f'${x:.0f}'
alerts_df = (
raw_alerts_df
.with_columns(
pl.col('symbol').str.slice(-8).cast(pl.Float64).alias('raw_strike_price')
)
.with_columns(
(pl.col('raw_strike_price') / 1000).cast(pl.String).str.replace(r'\.0', '').alias('strike_price_str')
)
.with_columns(
pl.col('symbol').str.slice(-15, 6).str.strptime(pl.Date, '%y%m%d').alias('expiration_dt')
)
.with_columns(
(pl.col('expiration_dt') - pl.lit(datetime.today().date())).alias('dte')
)
.with_columns(
(pl.col('dte').dt.total_milliseconds() / (24 * 60 * 60 * 1000)).cast(pl.Int64).alias('dte_days')
)
.with_columns(
(pl.col('alert_diff').cast(pl.Float64) * 100).round(1).alias('alert_diff_rounded')
)
.with_columns(
pl.when(pl.col('alert_diff_rounded') > 0)
.then(pl.concat_str([pl.col('alert_diff_rounded'), pl.lit('% OTM')]))
.otherwise(pl.concat_str([pl.col('alert_diff_rounded').abs(), pl.lit('% ITM')]))
.alias('pct_moneyness_str')
)
.with_columns(
pl.col('alert_avg_fill').cast(pl.Float64).round(2).alias('alert_avg_fill_rounded')
)
.with_columns(
pl.col('alert_total_premium').cast(pl.Int64).map_elements(format_total_premium).alias('formatted_total_premium')
)
.with_columns(
pl.col('tape_time').str.strptime(pl.Datetime, '%Y-%m-%dT%H:%M:%S%.fZ').alias('tape_time_dt')
)
.with_columns(
pl.col('tape_time_dt').dt.convert_time_zone('America/New_York').alias('tape_time_tz_dt')
)
.with_columns(
pl.col('tape_time_tz_dt').dt.strftime('%I:%M %p').alias('tape_time_tz_str')
)
.with_columns(
pl.concat_str(
[
pl.lit('Opening Put Seller: '),
pl.col('alert_volume').cast(pl.String),
pl.lit('x '),
pl.col('alert_underlying_symbol'),
pl.lit(' '),
pl.col('strike_price_str'),
pl.lit('P '),
pl.col('expiration_dt').dt.strftime('%m/%d/%Y'),
pl.lit(' ('),
pl.col('dte_days').cast(pl.String),
pl.lit('dte, '),
pl.col('pct_moneyness_str'),
pl.lit(') @ avg '),
pl.col('alert_avg_fill_rounded').cast(pl.String),
pl.lit(' for '),
pl.col('formatted_total_premium'),
pl.lit(' credit at '),
pl.col('tape_time_tz_str')
],
separator=''
).alias('message')
)
)
messages = alerts_df['message'].to_list()
rprint(messages[0:10]) # print the 10 most recent alerts as a "spot check"
[ 'Opening Put Seller: 7557x EWZ 31P 01/17/2025 (28dte, 35.6% ITM) @ avg 7.1 for $5.4M credit at 04:10 PM', 'Opening Put Seller: 1563x EWZ 30P 01/17/2025 (28dte, 31.2% ITM) @ avg 5.85 for $914.4K credit at 04:10 PM', 'Opening Put Seller: 20722x EWZ 32P 03/21/2025 (91dte, 40.0% ITM) @ avg 8.1 for $16.8M credit at 04:10 PM', 'Opening Put Seller: 306x TOL 155P 01/17/2025 (28dte, 25.4% ITM) @ avg 30.9 for $945.5K credit at 03:56 PM', 'Opening Put Seller: 590x DOW 60P 01/17/2025 (28dte, 53.0% ITM) @ avg 20.3 for $1.2M credit at 03:52 PM', 'Opening Put Seller: 530x DOW 65P 01/17/2025 (28dte, 65.8% ITM) @ avg 25.3 for $1.3M credit at 03:52 PM', 'Opening Put Seller: 2460x DOW 50P 01/17/2025 (28dte, 27.5% ITM) @ avg 10.3 for $2.5M credit at 03:52 PM', 'Opening Put Seller: 730x DOW 52.5P 01/17/2025 (28dte, 33.9% ITM) @ avg 12.6 for $919.8K credit at 03:52 PM', 'Opening Put Seller: 157x COIN 220P 01/15/2027 (756dte, 20.1% OTM) @ avg 64.05 for $1.0M credit at 03:39 PM', 'Opening Put Seller: 400x DELL 125P 01/24/2025 (35dte, 11.2% ITM) @ avg 14.14 for $565.6K credit at 03:39 PM' ]
Hmm... Lots of very deep ITM Put selling here, which is potentially more of an arb strategy and less of a directional bet. Let's filter out the extremely deep ITM (say more than 10% ITM) Put Sellers and send the messages again:
In [9]:
filtered_df = (
alerts_df
.filter(pl.col('alert_diff_rounded') > -10)
)
filtered_messages = filtered_df['message'].to_list()
rprint(filtered_messages[0:40]) # print the last 40 alerts to demonstrate the interesting trades that show up
[ 'Opening Put Seller: 157x COIN 220P 01/15/2027 (756dte, 20.1% OTM) @ avg 64.05 for $1.0M credit at 03:39 PM', 'Opening Put Seller: 6020x IWM 209P 01/17/2025 (28dte, 5.1% OTM) @ avg 2.71 for $1.6M credit at 03:35 PM', 'Opening Put Seller: 30x MELI 1540P 01/16/2026 (392dte, 7.8% OTM) @ avg 175.3 for $525.9K credit at 03:35 PM', 'Opening Put Seller: 1408x XLE 80P 02/21/2025 (63dte, 4.4% OTM) @ avg 1.79 for $252.0K credit at 03:26 PM', 'Opening Put Seller: 256x ACN 350P 06/20/2025 (182dte, 6.2% OTM) @ avg 14.99 for $383.7K credit at 03:23 PM', 'Opening Put Seller: 372x WFC 70P 01/16/2026 (392dte, 1.2% ITM) @ avg 8.15 for $303.2K credit at 03:22 PM', 'Opening Put Seller: 254x COR 220P 06/20/2025 (182dte, 2.9% OTM) @ avg 10.1 for $256.5K credit at 03:15 PM', 'Opening Put Seller: 170x PANW 180P 08/15/2025 (238dte, 5.1% OTM) @ avg 15.5 for $263.5K credit at 03:13 PM', 'Opening Put Seller: 2500x WMT 75P 12/18/2026 (728dte, 20.1% OTM) @ avg 3.73 for $932.5K credit at 02:45 PM', 'Opening Put Seller: 475x PANW 185P 02/21/2025 (63dte, 2.8% OTM) @ avg 9.4 for $446.5K credit at 02:35 PM', 'Opening Put Seller: 700x C 65P 01/15/2027 (756dte, 5.3% OTM) @ avg 7.65 for $535.5K credit at 02:16 PM', 'Opening Put Seller: 385x TSLA 430P 07/18/2025 (210dte, 0.8% OTM) @ avg 77.5 for $3.0M credit at 02:13 PM', 'Opening Put Seller: 152x APP 320P 01/03/2025 (14dte, 0.3% OTM) @ avg 17.9 for $272.1K credit at 02:02 PM', 'Opening Put Seller: 1895x SLV 26P 07/18/2025 (210dte, 1.8% OTM) @ avg 1.66 for $314.6K credit at 01:57 PM', 'Opening Put Seller: 830x KRE 59P 03/21/2025 (91dte, 1.9% OTM) @ avg 3.05 for $253.2K credit at 01:40 PM', 'Opening Put Seller: 186x MSTR 220P 04/17/2025 (118dte, 32.6% OTM) @ avg 26.12 for $485.8K credit at 01:13 PM', 'Opening Put Seller: 400x UNP 215P 05/16/2025 (147dte, 4.1% OTM) @ avg 8.45 for $338.0K credit at 01:07 PM', 'Opening Put Seller: 1432x VST 130P 12/27/2024 (7dte, 5.5% OTM) @ avg 2.2 for $315.0K credit at 12:57 PM', 'Opening Put Seller: 100x MSTR 342.5P 12/27/2024 (7dte, 3.0% ITM) @ avg 25.27 for $252.7K credit at 12:57 PM', 'Opening Put Seller: 349x XLY 230P 03/21/2025 (91dte, 1.0% ITM) @ avg 10.81 for $377.2K credit at 12:46 PM', 'Opening Put Seller: 923x SPY 580P 12/26/2024 (6dte, 1.4% OTM) @ avg 3.11 for $286.7K credit at 12:45 PM', 'Opening Put Seller: 275x META 600P 12/18/2026 (728dte, 0.6% OTM) @ avg 99.0 for $2.7M credit at 12:20 PM', 'Opening Put Seller: 329x SPY 587P 02/21/2025 (63dte, 0.4% OTM) @ avg 13.46 for $442.9K credit at 12:15 PM', 'Opening Put Seller: 255x FSLR 125P 12/19/2025 (364dte, 30.4% OTM) @ avg 9.9 for $252.4K credit at 12:12 PM', 'Opening Put Seller: 3000x TLT 91P 01/31/2025 (42dte, 3.5% ITM) @ avg 3.39 for $1.0M credit at 12:07 PM', 'Opening Put Seller: 290x AVGO 200P 01/15/2027 (756dte, 8.8% OTM) @ avg 31.5 for $913.5K credit at 12:01 PM', 'Opening Put Seller: 557x SBUX 91P 01/31/2025 (42dte, 1.2% ITM) @ avg 4.5 for $250.4K credit at 11:37 AM', 'Opening Put Seller: 553x SOUN 20P 02/21/2025 (63dte, 9.4% ITM) @ avg 5.95 for $329.3K credit at 11:26 AM', 'Opening Put Seller: 3095x SPY 566P 02/28/2025 (70dte, 3.7% OTM) @ avg 9.48 for $2.9M credit at 11:09 AM', 'Opening Put Seller: 2422x BE 21P 01/17/2025 (28dte, 5.0% OTM) @ avg 1.42 for $343.9K credit at 11:04 AM', 'Opening Put Seller: 1191x ALLY 32P 06/20/2025 (182dte, 7.9% OTM) @ avg 2.11 for $251.2K credit at 10:59 AM', 'Opening Put Seller: 392x PYPL 90P 01/16/2026 (392dte, 3.6% ITM) @ avg 13.0 for $509.6K credit at 10:34 AM', 'Opening Put Seller: 1003x TSLA 380P 01/31/2025 (42dte, 15.6% OTM) @ avg 16.0 for $1.6M credit at 10:14 AM', 'Opening Put Seller: 770x TLT 91P 01/24/2025 (35dte, 3.5% ITM) @ avg 3.32 for $255.7K credit at 10:11 AM', 'Opening Put Seller: 759x MSFT 415P 01/31/2025 (42dte, 5.7% OTM) @ avg 5.41 for $410.5K credit at 10:09 AM', 'Opening Put Seller: 9260x BSX 82.5P 01/17/2025 (28dte, 6.4% OTM) @ avg 0.6 for $555.7K credit at 10:08 AM', 'Opening Put Seller: 311x MSFT 440P 08/15/2025 (238dte, 0.0% ITM) @ avg 30.35 for $943.9K credit at 10:04 AM', 'Opening Put Seller: 1000x KWEB 30P 09/19/2025 (273dte, 0.2% OTM) @ avg 3.0 for $300.0K credit at 09:58 AM', 'Opening Put Seller: 371x SPY 562P 02/28/2025 (70dte, 4.9% OTM) @ avg 7.4 for $274.5K credit at 09:52 AM', 'Opening Put Seller: 3368x SLV 27P 01/03/2025 (14dte, 2.2% ITM) @ avg 0.81 for $272.8K credit at 09:52 AM' ]