Bullflow API

Connection

• Endpoint: https://api.bullflow.io/mcp
• Transport: MCP Streamable HTTP
• Supported method: POST
• Unsupported methods return an MCP error response. GET and DELETE are not valid for this endpoint.
• When using SSE endpoint metadata returned by MCP tools, it is recommended to implement auto reconnect functionality in your client in case the stream is disconnected for any reason.

Authentication

Public docs and the four free closing-data tools need no credentials. Other tools require subscriber access through one of the following:

• OAuth: Authorization: Bearer YOUR_ACCESS_TOKEN, or query string: ?key=YOUR_API_KEY
• Header: X-API-Key: YOUR_API_KEY
• Header: Authorization: Bearer YOUR_API_KEY
• Subscriber tools request account connection when credentials are missing or expired. Check isError in tool results even when HTTP returns 200.

Available tools

• bullflow_free_delayed_gex_tickers — available public GEX tickers with each snapshot's capture timestamp and session date, with no account.
• bullflow_free_delayed_gex_snapshot — GEX delayed by at least 15 minutes, including the strike-by-expiration heat map, exposure totals, and key levels for a supported ticker, with no account.
• bullflow_free_options_flow_related_tickers — up to six related tickers with recorded premium and trade totals from the same closing session, with no account.
• bullflow_free_gex_tickers — available public closing GEX tickers and session dates, with no account.
• bullflow_free_gex_summary — closing spot, total net GEX and up to 12 strikes for a supported ticker, with no account.
• bullflow_free_options_flow_tickers — available public closing options-flow tickers and session dates, with no account.
• bullflow_free_options_flow_summary — recorded session totals and up to 12 largest-premium trades for a supported ticker, with no account.
• bullflow_api_docs — returns API docs and MCP connection details.
• bullflow_peak_return — runs the peak return lookup with the current MCP connection's API key.
• bullflow_net_gex — looks up calculated net GEX with the current MCP connection. Accepts ticker and optional type: oi (default) or volume. Volume uses the current or most recent U.S. Eastern trading day.
• bullflow_net_vex — runs the net VEX lookup with the current MCP connection's API key.
• bullflow_net_premium_series — returns cumulative call and put net premium values with the current MCP connection's API key.
• bullflow_historical_options_flow — returns historical options trades with date, ticker, contract, trade filters, and pagination using the current connection's credentials.
• bullflow_options_profile — summarizes recorded ticker activity, 20-session relative volume, execution-side premium, sweeps, and unusual contracts.
• bullflow_options_top_tickers — returns leading option-flow tickers ranked by volume, premium, or directional net premium.
• bullflow_gex_alerts — returns GEX proximity and node movement alerts filtered by date range, ticker, and alert type.
• bullflow_last_trade_price — runs the last trade price lookup with the current MCP connection's API key.
• bullflow_dark_pool_trades — runs the dark pool trades lookup with the current MCP connection's API key.
• bullflow_get_custom_alerts — returns saved custom alerts for the current MCP connection's API key account.
• bullflow_create_alert — creates a saved custom alert for the current MCP connection's API key account.
• bullflow_streaming_endpoint — returns connection details for live alerts or backtesting replay SSE.
• bullflow_live_options_flow_endpoint — returns the live options flow SSE URL, authentication guidance, event types, and public trade fields.
• bullflow_backtesting_replay_sample — collects a bounded replay sample for agent workflows.

All free tools share 60 requests per fixed minute per client IP with the free REST endpoints. Read snapshot_date for the trading session and snapshot_timestamp for delayed GEX freshness; the latest capture may be older outside recording hours. A rate-limit error has structuredContent.status=429 and data.retryAfterSeconds; wait before retrying.

Resource

• bullflow://api-docs — YAML docs resource exposed by the MCP server.

Query params

• key — required API key value generated in the dashboard.

Event payloads

