Options Flow API

Programmatic access to real-time unusual options activity data. Build your own trading tools, dashboards, and alerts on top of the same options flow pipeline that powers OptionsBell.

Quick start

# Base URL

https://optionsbell.com/api/v1

# Auth header

X-API-Key: sms_your_key_here

# Example: get unusual activity for NVDA today

curl -H "X-API-Key: sms_..." \
  "https://optionsbell.com/api/v1/options-flow/unusual?symbols=NVDA&min_premium=25000"

Generate your API key at Settings. One plan, Personal, includes the full API: 60 requests/min, 4,000 requests/day. Full reference in the API docs and the OpenAPI spec.

One subscription is bound to one named person: use the output for your own professional or business decisions, but do not share keys, connector URLs, data or output with anyone - not even colleagues; every person needs their own subscription. No redistribution or embedding in products, bots, dashboards, reports or channels for others. See the API license.

Endpoint reference

MethodPathDescription
GET/options-flow/unusualContract-level scan ranked by score, with filters: symbols, type, min_voloi, min_premium, min_iv, max_dte, min_volume, min_oi, date / date range, since (polling window), limit + offset paging
GET/options-flow/topBiggest bets of the day ranked by premium
GET/options-flow/{symbol}All unusual contracts for a single ticker, latest day by default
GET/options-flow/history/{symbol}End-of-day unusual flow series per ticker, newest first
GET/options-flow/streaksTickers with N+ consecutive days of unusual flow
GET/options-flow/expiryPremium distribution across DTE buckets
GET/options-flow/sentimentBullish/bearish classification per ticker with 0-9 strength, from call/put volume, premium and net delta
GET/options-flow/sentiment/{symbol}Single-ticker sentiment breakdown
GET/options-flow/iv-rankIV rank and percentile for all tracked tickers
GET/options-flow/iv-rank/{symbol}Single-ticker IV rank history
GET/options-flow/oi-changesLargest open interest movers of the day
GET/options-flow/oi-changes/{symbol}Single-ticker OI change detail
GET/options-flow/sectorsUnusual flow aggregated by sector
GET/options-flow/marketMarket breadth, regime, and aggregate flow statistics
GET/options-flow/statsDataset coverage: date ranges, ticker counts, update cadence

MCP server

OptionsBell ships a first-party MCP (Model Context Protocol) server with 13 tools mirroring the REST surface. Use OptionsBell inside Claude Desktop, Claude Code, Cursor, Continue, or any MCP-capable client — no API key handling in your client config if you use a personal connector URL.

  • Endpoint: https://optionsbell.com/mcp (Streamable HTTP, stateless)
  • Auth: X-API-Key header, Bearer token, or personal connector URL
  • Tools: 13 tools — get_unusual_activity, get_symbol_flow, get_top_prints, get_flow_history, get_flow_streaks, get_expiry_concentration, get_flow_sentiment, get_iv_rank, get_oi_changes, get_sector_flow, get_market_regime, get_dataset_stats, ping
  • Rate limits: Tool calls count 1:1 against your API rate limits

Full setup guide at /docs/mcp.

Data model & coverage

  • Coverage: 7,000+ US-listed stocks and ETFs
  • Refresh cadence: Full options tape scan every 5 minutes during US market hours (9:30 AM – 4:00 PM ET)
  • History: Past days are immutable and queryable by date on every endpoint; the /history/{symbol} endpoint returns the end-of-day series behind backtests (local copies must be deleted within 30 days, per the Terms)
  • Premium values: Estimated as last_price × volume × 100; may differ from actual transaction values
  • Sentiment scoring: 0-9 strength with a bullish/bearish side, based on call/put volume, premium, net delta and screener confirmations

How “unusual” is defined

Every contract on the tape is scored the same way, so what the API returns is reproducible and you can tighten it with the query parameters rather than guess at a black box.

  • Base floor: volume / open interest ≥ 1.5, open interest ≥ 100 and estimated premium ≥ $25,000. Below that a print is routine market-making, not positioning. raw=1 on /unusual removes the floor if you want everything.
  • Score: volume_oi_ratio × ln(premium_estimate + 1). The logarithm keeps a single $50M print from drowning out a 40× Vol/OI contract on a mid-cap; rows are returned in score order with a deterministic tie-breaker for paging.
  • Days to expiration: calendar days from the scan date to expiry, computed by the API, so max_dte means the same thing on every day.
  • Sweep-like flag: is_sweep_like is true when Vol/OI ≥ 5, open interest ≥ 100, volume ≥ 1,000 contracts, DTE 0-60 and premium ≥ $250,000. True sweeps need the intraday tape; this is a documented proxy on the end-of-day snapshot, not an exchange flag.
  • Intraday appearance: first_seen_at / last_seen_at record when a contract entered and was last confirmed in the 5-minute scan during the session; since filters on them for polling.

Sample response

One row from GET /options-flow/unusual?symbols=NVDA&limit=1 on a live session day. Numeric columns from the tape are strings (exact decimals), computed fields are numbers, and the envelope carries filtered_total and has_more for paging.

{
  "date": "2026-10-09",
  "count": 1, "limit": 1, "offset": 0, "filtered_total": 77, "has_more": true,
  "sort": "score_desc,symbol,option_symbol",
  "data": [{
    "symbol": "NVDA",
    "option_symbol": "NVDA|20261014|225.00C",
    "symbol_type": "Call",
    "base_last_price": "230.4800",
    "strike_price": "225.0000",
    "expiration_date": "10/14/26",
    "days_to_expiration": 5,
    "last_price": "7.3600", "bid_price": "7.1000", "ask_price": "7.5000",
    "volume": "3749",
    "open_interest": "133",
    "volume_oi_ratio": "28.1900",
    "volatility": "33.2100",
    "delta": "0.7257",
    "data_date": "2026-10-09",
    "sector": "Information Technology",
    "industry": "Semiconductors",
    "premium_estimate": "2759264",
    "is_sweep_like": true
  }]
}

An unusual options activity API, not another dashboard

As an options data api it is deliberately narrow: unusual activity, per-symbol flow, IV rank, OI changes and sector aggregates, rather than a general options data api trying to cover every chain in the market. If you need a broad options data api with full chains and greeks on every strike, this is the wrong tool.

Most platforms bolt an API onto a terminal. Here the unusual options activity API is part of the same plan rather than a separate tier: 22 endpoints and 4,000 requests/day, included at $24.99/month alongside the options flow product itself.

If you are evaluating an unusual options activity API to feed your own models or alerting stack, it returns the same sweep and block trade data you can see in the live feed, without paying for a dashboard seat you will not use.

Pair the unusual options activity API with the MCP integration to query flow data from your own tools rather than scraping a dashboard.

Common use cases

  • Trading bot signals: Poll /unusual endpoint every 5 minutes, filter for your watchlist, forward high-conviction prints to your execution engine.
  • Webhooks, no polling: Register your tickers and filters once via POST /webhooks and receive a signed JSON event whenever new unusual contracts appear - included in the plan, no extra tier.
  • Personal dashboard: Surface top prints, sector flow, and sentiment data in your own research dashboard.
  • Backtesting: Use the /history/{symbol} endpoint to test whether unusual flow streaks predict short-term price movements for your target universe - re-query any time, keep local copies no longer than 30 days.
  • AI-assisted analysis: Pipe OptionsBell data into Claude via the MCP server for natural-language querying of options flow data.
  • Daily briefing for yourself: Pull top prints and sector data programmatically into your own morning notes.

Start building with the Options Flow API

22 REST endpoints, MCP server, OpenAPI spec. $24.99/month includes full API access. Cancel anytime.

Subscribe now →