OptionsBell REST API

Rate limits & usage cap

One plan, one set of limits: 60 requests per minute and 4,000 requests per day per API key, enforced durably across deployments. Every authenticated response (200, 400, 429) carries both header sets so you can pace your client. Responses rejected before authentication completes (401, 403, 503) carry none.

Exceeding a window returns 429 with code RATE_LIMIT_MINUTE or RATE_LIMIT_DAY. Every response also carries an X-Request-Id header - quote it when reporting a problem.

Endpoints

/api/v1/options-flow/unusual?symbols=AAPL,NVDA&type=c&min_voloi=5&min_premium=250000&limit=300

/api/v1/options-flow/:symbol/AAPL?limit=100

/api/v1/options-flow/top?type=p&min_premium=1000000&limit=20

/api/v1/options-flow/history/:symbol/TSLA?date_from=2026-04-01&limit=90

/api/v1/options-flow/streaks?min_streak=5&side=call&limit=50

/api/v1/options-flow/expiry?symbols=NVDA,TSLA

/api/v1/options-flow/sentiment?signal_only=1&min_strength=6&sector=Information+Technology&limit=50

/api/v1/options-flow/sentiment/:symbol/NVDA?limit=60

/api/v1/options-flow/iv-rank?side=put&min_rank=0.8&limit=50

/api/v1/options-flow/iv-rank/:symbol/AMD?lookback_days=120

/api/v1/options-flow/oi-changes?side=gainers&min_change_pct=0.5&limit=50

/api/v1/options-flow/oi-changes/:symbol/NVDA?limit=60

/api/v1/options-flow/sectors?limit=11

/api/v1/options-flow/market?limit=30

/api/v1/webhooks/:id/deliveries?limit=50

Query parameters

Both contract-level endpoints (/unusual and /:symbol) accept the same filters; only the paging limits differ. Default scope is the latest scan day - everything else is opt-in. Parameters are validated up front: a malformed value answers 400 before any query runs (see Error responses).

Time scope

Symbol scope

Contract filters

Numeric thresholds must be numbers (otherwise INVALID_PARAM); negative values are clamped to 0. The same rules apply to the numeric, integer and enum parameters of every other endpoint.

Ordering, paging and row identity

• Rows are ordered by volume_oi_ratio * ln(premium_estimate + 1) descending, then data_date, symbol, option_symbol ascending. The tie-breaker makeslimit + offset paging deterministic.
• A row is uniquely identified by (data_date, symbol, option_symbol).
• The envelope is { date, date_from, date_to, since, count, limit, offset, filtered_total, has_more, sort, data } (/:symbol adds symbol first). count is the rows in this response, filtered_total the rows matching the filters across all pages (0 when the page is past the end), sort is always score_desc,symbol,option_symbol. Empty results keep the same shape with count: 0.
• The current trading day is upserted every 5 minutes during the regular session: volume, last price, Vol/OI and therefore the score change, new contracts are added, none are removed. Past days are immutable, so a date-fixed query on a finished day is repeatable. For a consistent intraday enumeration, page quickly and de-duplicate on the row identity.
• last_seen_at is only refreshed during the regular session; a row's first_seen_at / last_seen_at are the scan timestamps since filters on, null when no intraday appearance was recorded.

Examples

# Latest scan, default filters
GET /api/v1/options-flow/unusual

# Calls only on NVDA + TSLA with Vol/OI >= 5 and $250k+ premium
GET /api/v1/options-flow/unusual?symbols=NVDA,TSLA&type=c&min_voloi=5&min_premium=250000

# Last 7 days of AAPL flow, ranked by score
GET /api/v1/options-flow/AAPL?date_from=2026-06-01&date_to=2026-06-07

# Anything seen in the last 10 minutes (polling; de-duplicate on the row identity)
GET /api/v1/options-flow/unusual?since=2026-06-08T14:30:00Z

# Page through a full day
GET /api/v1/options-flow/unusual?date=2026-06-05&limit=1000&offset=1000

# Short-dated put hedging, IV > 60%, DTE <= 14
GET /api/v1/options-flow/unusual?type=p&min_iv=60&max_dte=14