• Each SSE data: frame contains JSON. Parse that JSON and use event to identify the payload type.
• event === "init" — provides mode (alerts) and startedAt (ISO timestamp).
• event === "heartbeat" — emitted every 10 seconds to keep the connection alive; safe to ignore.
• event === "alert" — includes the alert id and the alert payload in data.
• Alert payloads include data.alertType, data.symbol, data.alertName, data.alertPremium, data.averageFillPrice, and data.timestamp.
• data.alertType — either algo (Bullflow algo alerts such as Urgent Repeater, Sizable Sweep, etc.) or custom (alerts matching the custom alerts you set in the Bullflow dashboard).
• Alert payloads also include data.latency, data.deliveryLatency, and data.receivedAt.
• Authentication, subscription, and connection-throttle failures are returned as normal HTTP JSON errors before the SSE stream begins.
• Custom alert delivery is limited to 10 custom alerts per 60 seconds and 1000 custom alerts per 12 hours. API subscribers receive up to 60 custom alerts per 60 seconds and 5000 custom alerts per 12 hours.
• It is recommended to implement auto reconnect functionality in your SSE client in case the stream is disconnected for any reason. Live alert streams only deliver alerts created after the connection opens.

Authentication

Requires an OAuth token with the relevant permission or an active Bullflow API key. For API keys, pass it as ?key=YOUR_API_KEY, an X-API-Key header, or an Authorization: Bearer YOUR_API_KEY header.

Query params

• key — required when the API key is not supplied in a header.
• history — optional boolean, defaults to false. When true, the first event contains all alerts from the current U.S. Eastern market date, ordered oldest-first.

Event payloads

• Each SSE data: frame contains JSON. Use its top-level event field to route the payload.
• event === "history" — sent first only when history=true. Its data object contains version, date, timezone, alertCount, and an oldest-first alerts array.
• event === "init" — confirms the connection with mode (gex-setups) and startedAt.
• event === "heartbeat" — keeps the connection alive and is safe to ignore.
• event === "gex_setup" — contains one newly created setup in data.
• Every setup includes id, type, ticker, slot, date, alertedAt, classification, severity, title, message, spotPrice, and previousSpotPrice.
• Setup-specific fields may include thresholdPercent, expiration, nodeStrike, nodeGex, distancePercent, absoluteDistancePercent, oldNodeStrike, newNodeStrike, oldNodeExpiration, newNodeExpiration, oldNodeGex, newNodeGex, and severityScore.
• Live setup frames also include an SSE id: line matching data.id, which clients can use for deduplication.
• Reconnecting with history=true sends the current day's history again, so use each alert's id if your client needs to deduplicate reconnects.

Query params

• key — required API key value.
• date — required replay date in YYYY-MM-DD format. Must be on or after 2025-06-01 and cannot be in the future.
• speed — optional replay speed multiplier. Passing 1 replays in real time.

Event payloads

• Each SSE data: frame contains JSON. Parse that JSON and use event to identify the payload type.
• event === "init" — includes mode (alerts-backtesting), replayDate, and connected.
• event === "status" — a single initialization message: Initializing trades, custom alerts and algo alerts... This can take up to a minute.
• event === "ready" — includes replayDate, speed, totalTrades, totalCustomAlerts, processedTrades, customAlerts, algoAlerts, and totalReplayAlerts.
• event === "heartbeat" — emitted during replay gaps and includes playbackTime such as 10:42:14 EST.
• event === "alert" — includes sequence, id, and a data object with alertType, symbol, alertName, alertPremium, tradePrice, timestamp, and estTimestamp.
• data.alertType — either algo or custom.
• event === "complete" — includes alertsSent, totalTrades, customAlerts, algoAlerts, totalReplayAlerts, and elapsedSeconds.
• event === "error" — sent before the stream closes if the request cannot be loaded or replayed.
• It is recommended to implement auto reconnect functionality in your SSE client in case the stream is disconnected for any reason.

Query params

• key — required for subscription or prepaid-credit access; optional when paying per request.
• sym — required option symbol, for example O:SPY260408C00520000.
• old_price — required entry price for the contract.
• trade_timestamp — required Unix timestamp for the trade.

Behavior

• Successful responses return a JSON object with the peak price and the peak percent return since the provided timestamp.
• Subscription requests require a valid API key. Per-request payments use the payment challenge instead.
• This endpoint is rate-limited to 60 requests per rolling 60 seconds per credential or payer, per endpoint.

Query params

