---
title: "Whale Options: Free Open-Source Options Flow Scanner"
description: "Track unusual options activity on your own machine. Whale Options spots sweeps, blocks, and split orders in live options flow and shows the math behind every score. Free, open source, no telemetry."
canonical: https://www.luxalgo.com/whale-options/
---

# Whale Options: Free Open-Source Options Flow Scanner

> Track unusual options activity on your own machine. Whale Options spots sweeps, blocks, and split orders in live options flow and shows the math behind every score. Free, open source, no telemetry.

## Options flow was never magic.

See the size the moment it prints. Whale Options watches every options trade, flags the sweeps, blocks, and split orders that matter, and scores each one with the math shown in full. Free, open source, on your own machine.

## Three shapes of size.

A sweep is urgency, a block is conviction, a split is patience, and the engine never confuses them. Every print is judged against the live quote at the exact moment it happened, and when that quote can’t be trusted it says unknown instead of guessing.

- Sweeps (2+ exchanges · 500 ms): Someone in a hurry: the same order racing across two or more exchanges inside half a second, stitched back together as one event.
- Blocks (99.5th percentile): Size that is huge for this contract, judged against its own recent volume, with floors so quiet names can’t fake it.
- Splits (4+ clips): The same order worked quietly over minutes, in four or more clips. Patience reads differently than urgency, and the engine keeps them apart.

## A score you can audit.

One number, zero to one hundred, built from six ingredients you can see. If an ingredient can’t be measured it says so and drops out; nothing gets hidden in the weighting, and new contracts are flagged as new instead of quietly fudged.

| Component | What it measures | Weight |
| --- | --- | --- |
| volumeVsBaseline | day volume vs its own 20-session average, log-scaled | 0.20 |
| premiumVsBaseline | premium percentile in the underlying’s distribution | 0.20 |
| volOi | day volume over open interest; ratio above 1 flags likely opening flow | 0.15 |
| aggression | how it hit the NBBO: mid 0.2, at-quote 0.7, through-quote 1.0 | 0.20 |
| urgency | short-dated plus out-of-the-money distance | 0.10 |
| repetition | same-contract, same-side recurrence this session | 0.15 |

## The flow, on the tape.

Candles of the underlying, and under them three panes built from every print, not just the ones above the premium floor: net premium with calls and puts split, directional delta, and net volume. Sweeps and blocks sit on the bar where they printed, sized by premium; click one and the same score breakdown the flow table shows opens. A GEX toggle draws the strike ladder against the price axis. Drawn in your browser by Vela™, our open source charting engine.

- Deterministic replay: Same tape plus same config produces a byte-identical event stream, ids included. A tested property, not a slogan.
- The flight recorder: Every tick is self-contained: NBBO, spot, and OI ride along, so any session can be replayed and audited. Replay never re-fires alerts.
- Calibration, with caveats: whale audit measures recorded scores against forward moves of the underlying, never option P&L, and prints its caveats with every report.

## Around the tape.

The context around the prints, computed from your own recorded data, with every assumption stated in the output.

- GEX ladder: Where dealer hedging pressure sits, strike by strike, plus the flip level.
- OI deltas: What actually changed in a chain overnight, contract by contract.
- Max pain: The classic pin level per expiry, labeled as a snapshot, not a prediction.
- IV rank: Is volatility rich or cheap right now, against your own recorded history.
- Net flow: Which names the big money leaned into today, netted per underlying.
- Short volume: Daily short-sale volume from the public FINRA files, cached locally.

## Alerts as plain JSON.

Tell it what matters (ticker, kind, side, score, premium) and it pings you on Discord, Telegram, your desktop, or any webhook. Cooldowns are on by default so it never spams, and every webhook is signed so you can trust what arrives.

```json
{
  "id": "nvda-big-sweeps",
  "match": { "tickers": ["NVDA"], "kind": ["sweep"],
             "minScore": 75, "minPremium": 250000 },
  "sink": { "type": "discord" },
  "cooldownSec": 300
}
```

## Sixteen tools. One tape.

The MCP server runs against your own engine, live or recorded, so an agent can pull the top-scored events with their full breakdowns, open one event’s complete story, or replay a window under a new config and diff what changes.

Local MCP server (`@luxalgo/whale-mcp`, from a clone): `git clone https://github.com/LuxAlgo/whale-options && cd whale-options && pnpm install && pnpm build`

## Keys later. Tape now.

The synthetic feed is a seeded, plausible tape with injected sweeps, blocks, and ladders, so the whole engine runs before you hold any vendor key. Plug in a real feed when you’re ready; servers bind loopback by default.

```bash
git clone https://github.com/LuxAlgo/whale-options
cd whale-options && pnpm install && pnpm build
node packages/cli/dist/index.js run --feed synthetic

# zero keys, synthetic tape, real engine
# dashboard on http://127.0.0.1:8787
```

- Synthetic tape: seeded and deterministic, runs with zero keys (built in)
- Tradier: live options prints (your key)
- ThetaData: live and historical options tape (your key)
- Alpaca: live options prints (your key)
- Massive: flat files from disk (your files)

## Open the detection. It's just tape.

Just tape. All math. MIT-licensed and self-host only: the engine phones home to no one, ever. No hosted mode, no order execution, no win-rate claims. Prints, classifications, and arithmetic, with the work shown.

- GitHub: https://github.com/LuxAlgo/whale-options

Whale Options is an independent project by LuxAlgo, not affiliated with, endorsed by, or derived from any commercial flow platform. Classifications and scores describe prints, not intent; audit returns measure moves of the underlying, never option P&L, and a calibration table is a measurement of one recorded window, not a forecast and not trading advice.

"TradingView" and "Pine Script" are trademarks or registered trademarks
of TradingView, Inc. LuxAlgo is not affiliated with, sponsored by, or
endorsed by TradingView, Inc.

Sitemap: https://www.luxalgo.com/sitemap.xml · Machine-readable index: https://www.luxalgo.com/llms.txt