Bullflow API

Agent-ready Options data for your stack

Stream low-latency options flow and GEX setup alerts over server-sent events (SSE), connect AI agents through MCP, manage custom alerts, and query exposure, ticker rankings, last trade prices, dark pool trades, and peak returns. Bullflow API is designed for traders and developers building automated scanners, notification systems, and research pipelines.

Get Started Read API Docs

Personal-use license only. Contact for commercial.

What you get with Bullflow API

Real-time Bullflow alerts

Receive algorithmic options flow alerts as they are detected.

Custom alert delivery

Create custom filters in Bullflow and stream them through the same feed.

Developer-first integration

Simple endpoints, production-ready payloads, and straightforward onboarding.

Historical backtesting

Replay one trading day over SSE with saved custom alerts and Bullflow algo alerts in timestamp order.

Live GEX setup alerts

Stream newly created GEX setups with classification, severity, spot price, and optional current-day history.

Peak return data

Query contract-level peak price and peak percent return after a trade timestamp.

Net GEX and net VEX data

Fetch strike and expiration-level gamma and vanna exposure for an underlying ticker.

Options market rankings

Query net premium history and rank top option-flow tickers by volume, premium, or net premium for the current day, a selected date, or an inclusive range.

Price and dark pool data

Look up Nasdaq-reported last trade prices or search dark pool trades by date, ticker, and minimum notional.

Alert management

Create saved custom alerts and retrieve existing custom alert configurations through JSON endpoints.

MCP server for AI agents

Connect coding agents to Bullflow API tools so they can inspect docs, draft requests, and build alert workflows faster.

API endpoints

Stream and backtest alerts, manage custom alerts, and query exposure, premium, ticker rankings, prices, dark pool trades, and post-trade peak returns.

GET /v1/streaming/live-options-flow

Stream newly published options trades with contract, premium, size, price, and Greek fields. The trading date changes at midnight U.S. Eastern time while connections remain open; heartbeats arrive every 10 seconds. API-key access requires an active API subscription; OAuth access requires an active Bullflow Premium or API subscription with api:read permission.

GET /v1/streaming/alerts

Stream Bullflow algo alerts and custom alert matches for your API key account in real time over SSE.

GET /v1/streaming/gexSetups

Stream newly created GEX setup alerts over SSE, with optional current-market-day history before live events begin.

GET /v1/streaming/backtesting

Replay a historical trading day over SSE with date and speed controls, ready events, heartbeat events, alert payloads, and a completion summary.

GET /v1/data/netgex

Return calculated net GEX by strike and expiration for an underlying ticker, including call, put, and net GEX rows. Omit type or use type=oi for open-interest weighting; use type=volume for cumulative contract volume from the current or most recent U.S. Eastern trading day.

Gamma and spot calculations refresh approximately every 5 seconds. Volume reflects the latest available contracts traded during the current or most recent U.S. Eastern trading day. Before a new session has volume, and on weekends or holidays, it uses the most recent completed trading day. Check as_of for the gamma and spot calculation timestamp. Both modes share the limit of 25 requests per rolling 60 seconds per API key.

GET /v1/data/eodGex

Request an end-of-day GEX snapshot with ticker and optional YYYY-MM-DD date. Returns closing underlying price, signed call/put/net GEX and weighted gamma by strike and expiration, and the open-interest date. Uses closing gamma with the open interest reported for the selected session, representing the previous session’s close. Defaults to the latest eligible session after 17:15 America/New_York. Limit: 10 requests per rolling 60 seconds per credential or payer. Available through API subscription, OAuth api:read, x402, MPP, and the subscriber MCP tool bullflow_eod_gex.

GET /v1/data/netvex

Return net VEX by strike and expiration for an underlying ticker, including call, put, and net VEX rows.

Results are cached for 5 seconds per ticker. Repeated requests within that window may return the same calculation; the next request after expiry recalculates using the latest available data. Check as_of for the calculation timestamp.

GET /v1/data/peakReturn

Submit an option symbol, old price, and trade timestamp to receive the highest price and peak percent return reached after that trade.

GET /v1/data/netPremiumSeries

Return chronological cumulative call and put net premium values for a ticker and inclusive date range with configurable aggregation and trade filters.

GET /v1/data/optionsProfile