• key — required for subscription or prepaid-credit access; optional when paying per request.
• ticker — required underlying ticker symbol, for example SPY. sym is also accepted as an alias.
• type — optional: oi (default) weights exposure by open interest; volume uses cumulative contracts traded during the current or most recent U.S. Eastern trading day.

Behavior

• Gamma and spot calculations refresh approximately every 5 seconds. Volume mode uses the latest available cumulative contract volume for 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.
• Successful responses return a JSON object with ticker, spot_price, as_of, and strikes.
• Each strike row includes expiration, strike, call_gex, put_gex, net_gex, call_gamma, and put_gamma.
• GEX uses a 1% underlying-price move: gamma × selected contract count × 100 × spot price squared × 0.01. Gamma fields equal gamma × selected contract count × 100. Calls contribute positively and puts negatively; net_gex is their sum. Expiration uses YYYYMMDD and strike prices are in dollars.
• Once the current session has volume, all tickers use that session. Contracts with no volume in the selected session contribute zero. No matching volume returns an empty strikes array. Unavailable volume returns HTTP 503 with Intraday contract volume is temporarily unavailable.
• Both weighting modes share this endpoint's limit of 60 requests per rolling 60 seconds per credential or payer, per endpoint.
• Each endpoint has a separate limit, shared across its tickers, dates, filters, and pages. API-key requests share the key’s limit, OAuth connections on the same account share its limit, and paid requests share the payer’s limit.
• Bursts are allowed within the quota. No minimum spacing is required between requests, but at most 60 requests are allowed in any rolling 60-second window.
• Throttled requests return HTTP 429 with Retry-After in seconds. Wait at least that long before retrying.
• Coordinate clients using the same credential or payer to stay within 60 requests per rolling 60 seconds per endpoint, and honor Retry-After on HTTP 429.

Query params

• key — required for subscription or prepaid-credit access; optional when paying per request.
• ticker — required underlying ticker symbol, for example SPY. sym is also accepted as an alias.

Behavior

• 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.
• Successful responses return a JSON object with ticker, spot_price, as_of, and strikes.
• Each strike row includes expiration, strike, call_vex, put_vex, net_vex, call_vanna, and put_vanna.
• Net VEX uses spot_price * vanna * open_interest and calculates net_vex as call VEX plus put VEX.
• This endpoint is rate-limited to 60 requests per rolling 60 seconds per credential or payer, per endpoint.
• Each endpoint has a separate limit, shared across its tickers, dates, filters, and pages. API-key requests share the key’s limit, OAuth connections on the same account share its limit, and paid requests share the payer’s limit.
• Bursts are allowed within the quota. No minimum spacing is required between requests, but at most 60 requests are allowed in any rolling 60-second window.
• Throttled requests return HTTP 429 with Retry-After in seconds. Wait at least that long before retrying.
• Coordinate clients using the same credential or payer to stay within 60 requests per rolling 60 seconds per endpoint, and honor Retry-After on HTTP 429.

Query params

• key — required for subscription or prepaid-credit access; optional when paying per request.
• ticker — required underlying ticker symbol, for example SPY.
• from — required inclusive start date in YYYY-MM-DD format.
• to — required inclusive end date in YYYY-MM-DD format.
• period — optional aggregation period: 1D, 7D, 1M, 3M, 1Y, or MAX. Defaults to 1D.
• include_multileg — optional boolean. Defaults to false.
• sweeps_only — optional boolean. Defaults to false.

Behavior

• Each point contains a Unix timestamp, cumulative callsNetPremium, and cumulative putsNetPremium.
• bucket_seconds reports the time bucket size. A value of 0 means individual time points.
• Results are returned in chronological order.
• This endpoint is rate-limited to 60 requests per rolling 60 seconds per credential or payer, per endpoint.

Request and access

symbol is required: supply an underlying ticker such as AAPL; letters are normalized to uppercase. Use an API key with an active API subscription or enough prepaid credits in key or X-API-Key, or an active Bullflow Premium or API subscription with an OAuth bearer token with api:read. You can also pay per REST request with x402 or MPP; inspect the live payment challenge for methods and pricing. The limit is 60 requests per rolling 60 seconds per credential or payer, per endpoint. Honor Retry-After on HTTP 429. The MCP tool is bullflow_options_profile and accepts the same symbol input with subscriber access.

