Bullflow API

Build your tools and agents with Bullflow market data

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.

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.

Subscriber REST endpoints, including custom-alert reads and creation, allow 60 requests per rolling 60 seconds per credential or payer, separately for each endpoint. All tickers, dates, filters, and pages on the same endpoint share its limit. Bursts are allowed, with no minimum spacing between requests; at most 60 requests are allowed in any rolling 60-second window. HTTP 429 includes Retry-After in seconds.

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 60 requests per rolling 60 seconds per credential or payer.

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 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: 60 requests per rolling 60 seconds per credential or payer, per endpoint. Available through API-key subscription or prepaid credits (4 credits per successful response), OAuth api:read, x402, MPP, and the subscriber MCP tool bullflow_eod_gex.

History is ticker-dependent and may have gaps. Earliest available snapshots verified on 2026-10-19: AAPL and QQQ 2012-06-01; SPY 2017-01-03; HOOD 2021-08-05. These are verified coverage examples, not a universal cutoff or a guarantee for every session. Dates outside a ticker’s available history return HTTP 404.

GET /v1/data/historicalGex

Request open-interest-weighted gamma exposure for supported GEX tickers at an exact snapshot time using ticker and an ISO timestamp with a UTC offset or Z. Choose all expirations or one expiration in YYYY-MM-DD. Returns historical spot price, signed call/put/net GEX totals, expiration and strike detail, and quality counters for the complete snapshot.

Snapshots follow a five-minute schedule in America/New_York: an opening snapshot at 09:31, then 09:35, 09:40, and every five minutes through 16:00 on regular sessions or the actual early close. Coverage is limited to supported GEX tickers and is expanding toward three years; dates and snapshot times vary. An unavailable ticker, snapshot time, or expiration returns 404 without substituting another snapshot. Contracts with unavailable IV or gamma contribute zero GEX and are reflected in quality counters.

Included with an active API subscription, or 4 prepaid credits per successful response. Failed requests do not consume credits. x402 and MPP payments are not accepted. Limit: 60 requests per rolling 60 seconds per credential, per endpoint. Read historical GEX documentation.

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

Give your AI agents the market context they need

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.

Connect your workflow to live market data

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

Choose how you pay for API access.

Buy credits for occasional REST requests, or subscribe for ongoing access with real-time streams and tools for AI agents.

Pay as you go — no subscription

Prepaid API credits start at $5 for 500 credits in the API dashboard. Purchases of $10+ receive 5% extra credits, $25+ receive 8%, and $50+ receive 10%, capped at 10%. The highest eligible bonus applies to the full purchase, rounded down to whole credits; refunds and disputes recalculate credits based on the remaining payment. Each successful REST response costs 1–10 credits; each page is a separate request, and failed responses do not consume credits. Credits do not grant MCP, OAuth, or streaming access. An active API subscription takes priority without spending credits, and active API subscribers cannot buy credits.

Buy API credits

API subscription

Monthly plan: $129/month. Unlimited requests within rate limits and access to streaming endpoints. Yearly plan: $99/month. Unlimited requests within rate limits and access to streaming endpoints. 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.

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 free closing market data

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.

GET /v1/optionsFlowClosingSnapshotSummary?ticker=SPY also needs no key or payment and returns recorded session totals and up to 12 largest-premium trades. Choose supported tickers from the options-flow availability list.

Choose available GEX tickers from GET /v1/gexClosingSnapshots. The four public GEX and options-flow summaries and availability lists and their free MCP tools share 60 requests per fixed minute per client IP; over-limit requests return 429 with Retry-After.

Paid live data and full-history products are separate. Prepaid API-key REST requests cost 1–10 credits per successful response; credits start at $5 for 500 in the API dashboard. Failed requests do not consume credits. Separate 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. The four free closing-data MCP tools need no account; other market-data tools and streams require subscriber access.