VolatilityWizard

Turn raw CBOE volatility data into ready-to-use options intelligence — VIX regime, IV rank, term structure, and strategy setup scores from a single REST call.

VolatilityWizard pulls official CBOE daily index data (VIX, VIX9D, VIX3M, VIX6M, and the per-stock VX series) and turns it into the signals options traders actually use: what volatility regime the market is in, how rich a name's implied volatility is versus its own history, the shape of the VIX term structure, and a 0–100 quality score for popular options strategies. Every response is plain JSON with stable field names, cached for fast repeat reads, and ready to drop into a scanner, dashboard, or trading bot.

Endpoints

Why this API

• Sourced from official CBOE data. VIX-family and per-stock VX indices are read straight from CBOE's public daily-price CSVs — not a black-box third party.
• Decisions, not just numbers. Beyond raw values, every endpoint returns a label or signal (regime, premium signal, term-structure shape, setup score) so you can act without building your own logic.
• Strategy-aware setup scoring. /setup/score weights IV rank, sentiment, and term-structure slope differently per strategy, so an iron condor and a long straddle get scored for the conditions each actually wants.
• Fast and cache-friendly. Responses are cached (default 300s TTL via Redis), so repeated scans across many tickers stay quick and cheap.
• Drop-in JSON with stable field names. Flat, predictable response shapes — easy to wire into a spreadsheet, scanner, or bot with zero parsing gymnastics.

Typical use cases

• Volatility regime dashboard — poll /vix/regime and /term-structure/SPY to show whether the market is calm or stressed and whether the curve is in contango or backwardation.
• Premium-selling screener — loop tickers through /iv/rank/:ticker and surface names where premium_signal is sell_premium.
• Strategy fit check — before placing a trade, hit /setup/score/:ticker?strategy=iron_condor (or long_straddle / covered_call) to gauge whether current conditions favor it.
• AI trading agent tool — feed the JSON signals into an LLM agent (the same logic ships as an MCP server) to reason about options setups.
• Alerting — watch /vix/regime regime transitions (e.g. moderate → elevated) to trigger risk-off notifications.

Good to know

• Data source is CBOE, not options chains. IV and volatility metrics are derived from CBOE volatility indices, not live options-chain/greeks feeds. Plan accordingly for strategies that need strike-level data.
• IV rank coverage is limited per-stock. Dedicated CBOE per-stock VX series exist only for AAPL, GS, IBM, and AMZN (data_source: cboe_vx). Any other ticker falls back to the broad VIX as a proxy (data_source: vix_proxy), so its iv_rank/atm_iv reflect market-wide volatility, not that single name.
• hv_30d is an estimate. It is derived from ATM IV (a fixed 0.87 ratio), not computed from realized price history.
• Flow signals are a VIX-regime heuristic. /flow/signals infers call_put_ratio and net_sentiment from the current VIX regime; it is not raw order-flow data, and largest_print is always null.
• Daily granularity. Values come from CBOE daily closing prices and update once per trading day, not intraday/real-time.
• Caching. Responses are cached for CACHE_TTL_SECONDS (default 300s), so a value can lag the source by up to the TTL window.
• Errors. Upstream failures return 500 with { "error": "..." }; unknown routes return 404 with { "error": "Not found" }.