Unusual Whales API integration & options flow data pipelines

Full options flow & filtering

Expose the complete options flow tape (contract, strike, expiry, side, premium, volume, open interest, IV, underlying price) with the same saved-filter logic the Unusual Whales mobile app offers. Typical use: feeding a trading bot that acts only on sweeps above $250k premium in defined sectors.

Unusual options activity & hot chains

Normalize "unusual" scoring across volume/open-interest ratios and premium percentile ranks. The hot chains endpoint surfaces contracts with abnormal concentration so quant desks can trigger intraday alpha tests or compliance lookbacks.

Dark pool flow

Capture off-exchange block prints published through FINRA ATS tapes, with per-trade size, settlement timing, and venue classification. Use case: reconcile institutional buying pressure against retail sentiment indicators in a single dashboard.

Market Tide & sector rotation

Aggregate net premium by sector, put/call ratio by sector, and relative rotation indexes. Useful for macro screens or allocation engines that need to rebalance thematic baskets based on option-derived sentiment.

Greeks, GEX and volatility surface

Per-symbol gamma exposure, charm and vanna, plus implied volatility skew across expiries. Consumed by market-makers and risk tools needing dealer positioning maps without building their own Black-Scholes pipelines.

Custom alerts & webhooks

Mirror the in-app custom alerting engine as webhook delivery. Your downstream receives a signed payload when a flow pattern matches — suitable for Discord bots, Slack alerts, or internal order management triggers.

1) Options flow into a trading-bot platform

Business context: A proprietary trading desk wants its execution bot to react only when sweep premium exceeds a threshold on pre-filtered tickers. Data / API: Flow Alerts WebSocket plus Greeks REST endpoint. OpenData mapping: The alert payload is normalized to an OpenFinance-style instrument + event + measurement schema, so the bot can be portable to other flow vendors without code rewrites.

2) Dark pool ingestion for risk dashboards

Business context: A portfolio analytics vendor reconciles intraday positioning against off-exchange blocks. Data / API: Dark Pool prints stream with venue and settlement fields. OpenData mapping: Prints are written to a Kafka topic; a downstream Flink job enriches with sector and market-cap metadata for institutional attribution views.

3) Congressional trading compliance feed

Business context: A compliance team at a multi-family office needs STOCK Act disclosures cross-referenced with client holdings. Data / API: Political trading endpoints, per-member and per-committee. OpenData mapping: Each disclosure becomes a signed event in the compliance warehouse with filing timestamps and ticker FIGI resolution.

4) LLM / MCP research agent

Business context: A buy-side firm wants a chat agent that can answer "what unusual AMZN call activity printed this morning?". Data / API: Unusual Whales MCP server plus custom retrieval layer over flow history. OpenData mapping: The MCP tool surface is proxied through an authenticated gateway that enforces entitlement, rate-limit, and redaction before the model sees anything.

5) Sector-rotation overlay for allocation engines

Business context: A robo-advisor overlays short-horizon option sentiment on top of long-horizon factor allocations. Data / API: Market Tide net premium by sector plus put/call ratios on 5-minute buckets. OpenData mapping: The overlay publishes a daily "sector conviction" vector consumable by any downstream portfolio engine that speaks a flat JSON schema.

1. Authenticated REST — flow history

GET /api/v1/uw/options-flow?ticker=AAPL&min_premium=250000&side=sweep
Authorization: Bearer <ACCESS_TOKEN>
Accept: application/json

200 OK
{
  "ticker": "AAPL",
  "window": "2026-04-23T13:30:00Z..2026-04-23T20:00:00Z",
  "trades": [
    {
      "id": "fl_9f2c...",
      "contract": "AAPL260515C00210000",
      "side": "sweep",
      "premium": 412500.00,
      "volume": 1500,
      "open_interest": 842,
      "iv": 0.284,
      "underlying_price": 207.51,
      "unusual_score": 0.91
    }
  ],
  "next_cursor": "eyJvZmZzZXQiOjEwMH0="
}

2. WebSocket — live flow alerts

// Node.js pseudocode
const ws = new WebSocket('wss://gw.example.com/uw/flow-alerts', {
  headers: { Authorization: 'Bearer ' + TOKEN }
});

ws.on('open', () => {
  ws.send(JSON.stringify({
    action: 'subscribe',
    filters: { min_premium: 500000, types: ['sweep','block'] }
  }));
});

ws.on('message', raw => {
  const evt = JSON.parse(raw);
  // evt: { ticker, contract, side, premium, unusual_score, ts }
  if (evt.unusual_score >= 0.85) route_to_bot(evt);
});

3. Webhook — custom alert delivery

POST /your/hook
X-UW-Signature: t=1714060800,v1=0b9c3...
Content-Type: application/json

{
  "alert_id": "ca_8d71",
  "rule": "gex_flip_above_zero",
  "ticker": "SPY",
  "triggered_at": "2026-04-23T14:05:03Z",
  "payload": {
    "gex": 1.2e9,
    "prev_gex": -4.3e8,
    "spot": 518.42
  }
}

4. Congressional trades — batch pull

POST /api/v1/uw/congress/trades
Authorization: Bearer <ACCESS_TOKEN>

{
  "member_ids": ["P000197","C001075"],
  "from_date": "2026-01-01",
  "to_date":   "2026-04-22"
}

Response:
[
  { "member":"P000197","ticker":"NVDA","txn":"buy",
    "amount_range":"$15,001-$50,000","filed":"2026-02-14" }
]

Deliverables checklist

• OpenAPI 3.1 specification for all wrapped endpoints
• Protocol and auth flow report (token refresh, rate limiting, entitlement)
• Runnable source code in Python, Node.js, or Go for flow, dark pool, congressional, and Greeks endpoints
• WebSocket and Kafka consumer reference clients
• Automated integration tests + synthetic fixtures
• Compliance guidance on redistribution, retention, and entitlement boundaries

Engagement options

• Source code delivery from $300: we ship runnable API source code and documentation — pay after delivery upon satisfaction.
• Pay-per-call hosted API: consume our managed endpoints and pay only per request; no upfront cost.
• Enterprise extension: custom ETL into your warehouse, SSO/SAML, and on-prem Kafka bridge.

About us

We are an independent studio focused on fintech, market data, and OpenData API integration. Our team includes engineers with backgrounds in options market-making, equities execution, protocol reverse engineering, and cloud data platforms. We have shipped integrations for options flow vendors, dark-pool print aggregators, and congressional-trading watchlists — all under documented authorization and vendor-compliant redistribution rules.

• Market data, options analytics, dark pool ingestion, political trading feeds
• Enterprise API gateways, rate-limit modeling, and entitlement enforcement
• Python / Node.js / Go SDKs, Kafka consumers, and MCP bridges
• Full pipeline: protocol analysis → build → validation → compliance sign-off

Contact

To scope a project or request a quote for Unusual Whales integration, share the target use case and any existing entitlements you hold.

Open contact page

Engagement workflow

1. Scope confirmation: target datasets (flow, dark pool, congressional, Greeks), delivery mode (REST / WS / Kafka / MCP), and compliance posture.
2. Protocol analysis and API design (2–5 business days).
3. Build and internal validation against live fixtures (3–8 business days).
4. Docs, SDK samples, and automated tests (1–2 business days).
5. First delivery typically within 5–15 business days; enterprise Kafka or on-prem deployments may extend timelines.

FAQ

What do you need from me?

How long does delivery take?

How is compliance handled?