Options Activity Profile summarizes recorded ticker volume, call/put premium, execution-side direction, sweeps, and unusual contracts. Supply symbol=AAPL. Daily and same-time Eastern relative volume use the prior 20 available trading dates; insufficient history or a zero denominator returns null. Also available through bullflow_options_profile. Recorded flow coverage does not establish complete market-wide volume.

GET /v1/data/optionsTopTickers

Rank the leading option-flow tickers by volume, premium, or directional net premium for the current trading day, a selected date, or an inclusive date range.

GET /v1/data/historicalOptionsFlow

Query recorded historical options trades for one date or a range of up to 30 calendar days, with ticker, contract, premium, size, score, and execution-side filters and newest-first pagination. Also available through the bullflow_historical_options_flow MCP tool.

GET /v1/data/lastTradePrice

Return the latest trade price for a stock or supported index ticker. The timestamp is UTC in ISO 8601 format with a trailing Z.

GET /v1/data/darkPoolTrades

Query Nasdaq-reported dark pool trades across an inclusive date range with ticker, minimum notional, limit, and cursor controls.

GET /v1/alerts/custom-alerts

Return saved custom alerts for the account associated with your API key.

POST /v1/alerts/create-alert

Create a saved custom alert for your API key account using clean filter fields and dashboard-style quick filters.

Read the endpoint docs

MCP server for AI agents

The Bullflow MCP server lets AI coding agents connect directly to structured API docs and supported Bullflow tools. Agents can use it to accelerate integration work, generate cleaner request code, inspect endpoint behavior, and create more intelligent workflows with live alerts, GEX setups, exposure, ticker rankings, prices, dark pool trades, peak returns, and custom alert context. 

https://api.bullflow.io/mcp?key=YOUR_API_KEY

Agent-ready API context

Give Cursor, Claude Code, Codex, and other AI agents a structured Bullflow API surface instead of scattered documentation.

Faster integration loops

Agents can discover endpoint metadata, draft requests, test payload shapes, and wire alert workflows with less manual copy-paste.

Smarter alert design

Combine live flow, GEX setups, exposure, ticker rankings, prices, dark pool trades, peak returns, and saved alert tools for richer context-aware logic.

Python quickstart

Connect to the live alerts stream and print the first alert symbol:

import json
import requests
from types import SimpleNamespace

with requests.get(
    "https://api.bullflow.io/v1/streaming/alerts",
    params={"key": "YOUR_API_KEY"},
    stream=True,
) as stream:
    stream.raise_for_status()
    for line in stream.iter_lines(decode_unicode=True):
        if not line or not line.startswith("data: "):
            continue
        payload = json.loads(
            line[6:],
            object_hook=lambda d: SimpleNamespace(**d),
        )
        if payload.event != "alert":
            continue
        print(payload.data.symbol)
        break

Simple API pricing

Monthly plan: $129/month. Yearly plan: $99/month billed annually. Both include real-time unusual options flow, historical options flow and backtesting endpoints, Options Activity Profiles, MCP server access, GEX setup streams, custom alert endpoints, and the documented market-data endpoints.

Personal-use license only. Contact for commercial.

Start Subscription View Pricing Details

Common API questions

  • How does it work? Connect to the stream endpoint and process real-time alert payloads in your app.
  • Can I create custom alerts? Yes. Custom dashboard alerts are delivered through the API feed, and historical backtesting evaluates replayed trades against your current saved custom alert set.
  • Can I backtest alerts? Yes. Use the backtesting endpoint to replay a historical trading day over SSE with saved custom alerts and Bullflow algo alerts in timestamp order.
  • Can I get access to the full options flow? Right now we only offer access to live trades triggered by custom alerts that you create or algo alerts that we generate.

Try a free closing GEX summary

GET /v1/gexClosingSnapshotSummary?ticker=SPY needs no key or payment and returns the previous trading session’s closing spot price, total net GEX and up to 12 strikes with the largest absolute exposure.

Choose available tickers from GET /v1/gexClosingSnapshots. Public GEX and options-flow summaries and availability lists share 60 requests per minute per client IP; over-limit requests return 429 with Retry-After.

Paid live data and full-history products are separate. Eligible paid REST requests: x402 USDC on Base $0.01/request; MPP USDC.e on Tempo $0.01/request; MPP card/Link $0.50/request. The live 402 challenge confirms supported methods and the final price; network fees may apply. MCP and streams require subscriber access.