Walkthrough · Earnings volatility

Your first scan is twenty minutes away.

You point your AI assistant at one file. It writes the scanner, checks its own arithmetic, and runs a scored pre-earnings screen against your Unusual Whales key. You don't write any code. You copy a few commands and paste one paragraph.

Start the walkthrough Why it might work

start to first scan: ~20 min
lines of code you write: 0
self-checks before any API call: 124

uw_earnings_vol_scan.py --scan

session: 2026-09-01
trade_by: 2026-09-01 (enter before today's close)
counts: 1 recommended · 9 consider · 3 avoid (13 scored)

Ticker	Volume	IV/RV	Slope	Verdict
GTLB	4.12M ✓	1.43 ✓	−0.03469 ✓	Recommended
CRDO	4.68M ✓	0.83 ✗	−0.01804 ✓	Consider
DELL	5.57M ✓	0.90 ✗	−0.01754 ✓	Consider
PANW	5.80M ✓	1.15 ✗	−0.01556 ✓	Consider
FCEL	8.21M ✓	0.85 ✗	−0.01501 ✓	Consider
MDB	1.42M ✗	1.42 ✓	−0.03204 ✓	Consider
OLLI	1.37M ✗	1.51 ✓	−0.00504 ✓	Consider
DAKT	0.43M ✗	2.24 ✓	−0.00632 ✓	Consider
CXM	2.96M ✓	1.39 ✓	−0.00331 ✗	Avoid
YSG	0.08M ✗	1.32 ✓	+0.00343 ✗	Avoid

Real output, 1 September 2026. Abridged to 10 of 13 rows for width.

What you're building, and why

You're getting paid to hold risk nobody else wants.

A company reports after the close. Overnight, with almost nobody trading, the stock can gap hard. So into that print, everyone wants the same thing: holders want protection, speculators want defined-risk leverage. Both are buyers of options.

Almost nobody wants to be on the other side, because being short that risk is genuinely unpleasant. So the near-dated options get bid up, and on average, the move that gets priced in is bigger than the move that actually happens. That gap is the earnings variance risk premium.

It's the same economics as insurance. The premium is not a mispricing anyone can arbitrage away; it's compensation for taking a risk that occasionally hurts. That's also precisely why it can persist, and why it is not free money.

Well documented in the professional literature: Sinclair, Positional Option Trading (2020) ch. 5; Bennett, Trading Volatility (2014) ch. 6.4; Augen, The Volatility Edge in Options Trading (2008) ch. 7.

How the screen decides

Three filters. One of them overrules the others.

No proprietary score. Three published numbers, each with a threshold you can read.

01 · Liquidity

Can you get filled?

At least 1.5M shares traded a day. A stand-in for the thing that really matters: options tight enough that friction doesn't eat the trade.

02 · Richness

Are options expensive?

What the market charges for the next 30 days vs. how much the stock has actually moved. 1.25 or higher means options are priced at least 25% above the stock's own behaviour.

The gate

Is the premium really there?

Options expiring in days must be meaningfully pricier than options six weeks out. No gap, no trade. The verdict is Avoid however good the other two look.

GTLB−0.03469 · PASS

CXM−0.00331 · FAIL

Both from the 1 September scan. The arrows measure the same gap the gate does: near-dated volatility against 45-day. CXM passed both other filters and is still Avoid, because its two expiries are priced almost identically, so there is nothing for a calendar spread to collect.

Curve shapes are drawn to illustrate the comparison. The slope values are the measured figures from that scan.

The walkthrough

Twenty minutes, start to first scan.

Written for Claude (desktop app or Claude Code). The same file works in Cursor and the Codex app. See the note at step 7 about which environments can run the scan themselves.

Before you start

Three things. Budget five extra minutes if you don't have them yet.

Claude

Either the Claude desktop app or Claude Code. Both work; the desktop app is the easier start.

Python

Most Macs already have it. To check, type python3 --version in a terminal (python --version on Windows). A version number means you're set. If not, install it free from python.org.

A UW API key

Free for 7 days. You'll grab it in step 4, so there's no need to fetch it now.

Who does what. The one path worth noticing: your API key goes from you straight into a file on your own disk, and the script reads it from there. It never travels through the chat, so it never lands in a conversation transcript.

1
Open a terminal
you
This is the part that looks like programming and isn't. A terminal is just a window where you type instructions instead of clicking them. It's already on your computer, so you don't install anything.
macOS
Press ⌘ + Space, type Terminal, press Enter.
Windows
Press the ⊞ Win key, type PowerShell, press Enter.
A window opens with a blinking cursor. That's it. Leave it open, because you'll come back to it four times, and each time you're pasting a line someone else already wrote.
2
Make a folder
you
Everything lives together: the scanner, your key, and later your results. Anywhere is fine.
Terminal
```
$ mkdir -p ~/uw-earnings-scan && cd ~/uw-earnings-scan
```
3
Install the Skill
one command
The Skill is a single file holding the strategy, the thresholds, and the scanner source all in one. This drops it where Claude looks for instructions.
macOS / Linux
```
$ curl --create-dirs \
    -o ~/.claude/skills/uw-earnings-vol-scan/SKILL.md \
    https://unusualwhales.com/skills/uw-earnings-vol-scan-skill.md
```
Windows PowerShell
```
PS> curl.exe --create-dirs `
    -o "$env:USERPROFILE\.claude\skills\uw-earnings-vol-scan\SKILL.md" `
    https://unusualwhales.com/skills/uw-earnings-vol-scan-skill.md
```
PowerShell needs curl.exe, because plain curl is an alias for Invoke-WebRequest and ~ won't expand inside the quoted path. Restart your assistant afterwards so it picks the Skill up.
4
Get your key and save it
you
Where to find it: sign in at unusualwhales.com and open your API dashboard. Your key is there. If you don't have one yet, start the 7-day free trial first. It takes a couple of minutes.
Where to put it: back in your terminal window, paste the command below and press Enter. It asks for your key, then writes it into a file called .env inside the folder you just made. The scanner reads it from there. Never paste your key into the Claude chat window.
macOS / Linux
```
$ printf 'Paste your UW API key: ' \
    && read -rs K && echo \
    && printf 'UW_API_KEY=%s\n' "$K" > .env \
    && chmod 600 .env && unset K \
    && printf '.env\n' > .gitignore
```
Windows PowerShell
```
PS> $sec = Read-Host "Paste your UW API key" -AsSecureString
PS> $K = [System.Net.NetworkCredential]::new('', $sec).Password
PS> "UW_API_KEY=$K" | Set-Content -Encoding ascii .env
PS> ".env" | Set-Content -Encoding ascii .gitignore
PS> Remove-Variable K, sec
```
Nothing will appear on screen when you paste. That's correct.
After you press Enter the cursor just sits there waiting. Paste your key and press Enter again. You will see no characters, no dots, no movement, because the terminal hides it on purpose so it can't be read over your shoulder or recovered from your command history. It worked. Keep going.
.env starts with a dot, which means your file browser hides it by default. That's normal, and the scanner can still see it.
5
Point Claude at the folder
you
Claude can only read and write where you let it. Give it the folder from step 2 and it can save the scanner there and read your key. Without that, it will tell you it can't find the file.
Claude Code
Your terminal is already sitting in the folder, so just type claude and press Enter. It starts up with that folder already available.
Claude desktop app
In the message box switch from Chat to Cowork, then click Project or folder and pick the folder you made in step 2. An ordinary chat cannot see your files.
Not sure it worked? Ask Claude “what files can you see in this folder?” and it should list .env. If it can't see anything, the folder wasn't added.
6
Hand your assistant the prompt
you
Open Claude in that folder and paste this. It points at the file you just downloaded, so no network is needed to read it, and asks the assistant to explain the method back to you before it builds and runs the scanner.
Paste into Claude
I have the Unusual Whales earnings-vol-scan Skill installed locally at ~/.claude/skills/uw-earnings-vol-scan/SKILL.md (on Windows: %USERPROFILE%\.claude\skills\uw-earnings-vol-scan\SKILL.md). It identifies opportunities to short earnings volatility in a risk-defined way. Read that local file in full. It is 2000+ lines, so do not stop partway. Then interactively work through these steps with me: (1) provide a short summary explaining why this strategy might have a durable edge, (2) concisely explain the filtering techniques it uses with as little jargon as possible, then (3) stand up and run the scanner the Skill provides, confirm its selftest passes, then review the returned trade ideas with me.
Ask questions at each step. The point of steps 1 and 2 in that prompt is that you understand the screen before you trade off it.
7
Watch it check its own work
automatic
Before a single network call, the scanner runs 124 internal checks: its volatility maths against an independent reference implementation to twelve decimal places, every row of the verdict logic, and the market-holiday calendar, so a trading deadline never lands on a day the exchange is shut.
--selftest · 0 API calls
```
$ python3 uw_earnings_vol_scan.py --selftest

selftest: 124/124 checks passed
All checks passed with zero API calls. Safe to scan.
```
On Windows the command is python, not python3, and that applies to every command from here on.
If your assistant says it can't reach the API
This is the most common snag, and it isn't your key. Some environments block outbound network by policy. claude.ai's analysis sandbox, ChatGPT's Code Interpreter, and Custom GPTs cannot reach the API at all. The scanner detects this and says so rather than blaming your subscription.
The fix: run the command yourself in Terminal, in the folder from step 2, and paste the output back to your assistant to interpret. Everything still works, and you're just supplying the network. Claude Code and the Codex desktop app can usually run it in place.
A 403 mentioning Cloudflare or “Error 1010” is also not an auth problem. It's an upstream block that happens before the API ever sees your key.

Run tonight's scan

you

One command. It pulls every company reporting after tonight's close or before the next session's open, scores each one, and sorts them.

Terminal

$ python3 uw_earnings_vol_scan.py --scan

session: 2026-09-01
trade_by: 2026-09-01 (every name below; enter before today's close)
counts: 1 recommended, 9 consider, 3 avoid (13 scored)
skipped: 1 of 14
  GTLB,2026-09-01 PM,Recommended,4117321,PASS,1.43,PASS,-0.03469,PASS,13.4%
  ...

Add --rich for a colour table you can screenshot. Add --days 5 to look ahead, but read the warning about that in step 9.

9
Read the verdicts
with your assistant
Three labels, and the middle one is doing more work than it looks like it is.
- Recommended. Passed all three filters. It means exactly that and nothing more.
- Consider. Passed the gate plus one of the other two. Worth understanding which one failed; the output tells you.
- Avoid. Failed the term-structure gate, or failed both quality filters.
“Recommended” is a label, not a recommendation
It is a statistical screen result, not advice and not an endorsement. Before trading any name you still have to check the option chain for a tradeable strike with real open interest and a tight spread, skim the news for anything that distorts a calendar, and size it against your own account.
Also read the skipped list. On 1 September one name was dropped for having no usable options curve. The scanner reports what it couldn't score and why, instead of quietly shrinking the table.

Doing it every day

The routine is about twenty minutes an afternoon.

The scan is only meaningful in a narrow window, and the trade has a fixed shape.

The edge lives entirely in the shaded band. Hold past the next morning and you're no longer betting that the implied move was overpriced. You're just holding a position that needs the stock to sit still.

Four things that matter

Run it in the afternoon, not the morning. Options reprice all day. A name that clears the filters at 10am can fail by 3pm.
Re-check before you enter. --ticker GTLB costs two API calls and confirms the numbers still hold.
Don't hold past the next morning. Close it 5-30 minutes after the open, not at the bell, when spreads are widest.
Watch total exposure, not just per-trade size. Some sessions produce seven Recommended names that all enter the same afternoon and share the same macro risk.

Before you size anything

The research, including the losses.

The three thresholds come from a published backtest of US equity earnings, 2007-2024. Here is its whole distribution.

Backtest · not a forecast

7,313 trades · US equity earnings 2007-2024 · hypothetical results

Distribution of per-trade returns

Return as a percentage of the amount risked. Losses left of zero, gains right.

mean per trade: +7.28%
standard deviation: 28.6%
of events passed the filters: 10.8%
trades in the sample: 7,313

The same distribution as a table.
	Statistic	Per-trade return
	Worst trade	−107.14%
	25th percentile	−6.28%
	Median	+11.15%
	Mean	+7.28%
	75th percentile	+26.42%
	Best trade	+78.84%

Source: the backtest published on the Volatility Vibes YouTube channel, youtube.com/watch?v=oW6MHjzxHpU. Worth the 19 minutes. Hypothetical performance shown for illustration only; it reflects one historical sample and one set of assumptions, is not a projection, and does not indicate future results. As with any single published backtest, validate the logic against your own data before committing capital.

Bonus · not part of the Skill

Grading yesterday's picks.

The natural next thing to build. It's also where most trade journals quietly go wrong, so it's worth being careful about what you can actually measure.

Every afternoon the scanner tells you what cleared the filters. The obvious follow-up is to open it the next morning and ask whether it was right. But the API never sees your fills. It doesn't know what you paid for the spread or what you closed it for, so it cannot compute your P&L. Any grader that claims to is making numbers up.

What it can do is grade the thesis, which is a different and arguably more useful question.

Measurable from the API

Was the premium really overpriced?

Implied vs realised move. The scan recorded an expected move; the next day's bar shows what actually happened.
Front-expiry IV, before and after. Re-pull the term structure. Did it collapse?
Slope normalisation. Did the backwardation flatten out, as the structure needs it to?

Only you can supply

What the trade actually did

Your entry debit and exit credit, per contract.
Which strike and expirations you actually got filled on.
Fees and slippage. Four spread crossings over the life of the trade.

Keep these in a file you maintain by hand. Never let the grader estimate them.

Why P&L alone is a bad teacher. A correct read can lose money and a broken one can win, so judging a handful of trades by their outcome trains the wrong instinct. Separating the two columns from the two rows is the entire point of keeping the log.

What you'd actually build

A row per entered trade, appended each morning. Three columns from the API, three from your broker, and a quadrant label. Something like this, pasted to your assistant:

A starting point

Using the same Unusual Whales Skill, build me a grader for yesterday's entries. For each ticker in my entries file, re-pull today's term structure and daily bar and report: (1) the expected move recorded at scan time vs the move that actually realised overnight, (2) front-expiry implied volatility before and after the print, (3) the term-structure slope before and after. Read my actual entry and exit prices from fills.csv, which I maintain by hand. Never estimate or infer a fill price, and if a row is missing, say so and leave the P&L blank. Label each trade by quadrant: did the volatility crush as predicted, and separately, did the trade make money. Finish with a reminder of how many closed trades I have, and state plainly that the sample is too small to draw conclusions from below about 30.

None of this ships with the Skill today. It's a sketch of how you'd extend it, and the same two endpoints you already use will do the work. If you build it, grade the thesis and the P&L in separate columns and never let one stand in for the other.

All of this runs on an API key, and 7 days are free.

The Skill, the scanner, the 124 self-checks, every step on this page, all free, all yours to read. The one thing you need is a key, and the first 7 days are free.

Start 7 days free Read the Skill first See the dashboard project

7-day free trial. A credit card is required to start. Cancel any time within the 7 days and you pay nothing; if you don't cancel, it converts to a paid API plan automatically.