Derived endpoints: paging and completeness

• /top, /streaks, /sentiment and /oi-changes page the same way as /unusual: limit + offset, and the envelope carries count, limit, offset, filtered_total, has_more. Each has a deterministic tie-breaker (symbol, and option_symbol for /top), so pages of a finished day never overlap or skip.
• A result is complete when has_more is false, equivalently when offset + count reaches filtered_total. On every endpoint, count below the requested limit also means nothing was cut; there is no other cap. /sectors has at most 14 rows and its default limit returns all of them.
• /top is not a fixed global top-N: symbols, type and min_premium filter before ranking and rank is the position in the full filtered set. A ticker with more than 100 qualifying prints is enumerated with offset.
• Absence semantics. /streaks (min_streak=1, side=all) and /sentiment (no side / signal_only) have one row per symbol with unusual flow that day, so a ticker missing from the complete result had no unusual contract on that day. /oi-changes additionally omits symbols with no earlier unusual-flow day in the previous 30 days or with prev_oi below min_prev_oi; a zero change is returned as a row with oi_change: 0.
• Finished days are repeatable: contract rows are immutable, the per-symbol daily aggregates are recomputed only for the two most recent days on each scan, and signals are computed once per day. The sector / industry labels are joined from a mapping table at query time and can change if a symbol is reclassified.

Types & units

Values are serialized straight from Postgres, so the JSON type follows the column type. The OpenAPI spec marks every field.

• Numeric strings. Prices, volumes, open interest, premiums, ratios, IV and other BIGINT / NUMERIC columns arrive as strings ("1234", "25.43") to preserve precision - parse them on your side.
• Numbers. Integer counts (days_to_expiration, calendar days from data_date to expiration_date computed by the API and authoritative for max_dte and the expiry buckets, rank, consecutive_days, strength_score, breadth_score, contract counts) and float columns (oi_change_pct, call_put_ratio, *_iv_percentile) are JSON numbers; flags are booleans; text arrays such as bullish_confirmations are string arrays.
• Dates and times. Trading days (date, data_date, prev_date, history_start) are YYYY-MM-DD. first_seen_at / last_seen_at and the since echo are ISO-8601 timestamps in UTC.
• Units. Implied volatility (volatility, *_iv, min_iv) is in percent (25.43 = 25.43%). Premiums are USD, estimated as last_price * volume * 100. IV rank, IV percentile, min_rank/max_rank and oi_change_pct/min_change_pct are fractions 0..1.

Error responses

All errors return JSON in the form { "error": "<message>", "code": "<CODE>" }; a 500 adds requestId (same value as the X-Request-Id header). 400, 404, 409 and 429 responses carry the rate-limit headers; 401, 403 and 503 do not. POST /webhooks/:id/test answers 502 with the regular test-result body (not an error object) when your endpoint did not accept the event.

Webhooks

Instead of polling /unusual, register a webhook: a ticker list plus optional filters, stored once. OptionsBell then POSTs a signed JSON event to your https endpoint whenever new unusual contracts matching the filters appear for those tickers. Webhooks are managed only through this API (no UI), require the same key and Personal subscription, and the management calls count against the rate limits like any other request - outbound deliveries do not.

When a webhook fires

• Evaluation runs every 5 minutes during the webhook's active_hours (default 09:00-16:00 America/New_York, end exclusive, may wrap past midnight). Outside the window nothing is evaluated or delivered.
• Each run compares the current unusual-activity scan for your tickers against the contracts you have already been sent. Only contracts you have not received yet are delivered, so each contract is delivered once - a contract that stays unusual for days does not repeat. De-duplicate on option_symbol anyway if you retry on your side.
• At most one delivery per notify_interval_min (default 10; choices 10, 30, 60, 240, 480, 1440), counted from the last successful delivery. Contracts that surface during the cooldown are batched into the next delivery, not dropped.
• The first run after creation only records a baseline and does not deliver - otherwise you would receive everything that is already unusual the moment you register. Expect the first event at the earliest ~10 minutes after creation, and only if something new shows up. Adding tickers later does not reset the baseline: contracts already unusual on a newly added ticker arrive with the next evaluation.
• The same base floor as the app alerts applies (Vol/OI >= 1.5, OI >= 100, premium >= $25k) plus your optional criteria (type, min_voloi, min_premium, min_iv, max_dte, min_volume, min_oi - same semantics as the query parameters above). An event carries at most 10 contracts per ticker (highest Vol/OI first); anything beyond that cap is marked as seen and not delivered later.
• Deliveries are best-effort push, typically 1-6 minutes after a print appears in our data. For an audit trail or a backfill after downtime, query /unusual with since.