Session and comparison baseline

The latest date with recorded activity across tickers is selected. Before new-session activity, on weekends, and on holidays, this can be the most recent completed session. A ticker with no recorded trades returns zero totals for that selected session. Check tradingDate and asOf for freshness.

• relativeVolumeDaily: selected-session recorded volume / average full-day recorded volume over the prior 20 available trading dates.
• relativeVolumeIntraday: selected-session recorded volume / average volume through the same Eastern time of asOf over those dates. Daylight-saving changes are accounted for.
• callRelativeVolumeDaily, callRelativeVolumeIntraday, putRelativeVolumeDaily, and putRelativeVolumeIntraday apply the same formulas to calls or puts.
• The selected session is excluded from the baseline. Dates with no activity for the ticker contribute zero; unavailable dates are not assumed to be zero-volume sessions. Shortened sessions contribute their available activity.
• Fewer than 20 prior dates makes relative-volume ratios null. Ratios and percentages are also null when their denominator is zero. For a past session, the cutoff is 23:59:59 Eastern and both comparisons use full days.

Response fields

• symbol and tradingDate identify the ticker and selected trading session.
• asOf is the latest recorded trade time across tickers in the selected session, in UTC ISO 8601.
• activity: totalVolume, callVolume, putVolume, the relative-volume ratios above, and putCallRatio (put volume / call volume). Volumes sum recorded trade sizes, including multi-leg trades.
• premium: totalPremium, callPremium, putPremium, and netDirectionalPremium, all in USD.
• Directional premium = call ask premium − call bid premium − put ask premium + put bid premium. These four side premiums exclude multi-leg trades; mid and unknown executions contribute zero. Total call and put premiums include multi-leg trades. Execution-side direction does not establish opening positions or trader intent.
• execution: callAskSidePercent and putAskSidePercent, from 0–100. Ask and above-ask contract volume is divided by all recorded volume for that option type.
• concentration: sweepPremium (USD), sweepVolumePercent, and shortDatedVolumePercent. Short-dated means 0–7 calendar days from the trading date, inclusive.
• unusualContracts: up to five contracts with recorded volume/OI > 1, ranked by ratio, then premium, then symbol. Fields are symbol (option contract), type (CALL/PUT), strike, expiration, volume, openInterest, volumeOiRatio, premium, and askSidePercent. OI uses its latest available observation; zero or missing OI is excluded. Strike is USD and expiration is YYYY-MM-DD; unavailable descriptive fields are null.
• largestPremiumTrade: a separate single trade, or null. Includes contract symbol, type, strike, expiration, UTC timestamp, trade volume, USD premium, tradeType (SWEEP/BLOCK/MULTI), and side (Ask/Above Ask/Mid/Bid/Below Bid); unavailable descriptive fields are null.

Structured flags

• INSUFFICIENT_HISTORY: fewer than 20 prior available trading dates.
• NO_RECORDED_ACTIVITY: no recorded ticker volume in the selected session.
• CALL_VOLUME_SPIKE / PUT_VOLUME_SPIKE: the corresponding intraday relative volume is at least 2.
• CALL_BUYING_SURGE: call intraday relative volume is at least 2 and call ask-side volume is at least 70%. This describes execution-side classification.
• UNUSUAL_WEEKLY_ACTIVITY: a contract expiring in 0–7 days has recorded volume/OI of at least 2. This does not identify the exchange's weekly listing designation.

Query params

• key — required for subscription or prepaid-credit access; optional when paying per request.
• date — optional single trading date in YYYY-MM-DD format. Cannot be combined with from or to.
• from — optional start date for an inclusive range in YYYY-MM-DD format. Must be supplied with to.
• to — optional end date for an inclusive range in YYYY-MM-DD format. Must be supplied with from; the range cannot exceed 30 days.
• metric — optional ranking metric: volume, premium, or net_premium. Defaults to premium.
• ticker_count — optional result count: 10, 20, 30, 40, or 50. Defaults to 20.
• exclude_etfs — optional boolean that excludes ETF option flow. Defaults to false.
• sweeps_only — optional boolean that limits results to sweep trades. Defaults to false.
• bullish_bearish — optional boolean for net_premium. When enabled, returns a balanced selection of bullish and bearish leaders. Defaults to false.

