# Options Flow API - Unusual Whales Flow Alerts, Dark Pool, GEX (`nabeelbaghoor/options-flow-dark-pool-api`) Actor

Pull unusual options flow alerts, unusual options activity, the option trades tape, hottest chains, option chains with greeks, gamma exposure (GEX), IV rank, max pain, dark pool prints, market tide, congress and insider trades from the Unusual Whales API into a dataset. Bring your own API key.

- **URL**: https://apify.com/nabeelbaghoor/options-flow-dark-pool-api.md
- **Developed by:** [Nabeel Hassan](https://apify.com/nabeelbaghoor) (community)
- **Categories:** Developer tools, Business, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 options flow alert returneds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Options Flow API - Unusual Whales Flow Alerts, Dark Pool, GEX

Export unusual options flow, the option trades tape, option chains with greeks, gamma exposure, dark pool prints, congress trades and insider trades into an Apify dataset with your own Unusual Whales API token.

This actor wraps the Unusual Whales REST API. It turns a ticker list, an option contract or a set of flow filters into clean, deduplicated rows you can download as JSON, CSV or Excel, schedule every few minutes, or feed into trading bots, dashboards, spreadsheets and AI agents.

### What it does

- **Options flow alerts**: unusual options activity alerts (repeated hits, ascending and descending fills, sweeps followed by floor, floor trades by market cap, OTM earnings floor), with premium, size, volume, open interest, volume to OI ratio, ask and bid side premium and greeks.
- **Unusual options activity**: the contracts flagged unusual on a trading day (volume above open interest, out of the money, 60 days or less to expiry, mostly ask side, 10,000 USD premium or more).
- **Hottest chains**: the option contract screener, sorted by premium, volume, open interest, IV, trades and more.
- **Option trades tape**: individual option prints of the latest trading day with NBBO, side volumes, tags, exchange and greeks.
- **Option chain**: every contract of a ticker with NBBO bid and ask, implied volatility, delta, gamma, theta, vega and rho.
- **Option contract trades and history**: the prints of one contract, or its daily open, high, low, close, volume, open interest and IV range.
- **Greek exposure (GEX)**: daily market maker gamma, delta, charm and vanna exposure, and spot GEX per strike.
- **IV rank, max pain and options volume**: implied volatility rank history, max pain per expiry, and daily call and put volume, premium and open interest.
- **Dark pool prints**: the latest off-exchange prints across the market, or every print of a ticker on a day.
- **Market tide**: market wide net call and net put premium per 1 or 5 minute interval.
- **Congress trades and insider transactions**: stock trades reported by members of Congress, and SEC Form 3, 4, 5 and 144 insider filings.
- **Pay only for results**: empty answers are recorded as a free row that says why, never charged.

### Input

| Field | Used by | What it does |
| --- | --- | --- |
| `mode` | all | `flowAlerts`, `unusualActivity`, `hottestChains`, `optionTrades`, `optionChain`, `contractTrades`, `contractHistory`, `greekExposure`, `gexByStrike`, `ivRank`, `maxPain`, `optionsVolume`, `darkpoolRecent`, `darkpoolTicker`, `marketTide`, `congressTrades` or `insiderTransactions` |
| `tickers`, `excludeTickers` | most modes | Symbols such as SPY, NVDA or SPX. Per-ticker modes read each one separately |
| `contracts` | contract modes | OSI option symbols such as TSLA250117C00250000 |
| `date` | daily modes | Trading date such as 2026-01-30; defaults to the last trading day |
| `from`, `to` | flow alerts, tape, dark pool by ticker, insiders | Time window, read newest first |
| `unusualPreset` | flow alerts, hottest chains | The provider's unusual flow criteria in one switch |
| `optionType`, `side`, `alertRules` | flow modes | Calls or puts, ask or bid side, alert rules |
| `minPremium`, `maxPremium`, `minSize` | flow and dark pool modes | Premium in USD and size in contracts or shares |
| `minDte`, `maxDte`, `expiry`, `minStrike`, `maxStrike` | contract filters | Days to expiry, one expiry date, strike range |
| `minVolumeOiRatio`, `volumeGreaterOi`, `sizeGreaterOi`, `openingOnly`, `otmOnly`, `multiLeg` | flow modes | Classic unusual activity filters |
| `issueTypes`, `sectors`, `minMarketcap`, `maxMarketcap` | screening modes | Common stock, ETF, index or ADR; sectors; market cap |
| `screenerSort`, `sortDirection` | hottest chains | Order of the screen |
| `lookback` | greek exposure, IV rank | Such as 1Y, 6M or YTD |
| `ownerName`, `insiderRole`, `transactionCodes`, `formTypes`, `minValue` | insiders | Who, which role, which Form 4 codes and forms, how large |
| `maxResults` | all | Row ceiling for the run |
| `apiKey` | all | Your Unusual Whales API token (secret). Or set the `DATA_API_KEY` environment secret |

Inputs a mode does not use are left off the request and named in the log, so a filter meant for another mode never silently empties your results.

### How to get an API key

Subscribe to an Unusual Whales API plan at unusualwhales.com (API Basic for individual developers, API Advanced, or the Startup and Enterprise plans for products), then create a token in the API section of your Unusual Whales dashboard. The token is a UUID such as 123e4567-e89b-12d3-a456-426614174000. Paste it into the API key field.

### Example output

```json
{
    "mode": "flowAlerts",
    "recordType": "flowAlert",
    "identifier": "NVDA",
    "found": true,
    "id": "NVDA260116C00200000|2026-10-07 15:42:10.512000+00:00",
    "ticker": "NVDA",
    "optionSymbol": "NVDA260116C00200000",
    "optionType": "call",
    "strike": "200",
    "expiry": "2026-01-16",
    "date": "2026-10-07 15:42:10.512000+00:00",
    "premium": "1240500",
    "size": 1530,
    "value": "2.41",
    "alert_rule": "RepeatedHits",
    "has_sweep": true,
    "has_floor": false,
    "total_ask_side_prem": "1180000",
    "total_bid_side_prem": "60500",
    "trade_count": 41,
    "volume": 9120,
    "open_interest": 3784,
    "underlying_price": "186.20",
    "note": null
}
```

Every field the provider returns is kept. `value` is the headline number of each record type: the volume to open interest ratio for flow alerts, open interest for contracts, the price for prints, net gamma for greek exposure and spot GEX, IV rank, max pain, the put to call volume ratio for options volume, net premium for market tide, the amount band for congress trades and the price for insider transactions.

### FAQ

#### What is the Unusual Whales API?

The Unusual Whales API is a commercial market data API from Unusual Whales covering the full US options tape (OPRA), rule based flow alerts, option chains with greeks, market maker greek exposure, volatility, dark pool prints, market tide, congressional trading and SEC insider filings. This actor calls its REST endpoints such as `/api/option-trades/flow-alerts`, `/api/option-activity/unusual`, `/api/screener/option-contracts`, `/api/option-trades`, `/api/stock/{ticker}/option-contracts`, `/api/stock/{ticker}/greek-exposure`, `/api/darkpool/recent`, `/api/market/market-tide`, `/api/congress/recent-trades` and `/api/insider/transactions`.

#### Do I need my own API key?

Yes. This actor is bring your own key: you need an active Unusual Whales API subscription. Your token is stored as an Apify secret, sent only in the `Authorization: Bearer` header, and kept out of every log line. Without a token the run stops immediately with a clear message and no charge.

#### How do I get unusual options activity for one stock?

Choose Flow alerts, put the ticker (for example NVDA) in Tickers, and set a minimum premium such as 100000. Tick "Unusual flow preset" to apply the same criteria as the provider's live options flow page, or combine your own filters: calls or puts, ask side, sweeps and repeated hits rules, volume above open interest, out of the money and days to expiry.

#### How far back can I read options flow?

Flow alerts and dark pool prints by ticker are read newest first and followed back in time until your row ceiling or the window you set in From and To. The option trades tape covers the latest trading day only; the provider serves earlier days as full tape file downloads from a separate endpoint, which this actor does not read. Your plan sets the historical lookback (the provider lists 2 years on its API plans and 90 days on Startup); an older date ends the run with the provider's explanation.

#### What is gamma exposure (GEX) and which mode gives it?

GEX is the assumed dollar gamma market makers hedge per 1 percent move of the underlying. Greek exposure returns one row per day with call and put gamma, delta, charm and vanna, and Spot GEX by strike returns the latest exposure per strike, both from open interest and from volume. The `value` column carries net gamma.

#### Does it cover SPX, VIX and other index options?

Index options appear in flow, trades and chains, but the provider returns CBOE index prices (the underlying price of SPX or VIX) as null unless your account has CBOE approval, and leaves index rows out when you filter on underlying price. This is a provider licensing rule.

#### What do I pay?

The actor charges per returned record: 0.01 USD per flow alert, 0.01 USD per option contract, 0.005 USD per option or dark pool print, 0.005 USD per series point (a day, strike, expiry or interval), and 0.01 USD per congress or insider trade, with Apify platform usage included. Empty results are free. Unusual Whales bills your API subscription separately, and each page is one request against your plan's per-minute cap.

#### What happens if my key is wrong or my plan does not cover a request?

A missing, malformed or revoked token (401), a request outside your plan such as an older date or an Advanced tier endpoint (403), or a spent daily allowance ends the run cleanly with the provider's own explanation as the status message. The per-minute rate limit (429) is waited out using the provider's reset header and retried.

### Keyword map

options flow API, unusual options activity, Unusual Whales API, flow alerts, options sweeps, whale trades, option trades tape, hottest chains, option chain API, options greeks, gamma exposure GEX, IV rank, max pain, dark pool prints, dark pool API, market tide, congress trades, politician stock trades, insider trading API, Form 4 data.

### Terms and data use

You need your own Unusual Whales API subscription, and your use of the data is governed by your agreement with Unusual Whales. Its API Basic plan is described as for individual developers; the provider sells commercial licensing on its Startup and Enterprise plans and redistribution licenses on Enterprise, so check your plan before you display the data to others or build a product on it. CBOE index prices need separate CBOE approval. Nothing here is investment advice. This actor is an independent tool and is not made or endorsed by Unusual Whales.

# Actor input Schema

## `mode` (type: `string`):

Flow alerts are the provider's unusual options flow alerts (repeated hits, sweeps, floor trades). Unusual options activity lists the contracts flagged unusual on a day. Hottest chains screens every option contract. The option trades tape lists individual prints of the latest trading day. Option chain lists every contract of a ticker with quotes and greeks. The contract modes read trades or daily history of one option. Greek exposure, spot GEX by strike, IV rank, max pain and options volume read one ticker each. Dark pool, market tide, congress trades and insider transactions read those datasets.

## `tickers` (type: `array`):

Stock, ETF or index symbols such as AAPL, SPY, BRK.B or SPX, one per line. Per-ticker modes (option chain, greek exposure, spot GEX, IV rank, max pain, options volume, dark pool by ticker) read each ticker separately; flow alerts, unusual activity, hottest chains, the trades tape and insider transactions filter by all of them in one request; congress trades read one ticker at a time or the whole Congress when empty.

## `excludeTickers` (type: `array`):

Flow alerts, unusual activity, hottest chains, the trades tape and insider transactions. Tickers to leave out, one per line. Use either this or Tickers, not both.

## `contracts` (type: `array`):

Option contract trades and history. OSI option symbols, one per line: ticker, expiry as YYMMDD, C or P, then the strike times 1000 in 8 digits, for example TSLA250117C00250000.

## `date` (type: `string`):

A trading date such as 2026-01-30 for unusual activity, hottest chains, contract trades, greek exposure, spot GEX, IV rank, max pain, dark pool, market tide and congress trades. Defaults to the last trading date. Your plan sets how far back you can go.

## `from` (type: `string`):

Flow alerts, the trades tape and dark pool by ticker: the earliest time to read, as a date (2026-01-30), a date and time (2026-01-30T14:30:00Z) or a unix time. Insider transactions: the earliest transaction date (date only).

## `to` (type: `string`):

Same modes as From: the latest time or date to read. Rows are read newest first from here backwards.

## `unusualPreset` (type: `boolean`):

Flow alerts and hottest chains. Applies the provider's live options flow "unusual" criteria (volume over open interest, out of the money, 60 days or less to expiry, mostly ask side, premium of 10,000 USD or more). Any filter you set below overrides the matching part of the preset.

## `optionType` (type: `string`):

Flow alerts, hottest chains, the trades tape and the option chain.

## `side` (type: `string`):

Flow alerts (ask or bid), the trades tape and option contract trades.

## `alertRules` (type: `array`):

Flow alerts. Only these alert rules. Leave empty for all.

## `minPremium` (type: `integer`):

Flow alerts, unusual activity, hottest chains, the trades tape, contract trades and dark pool prints. The smallest total premium, for example 100000 for six figure orders.

## `maxPremium` (type: `integer`):

Flow alerts, hottest chains, the trades tape and dark pool prints.

## `minSize` (type: `integer`):

Flow alerts, the trades tape (contracts) and dark pool prints (shares).

## `minDte` (type: `integer`):

Flow alerts, hottest chains, the trades tape and the option chain.

## `maxDte` (type: `integer`):

Flow alerts, unusual activity, hottest chains, the trades tape and the option chain. 0 means expiring today (0DTE).

## `minVolumeOiRatio` (type: `number`):

Flow alerts, hottest chains and the trades tape. 1 means volume at least equal to open interest.

## `otmOnly` (type: `boolean`):

Flow alerts, hottest chains, the trades tape, the option chain and market tide.

## `volumeGreaterOi` (type: `boolean`):

Flow alerts, hottest chains, the trades tape and the option chain.

## `sizeGreaterOi` (type: `boolean`):

Flow alerts and the trades tape. A strong hint of new positions.

## `openingOnly` (type: `boolean`):

Flow alerts (all trades opening) and the trades tape. The provider notes repeated hits alerts are rarely all opening, so this mostly keeps floor and sweep alerts.

## `multiLeg` (type: `string`):

Flow alerts and the trades tape. Spreads and other multi-leg orders.

## `issueTypes` (type: `array`):

Flow alerts, unusual activity, hottest chains and the trades tape.

## `sectors` (type: `array`):

Unusual activity, hottest chains, the trades tape and insider transactions.

## `minMarketcap` (type: `number`):

Flow alerts, hottest chains, the trades tape and insider transactions.

## `maxMarketcap` (type: `number`):

Same modes as the minimum.

## `expiry` (type: `string`):

Hottest chains, the trades tape and the option chain. One expiry such as 2026-01-16.

## `minStrike` (type: `number`):

Hottest chains, the trades tape and spot GEX by strike.

## `maxStrike` (type: `number`):

Same modes as the minimum.

## `screenerSort` (type: `string`):

Hottest chains. The field the screen is ordered by.

## `sortDirection` (type: `string`):

Hottest chains.

## `lookback` (type: `string`):

Greek exposure: YTD or a span such as 5D, 2W, 6M or 1Y. IV rank: 1w, 1m, 3m, 6m or 1y.

## `interval5m` (type: `boolean`):

Market tide. Untick for one minute intervals.

## `darkpoolSort` (type: `string`):

Dark pool prints across the market.

## `cancellation` (type: `string`):

Dark pool prints.

## `ownerName` (type: `string`):

Insider transactions. The name of the insider as filed, for example Huang Jen Hsun.

## `insiderRole` (type: `string`):

Insider transactions.

## `transactionCodes` (type: `array`):

Insider transactions. SEC Form 4 codes, one per line: P purchase, S sale, M option exercise, A award, G gift, F tax withholding.

## `formTypes` (type: `array`):

Insider transactions. Form 144 is a notice of intended sale; pick 4 and 4/A for executed trades only.

## `minValue` (type: `integer`):

Insider transactions.

## `sp500Only` (type: `boolean`):

Insider transactions.

## `groupTransactions` (type: `boolean`):

Insider transactions. The provider groups one person's transactions with the same code on the same day into one row; untick to read every transaction.

## `maxResults` (type: `integer`):

The most rows this run returns and charges for, across all tickers and contracts. Pages are read up to the provider's page size (200 flow alerts, 500 trades) until this ceiling.

## `requestsPerMinute` (type: `integer`):

Pacing. Your plan sets a per-minute cap, and the actor waits for the reset and retries when the provider answers 429.

## `apiKey` (type: `string`):

Your own Unusual Whales API token (a UUID from your API dashboard). Stored as a secret and sent only in the Authorization header; it is never logged. You can instead set the DATA_API_KEY environment secret.

## Actor input object example

```json
{
  "mode": "flowAlerts",
  "tickers": [
    "SPY"
  ],
  "optionType": "all",
  "side": "all",
  "multiLeg": "any",
  "screenerSort": "premium",
  "sortDirection": "desc",
  "lookback": "1y",
  "interval5m": true,
  "darkpoolSort": "executed_at",
  "cancellation": "all",
  "insiderRole": "any",
  "groupTransactions": true,
  "maxResults": 100,
  "requestsPerMinute": 60
}
```

# Actor output Schema

## `records` (type: `string`):

One row per flow alert, contract, print, series point or disclosure.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "tickers": [
        "SPY"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("nabeelbaghoor/options-flow-dark-pool-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "tickers": ["SPY"] }

# Run the Actor and wait for it to finish
run = client.actor("nabeelbaghoor/options-flow-dark-pool-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "tickers": [
    "SPY"
  ]
}' |
apify call nabeelbaghoor/options-flow-dark-pool-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/options-flow-dark-pool-api"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/ScjoNVnWEccQb8gwe/builds/R0EIlEYl8K2xVPbf1/openapi.json