Management endpoints

Validation errors are 400 with INVALID_PARAM (malformed body, name, criteria, notify_interval_min, active_hours, is_active), INVALID_URL (not https, not a public host, does not resolve) or INVALID_SYMBOLS (tickers missing, invalid, or more than 150); an unknown id is 404 NOT_FOUND. The url must be an absolute https URL on a public host - localhost, *.local, *.internal and hosts resolving to private, loopback or link-local ranges are rejected at registration. Redirects are not followed.

Create a webhook

curl -X POST https://optionsbell.com/api/v1/webhooks \
  -H "X-API-Key: sms_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "NVDA/TSLA calls",
    "url": "https://example.com/hooks/optionsbell",
    "tickers": ["NVDA", "TSLA"],
    "criteria": { "type": "c", "min_premium": 250000, "max_dte": 30 },
    "notify_interval_min": 10,
    "active_hours": { "start": "09:30", "end": "16:00" }
  }'

# 201
{
  "id": "cmg1x2y3z0000abcd12345678",
  "name": "NVDA/TSLA calls",
  "url": "https://example.com/hooks/optionsbell",
  "tickers": ["NVDA", "TSLA"],
  "criteria": { "type": "c", "min_voloi": null, "min_premium": 250000, "min_iv": null, "max_dte": 30, "min_volume": null, "min_oi": null },
  "notify_interval_min": 10,
  "active_hours": { "start": "09:30", "end": "16:00", "timezone": "America/New_York" },
  "is_active": true,
  "paused_at": null,
  "consecutive_failures": 0,
  "last_run_at": null,
  "last_delivered_at": null,
  "created_at": "2026-09-23T13:02:11.480Z",
  "updated_at": "2026-09-23T13:02:11.480Z",
  "secret": "whsec_0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a6978"
}

# Verify your endpoint end-to-end
curl -X POST https://optionsbell.com/api/v1/webhooks/cmg1x2y3z0000abcd12345678/test \
  -H "X-API-Key: sms_xxxxxxxxxxxxxxxx"

Event payload

Every delivery is a POST with Content-Type: application/json, User-Agent: OptionsBell-Webhooks/1.0, X-OptionsBell-Event (unusual_activity or test), X-OptionsBell-Delivery (the delivery id, unique per delivery and identical across its retries - use it for idempotency) and X-OptionsBell-Signature. Unlike the data endpoints, the numeric fields in the payload are JSON numbers; strike_price and expiration_date are the stored strings.

POST https://example.com/hooks/optionsbell
Content-Type: application/json
User-Agent: OptionsBell-Webhooks/1.0
X-OptionsBell-Event: unusual_activity
X-OptionsBell-Delivery: whd_3f9c1a2b4d5e6f708192a3b4
X-OptionsBell-Signature: t=1758640502,v1=5257a869e7ecebcaa3d8c7cd39ab5f2b4d9e0c1a2b3c4d5e6f708192a3b4c5d6