Behavior

• When date, from, and to are omitted, the endpoint returns the current trading day's flow.
• A supplied date returns that day's ranking. A supplied from/to pair aggregates all available trading days in the inclusive range.
• Volume results include totalVolume, callVolume, and putVolume for each ticker.
• Premium results include totalPremium, callPremium, and putPremium for each ticker.
• Net-premium results include directional call and put values plus ask-side and bid-side premium breakdowns. totalNetPremium is call net premium minus put net premium.
• This endpoint is rate-limited to 60 requests per rolling 60 seconds per credential or payer, per endpoint.

Query params

• key — required for subscription or prepaid-credit access; optional when paying per request.
• ticker — required stock or supported index ticker symbol, for example SPY or SPX. sym is also accepted as an alias.

Behavior

• Successful responses return a JSON object with lastTradePrice and timestamp. When present, timestamp is UTC and uses ISO 8601 format with a trailing Z.
• Subscription requests require a valid API key. Per-request payments use the payment challenge instead.
• This endpoint is rate-limited to 60 requests per rolling 60 seconds per credential or payer, per endpoint.

Query params

• key — your API key for subscription or prepaid-credit access; omit when paying per request or using an OAuth bearer token with api:read permission.
• date — optional single date in YYYY-MM-DD format.
• from and to — inclusive date range, up to 30 calendar days. Supply both; do not combine with date.
• ticker — optional stock, ETF, or index ticker.
• type — optional gex_node_proximity, largest_node_moved_higher, or largest_node_moved_lower.
• limit — page size from 1 to 5,000; defaults to 500.
• cursor — the preceding response's nextCursor. Keep the same date, ticker, and type filters.

Response

Returns version, from, to, timezone, applied ticker and type filters (null when omitted),count, limit, hasMore, nextCursor, and alerts. The count is for the current page. Alerts are ordered by date, detection time, and identifier, newest first.

Each alert contains id, type, ticker, date,alertedAt, classification, severity, title,message, spotPrice, previousSpotPrice, thresholdPercent,expiration, nodeStrike, nodeGex, distancePercent, and absoluteDistancePercent. Movement alerts also populate oldNodeStrike,newNodeStrike, oldNodeExpiration, newNodeExpiration,oldNodeGex, newNodeGex, and severityScore. Fields that do not apply are null. Expirations use YYYYMMDD; prices are in USD, GEX values are signed, and distances are percentages.

Limits and errors

60 requests per rolling 60 seconds per credential or payer, per endpoint. Invalid parameters or cursors return 400. Throttled requests return 429 with Retry-After in seconds. Unavailable alert data returns 503; unexpected failures return 500.

Query params

• key — required for subscription or prepaid-credit access; optional when paying per request.
• from — required start date in YYYY-MM-DD format.
• to — required end date in YYYY-MM-DD format.
• ticker — optional stock ticker symbol, for example SPY.
• limit — optional page size. Defaults to 500 and cannot exceed 5000.
• cursor — optional pagination cursor from a previous response's nextCursor field.
• minNotional — optional minimum trade notional value.

Behavior

• Date ranges are inclusive. Passing the same date for from and to returns trades for that day.
• This endpoint returns trades reported through Nasdaq trade reporting data. Based on Nasdaq's public figures, FINRA/Nasdaq TRFs support more than 40% of total U.S. equities trading while off-exchange trading is over 45% of volume, making Nasdaq-reported off-exchange flow roughly 90% of U.S. off-exchange equity trading.
• The date range cannot exceed 30 days.
• Successful responses return from, to, ticker, minNotional, count, limit, hasMore, nextCursor, and rows.
• When hasMore is true, pass nextCursor as cursor on the next request to fetch the following page.
• Condition codes can be cross-referenced against Nasdaq Trader's sale condition modifier definitions.
• This endpoint is rate-limited to 60 requests per rolling 60 seconds per credential or payer, per endpoint.