Loading the page…
Loading the page…
Companies often have news on a known date: the FDA ruling on a drug, a quarterly earnings report. In the days before, some traders buy options, contracts that pay off if the stock moves a lot. A call pays if the stock rises; a put pays if it falls.
Foreshadow looks at the five trading days before each piece of news and asks: was the betting unusual for this stock? It compares those five days with the same stock's previous 60, gives the betting a score from 0 to 100, and notes which way the bets leaned. After the news, it checks whether the stock moved further than options traders expected, in the direction the bets pointed. If so, the bets were right.
The data comes from Unusual Whales. The scoring is plain arithmetic, so anyone can repeat it. Claude, an AI model, only writes the short summaries and answers questions. It never sets a score.
For people who want the exact method, data sources and API.
Every signal becomes a z-score of the footprint window against the ticker's own baseline, so a sleepy biotech and a mega-cap are comparable. Each z is clipped to [0, 4], scaled to 0–1, weighted and summed:
Score = Σ_i w_i · min( max(z_i, 0) / 4, 1 ) · 100
Below 40 is ordinary, 40 to 70 is unusual, 70+ is very unusual. Direction is the sign of z(directional premium) + 2·OI imbalance − z(skew shift); within ±0.5 it is “mixed”. Dollar metrics are log1p-transformed before the z so one mega-print can't dominate, and every baseline gets a small standard-deviation floor so a near-constant history can't turn a bump into an infinite z.
Move a measurement and watch its points change. The presets are real cases.
Each slider is how far that measurement sat above the stock's normal, in units of its usual spread (volume is a percentile). Anything past 4 counts the same as 4, so one wild measurement can't carry the score.
| Signal | UW source | What is computed | Weight |
|---|---|---|---|
| Flow-alert intensity | /api/option-trades/flow-alerts | alert count and premium per day vs. baseline; sweep share adds up to +2 z | 25% |
| Directional premium | same, split by call/put and ask/bid side | ask-side call premium − ask-side put premium per day; |z| scores, sign sets direction | 20% |
| New open interest | /api/stock/{t}/oi-change | sum of |OI change| per day (log1p); call/put imbalance feeds direction | 20% |
| Volume unusualness | /api/stock/{t}/options-volume → percentile | 0–100 percentile of option volume vs. trailing 90 days, mapped straight onto the weight | 15% |
| Skew shift | /api/stock/{t}/historical-risk-reversal-skew | change in 25Δ put−call IV across the window vs. typical 5-day moves | 10% |
For past events the close-to-close move over the reaction window is compared to the implied move. Pre-market and intraday catalysts use close(T) vs close(T-1); after-hours catalysts use close(T+1) vs close(T). The footprint matched when the move is at least 1× the implied move and its sign agrees with the footprint direction; otherwise it missed. A “mixed” direction can never match. Pages split a miss in two: “Right way, small move” when the stock went the way the bets leaned but by less than the implied move, and “Wrong way” when it went against them. The implied move is the earnings expected move from UW when present, else the 1-day interpolated implied move the day before; if neither exists a 4% fallback is used and labelled as such.
Claude does the parts that need language, never the arithmetic. The Narrator writes the three-sentence story and the tweet-ready caption on each case page from the score's measurements and its largest trades; every number in the story is checked against that input, and the largest trades are shown beside the story so you can verify. The Catalyst tagger maps President's-schedule and economic-calendar rows to tickers with a confidence (for the calendars not shown on the site yet). The Investigator (the “Ask about this case” box) runs a short tool loop, capped at four calls, over Foreshadow's five tools plus the Unusual Whales hosted MCP (used for questions about right now, such as the latest options flow), and names the sources it used. The Stock summary is one paragraph on whether unusual betting keeps showing up before a stock's news. Narrations are cached by (ticker, event date, score). Without ANTHROPIC_API_KEY every surface still works and shows the deterministic template instead.
Foreshadow ships a remote MCP server over streamable HTTP. One URL, five tools, no auth.
Claude Code
claude mcp add --transport http foreshadow https://foreshadow-six.vercel.app/api/mcp
Claude on the web or Claude Desktop
Settings → Connectors → Add custom connector. Name it Foreshadow and paste https://foreshadow-six.vercel.app/api/mcp.
Cursor
// .cursor/mcp.json
{
"mcpServers": {
"foreshadow": { "url": "https://foreshadow-six.vercel.app/api/mcp" }
}
}The server also offers three prompts, which Claude shows as slash commands: investigate_case (ticker, date), week_ahead and stock_track_record (ticker). Each chains the tools and asks for a short, plain answer. All five tools are read-only.
YouWas there unusual options betting before TENX's FDA news in August, and has betting like that been right before?
Claude calls foreshadow_history, foreshadow_score and foreshadow_similar.
ClaudeYes, there was notable betting against TENX before its August 10 trial results. It scored 53 out of 100, busier than 99% of 587 comparable cases. Traders bet about $1.5M on a fall, against $374K on a rise. The biggest single trade was a $983K bet on a drop, placed August 7. The stock then fell about 90%, more than the roughly 81% move options had priced in. Of 5 comparable cases, the bets were fully right in 2; the stock moved the bets' way in 4.
The API and MCP return Foreshadow's own results, not raw Unusual Whales rows: example trades carry only the day, call or put, strike, expiry, amount and whether it was a sweep. For every trade, look the stock up on Unusual Whales.
Sign in (a guest account, or GitHub or Google where enabled; no email needed) and paste your Unusual Whales API key in Settings. It is stored in Supabase Vault and only decrypted server-side for your own requests: the Ask panel's UW tools use it, and Foreshadow never re-serves UW data to anyone else. Watchlists and Discord-webhook alerts fire from the cron when a Coming up score crosses your threshold.
git clone https://github.com/yashshah1910/Foreshadow.git && cd Foreshadow && pnpm install cp .env.example .env # leave Supabase empty for demo mode, or add a free project pnpm dev # http://localhost:3000 — seeded demo data, no keys needed # with Supabase (Docker running): pnpm supabase start && pnpm supabase db reset # migrations + seed # with a UW key, backfill real data: pnpm ingest --mode backfill --days 90 --loop
The seeded dataset is synthetic: fictional tickers, generated by scripts/generate-seed.ts with a fixed seed and scored by the real scorer, so the UI demos without a key. Add UW_API_KEY and run the ingest to replace it with real catalysts.
Not financial advice. Foreshadow detects positioning, not intent; a high score is a statistical anomaly, never an allegation.
| Dark pool prints |
| /api/darkpool/{t} |
| notional of prints ≥ $1M per day (log1p) vs. baseline |
| 10% |
The cases on the site are FDA news and earnings, from /api/market/fda-calendar, /api/earnings/premarket and afterhours. The ingest can also read other calendars (not shown on the site yet): /api/congress/recent-trades (with the premium unusual-trades feed and its committee_conflict tag when available), /api/insider/transactions, /api/potus/schedule and /api/market/economic-calendar. Outcomes come from /api/stock/{t}/ohlc/1d and /api/stock/{t}/interpolated-iv. Every response is cached in the footprints table, so scoring a stock a second time is mostly free.
A real exchange with the live server (Claude Sonnet 5.5 through the MCP connector, Oct 23, 2026), lightly shortened.
Each tool has a REST twin that returns the same thing. Run one to see exactly what Claude gets.
Scores the betting before one piece of news: the score, which way it leaned and what the stock did.
What Claude sends:
{"name":"foreshadow_score","arguments":{"ticker":"KNX","eventDate":"2026-10-21"}}For clients that only run local (stdio) servers, build the small proxy in packages/mcp-stdio with pnpm --filter foreshadow-mcp build and run node packages/mcp-stdio/dist/index.js with FORESHADOW_URL=https://foreshadow-six.vercel.app. Then ask: “was there unusual options betting before Tesla's Oct 21 earnings?”