{
  "event": "unusual_activity",
  "delivery_id": "whd_3f9c1a2b4d5e6f708192a3b4",
  "sent_at": "2026-09-23T14:35:02.117Z",
  "data_date": "2026-09-23",
  "webhook": { "id": "cmg1x2y3z0000abcd12345678", "name": "NVDA/TSLA calls" },
  "count": 2,
  "contracts": [
    {
      "symbol": "NVDA",
      "option_symbol": "NVDA|20261016|215.00C",
      "symbol_type": "Call",
      "strike_price": "215.0000",
      "expiration_date": "10/16/26",
      "days_to_expiration": 23,
      "volume_oi_ratio": 85.3,
      "volatility": 54,
      "premium_estimate": 13700000
    },
    {
      "symbol": "TSLA",
      "option_symbol": "TSLA|20261009|460.00C",
      "symbol_type": "Call",
      "strike_price": "460.0000",
      "expiration_date": "10/09/26",
      "days_to_expiration": 16,
      "volume_oi_ratio": 12.4,
      "volatility": 61,
      "premium_estimate": 2450000
    }
  ]
}

Verifying the signature

X-OptionsBell-Signature is t=<unix seconds>,v1=<hex> where v1 is HMAC-SHA256 over the string <t>.<raw body> keyed with your webhook secret. Compute it over the raw request bytes exactly as received (do not parse and re-serialize), compare in constant time, and reject requests whose t is too far from your clock. The 5-minute tolerance below is a client-side recommendation against replay - OptionsBell signs a fresh t on every attempt but does not enforce a tolerance itself.

// Node.js (Express: use express.raw({ type: "application/json" }) so req.body is a Buffer)
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyOptionsBell(rawBody, signatureHeader, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(signatureHeader.split(",").map((kv) => kv.split("=")));
  const t = Number(parts.t);
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

app.post("/hooks/optionsbell", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifyOptionsBell(req.body, req.get("X-OptionsBell-Signature") ?? "", process.env.OB_WEBHOOK_SECRET)) {
    return res.status(401).end();
  }
  const event = JSON.parse(req.body.toString("utf8"));
  res.status(204).end(); // answer 2xx within 5 s, then do the work
});

# Python
import hmac, hashlib, time

def verify_optionsbell(raw_body: bytes, signature_header: str, secret: str, tolerance_sec: int = 300) -> bool:
    parts = dict(kv.split("=", 1) for kv in signature_header.split(","))
    try:
        t = int(parts["t"])
    except (KeyError, ValueError):
        return False
    if abs(time.time() - t) > tolerance_sec:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

# Flask: verify_optionsbell(request.get_data(), request.headers.get("X-OptionsBell-Signature", ""), SECRET)

Retries and pausing

• Any 2xx within 5 seconds counts as delivered. Respond first, process after.
• Up to 3 attempts per delivery: immediately, after 2 s, after 6 s. 5xx, 408, 429, timeouts and network errors are retried; any other 4xx ends the delivery. Redirects are not followed. Each attempt is signed with a fresh t; the body and delivery_id stay the same.
• A failed delivery leaves its contracts marked as not-yet-delivered, so the next evaluation (5 minutes later) sends them again - the cooldown only counts from successful deliveries.
• After 20 consecutive failed deliveries the webhook is paused: paused_at is set and nothing more is sent (it is still evaluated, so contracts keep being marked as seen). Resume it with a PATCH carrying a url or is_active: true, or with a successful /test. Any successful delivery resets consecutive_failures to 0; failed test events do not count.
• GET /webhooks/:id/deliveries shows every delivery with its last HTTP status, attempts, duration and error text - check it before re-enabling.

Limits and licensing

• Webhooks and app-created alerts share a limit of 10 per subscription; up to 150 tickers per webhook; name 1-80 characters; url up to 2048 characters.
• Webhooks stop firing when the subscription ends (a canceled subscription keeps working until the end of its paid period); the configuration is kept.
• Deliveries go to your own endpoint and the one-person rule of the Personal plan applies to them exactly as to API responses: consume the events yourself, do not forward them to colleagues, channels or products for others.

Coverage and freshness

• 7,000+ US-listed common stocks and ADRs with active options.
• The current trading day is refreshed every 5 minutes during the regular session; rows are added or updated, never removed. Past days are immutable.
• Historical days are queryable everywhere via date / date_from / date_to, and as an end-of-day series via /options-flow/history/:symbol. Call /options-flow/stats to see the available date range.
• All timestamps are UTC; trading days are the US session date.