Options Flow API

Connect to live alerts

Generate a key in your API dashboard and set it as the BULLFLOW_API_KEY environment variable. Keep the key on your server and out of public frontend code.

curl --no-buffer --get \
  'https://api.bullflow.io/v1/streaming/alerts' \
  --data-urlencode "key=$BULLFLOW_API_KEY"

The Python example uses the requests package. The connection stays open while events arrive; stop the example with Ctrl+C. Authentication and access errors are returned before streaming begins.

Stream live options trades

GET /v1/streaming/live-options-flow delivers newly published options trades for the current U.S. Eastern trading date. The date changes at midnight while your connection remains open, and heartbeats arrive every 10 seconds.

Use an active subscriber API key in X-API-Key, key, or an Authorization bearer header. OAuth connections require api:read permission. There is one active live flow connection per API key; opening another replaces the previous connection.

import json
import os
import requests

with requests.get(
    "https://api.bullflow.io/v1/streaming/live-options-flow",
    headers={"X-API-Key": os.environ["BULLFLOW_API_KEY"]},
    stream=True, timeout=(10, 35),
) as response:
    response.raise_for_status()
    for line in response.iter_lines(chunk_size=1, decode_unicode=True):
        if line and line.startswith("data: "):
            message = json.loads(line[6:])
            if message["event"] == "trade":
                trade = message["data"]
                print(trade["symbol"], trade["premium"], trade["timestamp"])

Read the JSON event field to handle init, trade, heartbeat, date_changed, and error messages. Trade payloads include cancellation flags and public price, size, contract, and Greek fields.

Reconnect with a delay and honor Retry-After on 429 responses. Reconnecting delivers future trades only. Agents can use bullflow_live_options_flow_endpoint for connection details.

Read stream events

Each SSE data: frame contains JSON. Read its event field to distinguish connection updates from an alert.

init

Connection established. Includes the stream mode and start time.

heartbeat

Sent every 10 seconds to keep the connection alive.

alert

An alert ID and its payload, including the option symbol, premium, and alert type.

{
  "event": "alert",
  "id": "example-alert-id",
  "data": {
    "alertType": "algo",
    "symbol": "O:AMD251205P00205000",
    "alertName": "Urgent Repeater",
    "alertPremium": 16965.0,
    "averageFillPrice": 1.31,
    "timestamp": 1764708086.0
  }
}

alertType distinguishes Bullflow algo alerts from custom alerts. alertPremium is the premium of the triggering trade; averageFillPrice is its average fill price.

Custom Options Flow Alerts

Save a set of options flow filters in Bullflow or create an alert through the API. Matching custom alerts arrive on the live stream associated with the same API key account.

Query historical options flow

For a ticker snapshot, Options Activity Profile adds daily and same-time relative volume, premium, execution-side activity, and unusual contracts.

GET /v1/data/historicalOptionsFlow returns recorded options trades for one date or an inclusive range of up to 30 calendar days. Supply date or both from and to. Dates refer to U.S. Eastern trading dates, and future dates are rejected.

Filter by ticker, exact option symbol, call or put, trade type, execution side, premium, contract count, and minimum SigScore. Cancelled trades are excluded. Results are newest first, with 500 trades per page by default and a maximum of 5000.

import os
import requests

response = requests.get(
    "https://api.bullflow.io/v1/data/historicalOptionsFlow",
    params={
        "key": os.environ["BULLFLOW_API_KEY"],
        "date": "2026-09-25", "ticker": "SPY",
        "minPremium": 100000, "limit": 500,
    },
    timeout=35,
)
response.raise_for_status()
page = response.json()
for trade in page["rows"]:
    print(trade["symbol"], trade["premium"], trade["timestamp"])

Follow nextCursor with the same filters while hasMore is true. The rate limit is 10 requests per minute per API key; honor Retry-After on a 429 response. Agents can use bullflow_historical_options_flow through MCP.

Plan for disconnects

The live stream delivers alerts created after the connection opens. Reconnecting resumes live delivery; it does not replay the events missed while disconnected. Add retry handling with a delay to your production client.

Custom alert delivery limits depend on your subscription. Check the live alert reference for limits and the complete payload.