{"openapi":"3.1.0","info":{"title":"Bullflow Market Data API","version":"1.1.0","description":"Free public closing GEX and options-flow summaries need no account, key, or payment. Other U.S. stock and options market data: gamma and vanna exposure, net premium, options activity, dark pool trades, and trade prices. Access with an API key backed by an active API subscription or prepaid credits, or an offered x402/MPP payment method. Buy credits in the API dashboard from $5 for 500 credits. Credits do not grant MCP, OAuth, or streaming access.","contact":{"email":"support@bullflow.io","url":"https://www.bullflow.io/api/docs"},"x-guidance":"Send GET query parameters described for each endpoint. Free closing data operations have security: [] and need no credentials or payment. For other operations, authenticate with X-API-Key, key, or an Authorization bearer credential. An API key uses the active API subscription first and prepaid credits otherwise. Do not purchase more credits without user authorization; active API subscribers cannot buy credits. For separate x402/MPP access, first call without credentials and inspect HTTP 402. Approve the live quote and retry with exactly one payment credential. Its quote is separate from prepaid credit pricing. Do not assume a method is available merely because it is documented. Dates are YYYY-MM-DD; check response timestamps for freshness. Follow nextCursor with unchanged filters. Honor Retry-After and avoid immediate retry loops. Private alerts, app-only endpoints, and streaming services are outside this discovery catalog."},"servers":[{"url":"https://api.bullflow.io"}],"externalDocs":{"url":"https://www.bullflow.io/api/docs","description":"Public API reference and examples"},"tags":[{"name":"Free market data","description":"60 requests per fixed minute per client IP, shared across all free closing-data and delayed-GEX REST endpoints and their MCP tools. REST HTTP 429 includes Retry-After in seconds. MCP tool errors set isError and structuredContent.status=429 with data.retryAfterSeconds; the HTTP transport can still return 200."},{"name":"Market data","description":"Options activity and market prices"}],"paths":{"/v1/data/netgex":{"get":{"operationId":"bullflow_net_gex","summary":"Net gamma exposure","description":"Gamma exposure by strike and expiration. Uses open interest by default; type=volume uses cumulative contract volume from the current or most recent trading day. Check as_of for response timing. Limit: 60 requests per rolling 60 seconds separately per endpoint per credential or payer. Bursts are allowed within that quota. All ticker, date, filter, pagination, and mode variants of an endpoint share its limit. HTTP 429 includes Retry-After in seconds. With a prepaid API key, each successful response costs 4 credits ($0.04). Each page is a separate request. Failed responses do not consume credits. Active API subscriptions cover these requests without spending credits or an additional payment.","x-prepaid-credits":{"credits":4,"currency":"USD","amount":"0.04","charged_on":"successful_response"},"tags":["Market data"],"security":[{"apiKeyHeader":[]},{"apiKeyQuery":[]},{"bearerAuth":[]},{"x402Payment":[]},{"mppPayment":[]},{"mppPaymentHeader":[]}],"x-payment-info":{"protocols":[{"x402":{}},{"mpp":{"method":"stripe","intent":"charge","currency":"usd"}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC"}}],"price":{"mode":"dynamic","currency":"USD","min":"0.01","max":"0.50"}},"parameters":[{"name":"ticker","in":"query","required":true,"description":"Underlying stock, ETF, or supported index ticker.","schema":{"type":"string","description":"Underlying stock, ETF, or supported index ticker.","examples":["SPY"]},"example":"SPY"},{"name":"type","in":"query","required":false,"description":"type","schema":{"type":"string","enum":["oi","volume"],"default":"oi"}}],"responses":{"200":{"description":"Net gamma exposure. Example values are illustrative, not live data.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ticker":{"type":"string"},"spot_price":{"type":"number","description":"Amount in US dollars."},"as_of":{"type":"string","description":"ISO 8601 timestamp."},"strikes":{"type":"array","items":{"type":"object","properties":{"expiration":{"type":"string","description":"Option expiration date in YYYYMMDD format."},"strike":{"type":"number","description":"Amount in US dollars."},"call_gex":{"type":"number"},"put_gex":{"type":"number"},"net_gex":{"type":"number"},"call_gamma":{"type":"number","description":"Call gamma times contract count (open interest by default or cumulative contract volume from the current or most recent trading day with type=volume) times 100."},"put_gamma":{"type":"number","description":"Negative put gamma times contract count (open interest by default or cumulative contract volume from the current or most recent trading day with type=volume) times 100."}},"required":["expiration","strike","call_gex","put_gex","net_gex","call_gamma","put_gamma"]},"description":"Exposure by strike and expiration; net_gex is the net exposure."}},"required":["ticker","spot_price","as_of","strikes"]},"example":{"ticker":"SPY","spot_price":600,"as_of":"2026-10-14T19:00:00Z","strikes":[{"expiration":"20261016","strike":600,"call_gex":200000,"put_gex":-100000,"net_gex":100000,"call_gamma":55.5556,"put_gamma":-27.7778}]}}}},"400":{"description":"Invalid query parameters. No payment is settled for an unsuccessful data response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required or insufficient prepaid credits. Add credits in the API dashboard, use an active API subscription, or approve one offered x402/MPP method and retry with its payment credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"PAYMENT-REQUIRED":{"description":"Base USDC x402 payment requirements when offered; retry using PAYMENT-SIGNATURE.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"MPP payment challenges when offered; retry using Authorization: Payment or Payment-Authorization.","schema":{"type":"string"}}}},"404":{"description":"No matching data is available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; honor Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds to wait before retrying."}}},"503":{"description":"Data or the selected payment method is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/data/eodGex":{"get":{"operationId":"bullflow_eod_gex","summary":"End-of-day gamma exposure","description":"Closing gamma exposure by strike and expiration. Defaults to the latest eligible trading session; each session becomes eligible after 17:15 America/New_York. date and open_interest_date identify the represented sessions. Limit: 60 requests per rolling 60 seconds separately per endpoint per credential or payer. Bursts are allowed within that quota. All ticker, date, filter, pagination, and mode variants of an endpoint share its limit. HTTP 429 includes Retry-After in seconds. With a prepaid API key, each successful response costs 4 credits ($0.04). Each page is a separate request. Failed responses do not consume credits. Active API subscriptions cover these requests without spending credits or an additional payment.","x-prepaid-credits":{"credits":4,"currency":"USD","amount":"0.04","charged_on":"successful_response"},"tags":["Market data"],"security":[{"apiKeyHeader":[]},{"apiKeyQuery":[]},{"bearerAuth":[]},{"x402Payment":[]},{"mppPayment":[]},{"mppPaymentHeader":[]}],"x-payment-info":{"protocols":[{"x402":{}},{"mpp":{"method":"stripe","intent":"charge","currency":"usd"}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC"}}],"price":{"mode":"dynamic","currency":"USD","min":"0.01","max":"0.50"}},"parameters":[{"name":"ticker","in":"query","required":true,"description":"Underlying stock, ETF, or supported index ticker.","schema":{"type":"string","description":"Underlying stock, ETF, or supported index ticker.","examples":["SPY"]},"example":"SPY"},{"name":"date","in":"query","required":false,"description":"Trading date in YYYY-MM-DD format.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Trading date in YYYY-MM-DD format."}}],"responses":{"200":{"description":"End-of-day gamma exposure. Example values are illustrative, not live data.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ticker":{"type":"string"},"spot_price":{"type":"number","description":"Amount in US dollars."},"as_of":{"type":"string","description":"Timestamp of the closing underlying price used in the snapshot, in UTC."},"strikes":{"type":"array","items":{"type":"object","properties":{"expiration":{"type":"string","description":"Option expiration date in YYYYMMDD format."},"strike":{"type":"number","description":"Amount in US dollars."},"call_gex":{"type":"number"},"put_gex":{"type":"number"},"net_gex":{"type":"number"}},"required":["expiration","strike","call_gex","put_gex","net_gex"]},"description":"Call, put, and net GEX in USD per 1% underlying move, by strike and expiration."},"date":{"type":"string","description":"Selected trading date in YYYY-MM-DD format. Historical availability varies by ticker and session; unavailable history returns HTTP 404."},"open_interest_date":{"type":"string","description":"Previous trading date whose closing positions are represented by the open interest reported for this session."},"timezone":{"type":"string","const":"America/New_York"}},"required":["ticker","spot_price","as_of","strikes","date","open_interest_date","timezone"],"description":"End-of-day GEX using closing gamma and underlying price with the open interest reported for the selected session. GEX is in USD per 1% underlying move; calls are positive and puts negative."},"example":{"ticker":"SPY","spot_price":600,"as_of":"2026-10-14T20:00:00Z","date":"2026-10-14","open_interest_date":"2026-10-13","timezone":"America/New_York","strikes":[{"expiration":"20261016","strike":600,"call_gex":200000,"put_gex":-100000,"net_gex":100000}]}}}},"400":{"description":"Invalid query parameters. No payment is settled for an unsuccessful data response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required or insufficient prepaid credits. Add credits in the API dashboard, use an active API subscription, or approve one offered x402/MPP method and retry with its payment credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"PAYMENT-REQUIRED":{"description":"Base USDC x402 payment requirements when offered; retry using PAYMENT-SIGNATURE.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"MPP payment challenges when offered; retry using Authorization: Payment or Payment-Authorization.","schema":{"type":"string"}}}},"404":{"description":"No matching data is available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; honor Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds to wait before retrying."}}},"503":{"description":"Data or the selected payment method is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/data/netvex":{"get":{"operationId":"bullflow_net_vex","summary":"Net vanna exposure","description":"Vanna exposure by strike and expiration, with the underlying spot price and response timestamp. Limit: 60 requests per rolling 60 seconds separately per endpoint per credential or payer. Bursts are allowed within that quota. All ticker, date, filter, pagination, and mode variants of an endpoint share its limit. HTTP 429 includes Retry-After in seconds. With a prepaid API key, each successful response costs 4 credits ($0.04). Each page is a separate request. Failed responses do not consume credits. Active API subscriptions cover these requests without spending credits or an additional payment.","x-prepaid-credits":{"credits":4,"currency":"USD","amount":"0.04","charged_on":"successful_response"},"tags":["Market data"],"security":[{"apiKeyHeader":[]},{"apiKeyQuery":[]},{"bearerAuth":[]},{"x402Payment":[]},{"mppPayment":[]},{"mppPaymentHeader":[]}],"x-payment-info":{"protocols":[{"x402":{}},{"mpp":{"method":"stripe","intent":"charge","currency":"usd"}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC"}}],"price":{"mode":"dynamic","currency":"USD","min":"0.01","max":"0.50"}},"parameters":[{"name":"ticker","in":"query","required":true,"description":"Underlying stock, ETF, or supported index ticker.","schema":{"type":"string","description":"Underlying stock, ETF, or supported index ticker.","examples":["SPY"]},"example":"SPY"}],"responses":{"200":{"description":"Net vanna exposure. Example values are illustrative, not live data.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ticker":{"type":"string"},"spot_price":{"type":"number","description":"Amount in US dollars."},"as_of":{"type":"string","description":"ISO 8601 timestamp."},"strikes":{"type":"array","items":{"type":"object","properties":{"expiration":{"type":"string","description":"Option expiration date in YYYYMMDD format."},"strike":{"type":"number","description":"Amount in US dollars."},"call_vex":{"type":"number"},"put_vex":{"type":"number"},"net_vex":{"type":"number"},"call_vanna":{"type":"number","description":"Weighted call vanna."},"put_vanna":{"type":"number","description":"Weighted put vanna."}},"required":["expiration","strike","call_vex","put_vex","net_vex","call_vanna","put_vanna"]},"description":"Exposure by strike and expiration; net_vex is the net exposure."}},"required":["ticker","spot_price","as_of","strikes"]},"example":{"ticker":"SPY","spot_price":600,"as_of":"2026-10-14T19:00:00Z","strikes":[{"expiration":"20261016","strike":600,"call_vex":200000,"put_vex":-100000,"net_vex":100000,"call_vanna":0.5,"put_vanna":-0.25}]}}}},"400":{"description":"Invalid query parameters. No payment is settled for an unsuccessful data response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required or insufficient prepaid credits. Add credits in the API dashboard, use an active API subscription, or approve one offered x402/MPP method and retry with its payment credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"PAYMENT-REQUIRED":{"description":"Base USDC x402 payment requirements when offered; retry using PAYMENT-SIGNATURE.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"MPP payment challenges when offered; retry using Authorization: Payment or Payment-Authorization.","schema":{"type":"string"}}}},"404":{"description":"No matching data is available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; honor Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds to wait before retrying."}}},"503":{"description":"Data or the selected payment method is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/data/netPremiumSeries":{"get":{"operationId":"bullflow_net_premium_series","summary":"Net premium time series","description":"Cumulative call and put net premium over the selected period or date range. Premium values are in USD. Limit: 60 requests per rolling 60 seconds separately per endpoint per credential or payer. Bursts are allowed within that quota. All ticker, date, filter, pagination, and mode variants of an endpoint share its limit. HTTP 429 includes Retry-After in seconds. With a prepaid API key, each successful response costs 2 credits ($0.02). Each page is a separate request. Failed responses do not consume credits. Active API subscriptions cover these requests without spending credits or an additional payment.","x-prepaid-credits":{"credits":2,"currency":"USD","amount":"0.02","charged_on":"successful_response"},"tags":["Market data"],"security":[{"apiKeyHeader":[]},{"apiKeyQuery":[]},{"bearerAuth":[]},{"x402Payment":[]},{"mppPayment":[]},{"mppPaymentHeader":[]}],"x-payment-info":{"protocols":[{"x402":{}},{"mpp":{"method":"stripe","intent":"charge","currency":"usd"}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC"}}],"price":{"mode":"dynamic","currency":"USD","min":"0.01","max":"0.50"}},"parameters":[{"name":"ticker","in":"query","required":true,"description":"Underlying stock, ETF, or supported index ticker.","schema":{"type":"string","description":"Underlying stock, ETF, or supported index ticker.","examples":["SPY"]},"example":"SPY"},{"name":"from","in":"query","required":false,"description":"Inclusive start date for a custom range; supply with to.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Inclusive start date for a custom range; supply with to."}},{"name":"to","in":"query","required":false,"description":"Inclusive end date for a custom range; supply with from.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Inclusive end date for a custom range; supply with from."}},{"name":"period","in":"query","required":false,"description":"period","schema":{"type":"string","enum":["1D","7D","1M","3M","1Y","MAX"],"default":"1D"},"example":"1D"},{"name":"include_multileg","in":"query","required":false,"description":"include_multileg","schema":{"type":"boolean","default":false}},{"name":"sweeps_only","in":"query","required":false,"description":"sweeps_only","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Net premium time series. Example values are illustrative, not live data.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ticker":{"type":"string"},"period":{"type":"string","enum":["1D","7D","1M","3M","1Y","MAX"]},"from":{"type":"string","description":"Trading date in YYYY-MM-DD format."},"to":{"type":"string","description":"Trading date in YYYY-MM-DD format."},"include_multileg":{"type":"boolean"},"sweeps_only":{"type":"boolean"},"multilegs_filtered_count":{"type":"integer","minimum":0,"maximum":9007199254740991},"sweeps_filtered_count":{"type":"integer","minimum":0,"maximum":9007199254740991},"bucket_seconds":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Bucket duration in seconds; zero denotes individual time points."},"point_count":{"type":"integer","minimum":0,"maximum":9007199254740991},"points":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"number","description":"Unix timestamp in seconds."},"callsNetPremium":{"type":"number","description":"Cumulative call net premium in USD."},"putsNetPremium":{"type":"number","description":"Cumulative put net premium in USD."}},"required":["timestamp","callsNetPremium","putsNetPremium"]}}},"required":["ticker","period","from","to","include_multileg","sweeps_only","multilegs_filtered_count","sweeps_filtered_count","bucket_seconds","point_count","points"]},"example":{"ticker":"SPY","period":"1D","from":"2026-10-14","to":"2026-10-14","include_multileg":false,"sweeps_only":false,"multilegs_filtered_count":0,"sweeps_filtered_count":0,"bucket_seconds":0,"point_count":0,"points":[]}}}},"400":{"description":"Invalid query parameters. No payment is settled for an unsuccessful data response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required or insufficient prepaid credits. Add credits in the API dashboard, use an active API subscription, or approve one offered x402/MPP method and retry with its payment credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"PAYMENT-REQUIRED":{"description":"Base USDC x402 payment requirements when offered; retry using PAYMENT-SIGNATURE.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"MPP payment challenges when offered; retry using Authorization: Payment or Payment-Authorization.","schema":{"type":"string"}}}},"404":{"description":"No matching data is available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; honor Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds to wait before retrying."}}},"503":{"description":"Data or the selected payment method is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/data/lastTradePrice":{"get":{"operationId":"bullflow_last_trade_price","summary":"Latest trade price","description":"Latest available trade price for a stock or supported index. timestamp is the trade time when available; market closures can leave the latest trade in an earlier session. Limit: 60 requests per rolling 60 seconds separately per endpoint per credential or payer. Bursts are allowed within that quota. All ticker, date, filter, pagination, and mode variants of an endpoint share its limit. HTTP 429 includes Retry-After in seconds. With a prepaid API key, each successful response costs 1 credits ($0.01). Each page is a separate request. Failed responses do not consume credits. Active API subscriptions cover these requests without spending credits or an additional payment.","x-prepaid-credits":{"credits":1,"currency":"USD","amount":"0.01","charged_on":"successful_response"},"tags":["Market data"],"security":[{"apiKeyHeader":[]},{"apiKeyQuery":[]},{"bearerAuth":[]},{"x402Payment":[]},{"mppPayment":[]},{"mppPaymentHeader":[]}],"x-payment-info":{"protocols":[{"x402":{}},{"mpp":{"method":"stripe","intent":"charge","currency":"usd"}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC"}}],"price":{"mode":"dynamic","currency":"USD","min":"0.01","max":"0.50"}},"parameters":[{"name":"ticker","in":"query","required":true,"description":"Underlying stock, ETF, or supported index ticker.","schema":{"type":"string","description":"Underlying stock, ETF, or supported index ticker.","examples":["SPY"]},"example":"SPY"}],"responses":{"200":{"description":"Latest trade price. Example values are illustrative, not live data.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"lastTradePrice":{"type":"number","description":"Amount in US dollars."},"timestamp":{"description":"Trade time when available; null or absent means unavailable.","anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]}},"required":["lastTradePrice"]},"example":{"lastTradePrice":600,"timestamp":"2026-10-14T19:00:00Z"}}}},"400":{"description":"Invalid query parameters. No payment is settled for an unsuccessful data response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required or insufficient prepaid credits. Add credits in the API dashboard, use an active API subscription, or approve one offered x402/MPP method and retry with its payment credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"PAYMENT-REQUIRED":{"description":"Base USDC x402 payment requirements when offered; retry using PAYMENT-SIGNATURE.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"MPP payment challenges when offered; retry using Authorization: Payment or Payment-Authorization.","schema":{"type":"string"}}}},"404":{"description":"No matching data is available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; honor Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds to wait before retrying."}}},"503":{"description":"Data or the selected payment method is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/data/darkPoolTrades":{"get":{"operationId":"bullflow_dark_pool_trades","summary":"Dark pool trades","description":"One page of dark pool trades for an inclusive date range of at most 30 days. Follow nextCursor to retrieve additional pages. Limit: 60 requests per rolling 60 seconds separately per endpoint per credential or payer. Bursts are allowed within that quota. All ticker, date, filter, pagination, and mode variants of an endpoint share its limit. HTTP 429 includes Retry-After in seconds. With a prepaid API key, each successful response costs 3 credits ($0.03). Each page is a separate request. Failed responses do not consume credits. Active API subscriptions cover these requests without spending credits or an additional payment.","x-prepaid-credits":{"credits":3,"currency":"USD","amount":"0.03","charged_on":"successful_response"},"tags":["Market data"],"security":[{"apiKeyHeader":[]},{"apiKeyQuery":[]},{"bearerAuth":[]},{"x402Payment":[]},{"mppPayment":[]},{"mppPaymentHeader":[]}],"x-payment-info":{"protocols":[{"x402":{}},{"mpp":{"method":"stripe","intent":"charge","currency":"usd"}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC"}}],"price":{"mode":"dynamic","currency":"USD","min":"0.01","max":"0.50"}},"parameters":[{"name":"from","in":"query","required":true,"description":"Inclusive start date. Supply with to; do not combine with date.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Inclusive start date. Supply with to; do not combine with date."},"example":"2026-10-14"},{"name":"to","in":"query","required":true,"description":"Inclusive end date. Supply with from; maximum range is 30 calendar days.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Inclusive end date. Supply with from; maximum range is 30 calendar days."},"example":"2026-10-14"},{"name":"ticker","in":"query","required":false,"description":"Underlying stock, ETF, or supported index ticker.","schema":{"type":"string","description":"Underlying stock, ETF, or supported index ticker.","examples":["SPY"]},"example":"SPY"},{"name":"minNotional","in":"query","required":false,"description":"Minimum trade notional in USD.","schema":{"type":"number","minimum":0,"description":"Minimum trade notional in USD."}},{"name":"limit","in":"query","required":false,"description":"Maximum number of records in this page.","schema":{"type":"integer","minimum":1,"maximum":5000,"default":500,"description":"Maximum number of records in this page."},"example":10},{"name":"cursor","in":"query","required":false,"description":"Use nextCursor from the previous page with the same filters.","schema":{"type":"string","description":"Use nextCursor from the previous page with the same filters."}}],"responses":{"200":{"description":"Dark pool trades. Example values are illustrative, not live data.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"from":{"type":"string","description":"Trading date in YYYY-MM-DD format."},"to":{"type":"string","description":"Trading date in YYYY-MM-DD format."},"ticker":{"type":["string","null"]},"minNotional":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"count":{"type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"type":"integer","minimum":0,"maximum":9007199254740991},"hasMore":{"type":"boolean"},"nextCursor":{"description":"Pass as cursor to read the next page; null when there is no next page.","type":["string","null"]},"rows":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"price":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"size":{"type":["number","null"]},"notional":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"trfTimestampMs":{"description":"Trade report timestamp in Unix milliseconds, when available.","type":["number","null"]},"tradeDate":{"anyOf":[{"type":"string","description":"Trading date in YYYY-MM-DD format."},{"type":"null"}]}},"required":["symbol","price","size","notional","trfTimestampMs","tradeDate"],"additionalProperties":{}},"description":"One page of trades, not a full-day total."}},"required":["from","to","ticker","minNotional","count","limit","hasMore","nextCursor","rows"]},"example":{"from":"2026-10-14","to":"2026-10-14","ticker":"SPY","minNotional":null,"count":0,"limit":10,"hasMore":false,"nextCursor":null,"rows":[]}}}},"400":{"description":"Invalid query parameters. No payment is settled for an unsuccessful data response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required or insufficient prepaid credits. Add credits in the API dashboard, use an active API subscription, or approve one offered x402/MPP method and retry with its payment credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"PAYMENT-REQUIRED":{"description":"Base USDC x402 payment requirements when offered; retry using PAYMENT-SIGNATURE.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"MPP payment challenges when offered; retry using Authorization: Payment or Payment-Authorization.","schema":{"type":"string"}}}},"404":{"description":"No matching data is available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; honor Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds to wait before retrying."}}},"503":{"description":"Data or the selected payment method is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/data/peakReturn":{"get":{"operationId":"bullflow_peak_return","summary":"Option peak return","description":"Highest option price and percent return observed after the supplied trade timestamp, relative to the entry price. Limit: 60 requests per rolling 60 seconds separately per endpoint per credential or payer. Bursts are allowed within that quota. All ticker, date, filter, pagination, and mode variants of an endpoint share its limit. HTTP 429 includes Retry-After in seconds. With a prepaid API key, each successful response costs 10 credits ($0.10). Each page is a separate request. Failed responses do not consume credits. Active API subscriptions cover these requests without spending credits or an additional payment.","x-prepaid-credits":{"credits":10,"currency":"USD","amount":"0.10","charged_on":"successful_response"},"tags":["Market data"],"security":[{"apiKeyHeader":[]},{"apiKeyQuery":[]},{"bearerAuth":[]},{"x402Payment":[]},{"mppPayment":[]},{"mppPaymentHeader":[]}],"x-payment-info":{"protocols":[{"x402":{}},{"mpp":{"method":"stripe","intent":"charge","currency":"usd"}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC"}}],"price":{"mode":"dynamic","currency":"USD","min":"0.01","max":"0.50"}},"parameters":[{"name":"sym","in":"query","required":true,"description":"Option contract symbol, for example O:SPY261016C00650000.","schema":{"type":"string","description":"Option contract symbol, for example O:SPY261016C00650000."},"example":"O:SPY261016C00650000"},{"name":"old_price","in":"query","required":true,"description":"Entry price in USD per share.","schema":{"type":"number","exclusiveMinimum":0,"description":"Entry price in USD per share."},"example":1.35},{"name":"trade_timestamp","in":"query","required":true,"description":"Trade Unix timestamp in seconds.","schema":{"type":"number","exclusiveMinimum":0,"description":"Trade Unix timestamp in seconds."},"example":1791984600}],"responses":{"200":{"description":"Option peak return. Example values are illustrative, not live data.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"peakPriceSinceTimestamp":{"type":"string","description":"Highest option price in USD, formatted to two decimal places."},"peakPercentReturnSinceTimestamp":{"type":"number","description":"Peak return in percent relative to the supplied entry price."}},"required":["peakPriceSinceTimestamp","peakPercentReturnSinceTimestamp"]},"example":{"peakPriceSinceTimestamp":"1.50","peakPercentReturnSinceTimestamp":11.11}}}},"400":{"description":"Invalid query parameters. No payment is settled for an unsuccessful data response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required or insufficient prepaid credits. Add credits in the API dashboard, use an active API subscription, or approve one offered x402/MPP method and retry with its payment credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"PAYMENT-REQUIRED":{"description":"Base USDC x402 payment requirements when offered; retry using PAYMENT-SIGNATURE.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"MPP payment challenges when offered; retry using Authorization: Payment or Payment-Authorization.","schema":{"type":"string"}}}},"404":{"description":"No matching data is available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; honor Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds to wait before retrying."}}},"503":{"description":"Data or the selected payment method is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/data/optionsTopTickers":{"get":{"operationId":"bullflow_options_top_tickers","summary":"Top options tickers","description":"Rank tickers by recorded options volume, premium, or directional net premium. Choose date or an inclusive from/to range of at most 30 days. With no dates, uses the latest available session. Limit: 60 requests per rolling 60 seconds separately per endpoint per credential or payer. Bursts are allowed within that quota. All ticker, date, filter, pagination, and mode variants of an endpoint share its limit. HTTP 429 includes Retry-After in seconds. With a prepaid API key, each successful response costs 3 credits ($0.03). Each page is a separate request. Failed responses do not consume credits. Active API subscriptions cover these requests without spending credits or an additional payment.","x-prepaid-credits":{"credits":3,"currency":"USD","amount":"0.03","charged_on":"successful_response"},"tags":["Market data"],"security":[{"apiKeyHeader":[]},{"apiKeyQuery":[]},{"bearerAuth":[]},{"x402Payment":[]},{"mppPayment":[]},{"mppPaymentHeader":[]}],"x-payment-info":{"protocols":[{"x402":{}},{"mpp":{"method":"stripe","intent":"charge","currency":"usd"}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC"}}],"price":{"mode":"dynamic","currency":"USD","min":"0.01","max":"0.50"}},"parameters":[{"name":"date","in":"query","required":false,"description":"Trading date in YYYY-MM-DD format.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Trading date in YYYY-MM-DD format."}},{"name":"from","in":"query","required":false,"description":"Inclusive start date. Supply with to; do not combine with date.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Inclusive start date. Supply with to; do not combine with date."}},{"name":"to","in":"query","required":false,"description":"Inclusive end date. Supply with from; maximum range is 30 calendar days.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Inclusive end date. Supply with from; maximum range is 30 calendar days."}},{"name":"metric","in":"query","required":false,"description":"metric","schema":{"type":"string","enum":["volume","premium","net_premium"],"default":"premium"},"example":"premium"},{"name":"ticker_count","in":"query","required":false,"description":"ticker_count","schema":{"type":"integer","enum":[10,20,30,40,50],"default":20},"example":20},{"name":"exclude_etfs","in":"query","required":false,"description":"exclude_etfs","schema":{"type":"boolean","default":false}},{"name":"sweeps_only","in":"query","required":false,"description":"sweeps_only","schema":{"type":"boolean","default":false}},{"name":"bullish_bearish","in":"query","required":false,"description":"Balance bullish and bearish leaders when metric=net_premium.","schema":{"type":"boolean","default":false,"description":"Balance bullish and bearish leaders when metric=net_premium."}}],"responses":{"200":{"description":"Top options tickers. Example values are illustrative, not live data.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"tradingDate":{"type":"string","description":"Latest trading date represented in the data."},"from":{"type":"string","description":"Trading date in YYYY-MM-DD format."},"to":{"type":"string","description":"Trading date in YYYY-MM-DD format."},"generatedAt":{"type":"string","description":"Response generation time, not the trading date."},"metric":{"type":"string","enum":["volume","premium","net_premium"]},"tickerCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"filters":{"type":"object","properties":{"excludeEtfs":{"type":"boolean"},"sweepsOnly":{"type":"boolean"},"bullishBearish":{"type":"boolean"}},"required":["excludeEtfs","sweepsOnly","bullishBearish"]},"sourceTradeCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"matchedTradeCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"count":{"type":"integer","minimum":0,"maximum":9007199254740991},"rows":{"type":"array","items":{"type":"object","properties":{"ticker":{"type":"string"},"totalVolume":{"description":"Total option contracts in volume mode.","type":"integer","minimum":0,"maximum":9007199254740991},"callVolume":{"type":"integer","minimum":0,"maximum":9007199254740991},"putVolume":{"type":"integer","minimum":0,"maximum":9007199254740991},"totalPremium":{"description":"Total option premium in premium mode.","type":"number"},"callPremium":{"type":"number","description":"Amount in US dollars."},"putPremium":{"type":"number","description":"Amount in US dollars."},"totalNetPremium":{"description":"Directional net premium: call net premium minus put net premium.","type":"number"},"callNetPremium":{"type":"number","description":"Amount in US dollars."},"putNetPremium":{"type":"number","description":"Amount in US dollars."},"callAskPremium":{"type":"number","description":"Amount in US dollars."},"callBidPremium":{"type":"number","description":"Amount in US dollars."},"putAskPremium":{"type":"number","description":"Amount in US dollars."},"putBidPremium":{"type":"number","description":"Amount in US dollars."},"rankedSide":{"type":"string","enum":["bullish","bearish"]},"rankedAbsoluteNetPremium":{"type":"number","description":"Amount in US dollars."}},"required":["ticker"],"additionalProperties":{}},"description":"Ranked aggregates for the selected metric and date range."}},"required":["tradingDate","from","to","generatedAt","metric","tickerCount","filters","sourceTradeCount","matchedTradeCount","count","rows"]},"example":{"tradingDate":"2026-10-14","from":"2026-10-14","to":"2026-10-14","generatedAt":"2026-10-14T19:00:00Z","metric":"premium","tickerCount":20,"filters":{"excludeEtfs":false,"sweepsOnly":false,"bullishBearish":false},"sourceTradeCount":0,"matchedTradeCount":0,"count":0,"rows":[]}}}},"400":{"description":"Invalid query parameters. No payment is settled for an unsuccessful data response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required or insufficient prepaid credits. Add credits in the API dashboard, use an active API subscription, or approve one offered x402/MPP method and retry with its payment credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"PAYMENT-REQUIRED":{"description":"Base USDC x402 payment requirements when offered; retry using PAYMENT-SIGNATURE.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"MPP payment challenges when offered; retry using Authorization: Payment or Payment-Authorization.","schema":{"type":"string"}}}},"404":{"description":"No matching data is available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; honor Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds to wait before retrying."}}},"503":{"description":"Data or the selected payment method is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/data/optionsProfile":{"get":{"operationId":"bullflow_options_profile","summary":"Ticker options activity profile","description":"Recorded options volume, premium, execution-side activity, relative-volume ratios, and unusual contracts for the latest available session. Ratios can be null when comparison history is insufficient; coverage is not a complete market-wide total. Limit: 60 requests per rolling 60 seconds separately per endpoint per credential or payer. Bursts are allowed within that quota. All ticker, date, filter, pagination, and mode variants of an endpoint share its limit. HTTP 429 includes Retry-After in seconds. With a prepaid API key, each successful response costs 3 credits ($0.03). Each page is a separate request. Failed responses do not consume credits. Active API subscriptions cover these requests without spending credits or an additional payment.","x-prepaid-credits":{"credits":3,"currency":"USD","amount":"0.03","charged_on":"successful_response"},"tags":["Market data"],"security":[{"apiKeyHeader":[]},{"apiKeyQuery":[]},{"bearerAuth":[]},{"x402Payment":[]},{"mppPayment":[]},{"mppPaymentHeader":[]}],"x-payment-info":{"protocols":[{"x402":{}},{"mpp":{"method":"stripe","intent":"charge","currency":"usd"}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC"}}],"price":{"mode":"dynamic","currency":"USD","min":"0.01","max":"0.50"}},"parameters":[{"name":"symbol","in":"query","required":true,"description":"Underlying stock, ETF, or supported index ticker.","schema":{"type":"string","description":"Underlying stock, ETF, or supported index ticker.","examples":["SPY"]},"example":"SPY"}],"responses":{"200":{"description":"Ticker options activity profile. Example values are illustrative, not live data.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"symbol":{"type":"string"},"tradingDate":{"type":"string","description":"Trading date in YYYY-MM-DD format."},"asOf":{"type":"string","description":"Latest recorded trade time across tickers in the selected session; the intraday comparison uses its Eastern time."},"activity":{"type":"object","properties":{"totalVolume":{"type":"integer","minimum":0,"maximum":9007199254740991},"callVolume":{"type":"integer","minimum":0,"maximum":9007199254740991},"putVolume":{"type":"integer","minimum":0,"maximum":9007199254740991},"relativeVolumeDaily":{"type":["number","null"]},"relativeVolumeIntraday":{"type":["number","null"]},"callRelativeVolumeDaily":{"type":["number","null"]},"callRelativeVolumeIntraday":{"type":["number","null"]},"putRelativeVolumeDaily":{"type":["number","null"]},"putRelativeVolumeIntraday":{"type":["number","null"]},"putCallRatio":{"type":["number","null"]}},"required":["totalVolume","callVolume","putVolume","relativeVolumeDaily","relativeVolumeIntraday","callRelativeVolumeDaily","callRelativeVolumeIntraday","putRelativeVolumeDaily","putRelativeVolumeIntraday","putCallRatio"],"description":"Volumes sum recorded trade sizes, including multi-leg trades. Relative volume uses the prior 20 available trading dates, excluding the selected session. Ratios are null with fewer than 20 dates or a zero denominator."},"premium":{"type":"object","properties":{"totalPremium":{"type":"number","description":"Amount in US dollars."},"callPremium":{"type":"number","description":"Amount in US dollars."},"putPremium":{"type":"number","description":"Amount in US dollars."},"netDirectionalPremium":{"type":"number","description":"Amount in US dollars."}},"required":["totalPremium","callPremium","putPremium","netDirectionalPremium"],"description":"Totals include multi-leg trades. Directional premium excludes multi-leg trades. Directional = call ask premium - call bid premium - put ask premium + put bid premium; mid/unknown executions contribute zero."},"execution":{"type":"object","properties":{"callAskSidePercent":{"type":["number","null"]},"putAskSidePercent":{"type":["number","null"]}},"required":["callAskSidePercent","putAskSidePercent"],"description":"Contract-volume-weighted ask/above-ask percentages, 0–100, using all recorded call or put volume as denominator."},"concentration":{"type":"object","properties":{"sweepPremium":{"type":"number","description":"Amount in US dollars."},"sweepVolumePercent":{"type":["number","null"]},"shortDatedVolumePercent":{"type":["number","null"]}},"required":["sweepPremium","sweepVolumePercent","shortDatedVolumePercent"],"description":"Short dated means 0–7 calendar days from tradingDate, inclusive."},"unusualContracts":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"type":{"type":"string","enum":["CALL","PUT"]},"strike":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"expiration":{"anyOf":[{"type":"string","description":"Trading date in YYYY-MM-DD format."},{"type":"null"}]},"volume":{"type":"integer","minimum":0,"maximum":9007199254740991},"openInterest":{"type":"integer","minimum":0,"maximum":9007199254740991},"volumeOiRatio":{"type":"number"},"premium":{"type":"number","description":"Amount in US dollars."},"askSidePercent":{"type":["number","null"]}},"required":["symbol","type","strike","expiration","volume","openInterest","volumeOiRatio","premium","askSidePercent"]},"description":"Up to five contracts with recorded volume/OI > 1, sorted by ratio, then premium, then symbol. OI uses the latest available observation. Zero/missing OI is excluded."},"largestPremiumTrade":{"anyOf":[{"type":"object","properties":{"symbol":{"type":["string","null"]},"type":{"type":"string","enum":["CALL","PUT"]},"strike":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"expiration":{"anyOf":[{"type":"string","description":"Trading date in YYYY-MM-DD format."},{"type":"null"}]},"timestamp":{"type":"string","description":"ISO 8601 timestamp."},"volume":{"type":"integer","minimum":0,"maximum":9007199254740991},"premium":{"type":"number","description":"Amount in US dollars."},"tradeType":{"type":["string","null"]},"side":{"type":["string","null"]}},"required":["symbol","type","strike","expiration","timestamp","volume","premium","tradeType","side"]},{"type":"null"}]},"flags":{"type":"array","items":{"type":"string","enum":["INSUFFICIENT_HISTORY","NO_RECORDED_ACTIVITY","CALL_VOLUME_SPIKE","PUT_VOLUME_SPIKE","CALL_BUYING_SURGE","UNUSUAL_WEEKLY_ACTIVITY"]}}},"required":["symbol","tradingDate","asOf","activity","premium","execution","concentration","unusualContracts","largestPremiumTrade","flags"]},"example":{"symbol":"SPY","tradingDate":"2026-10-14","asOf":"2026-10-14T19:00:00Z","activity":{"totalVolume":0,"callVolume":0,"putVolume":0,"relativeVolumeDaily":null,"relativeVolumeIntraday":null,"callRelativeVolumeDaily":null,"callRelativeVolumeIntraday":null,"putRelativeVolumeDaily":null,"putRelativeVolumeIntraday":null,"putCallRatio":null},"premium":{"totalPremium":0,"callPremium":0,"putPremium":0,"netDirectionalPremium":0},"execution":{"callAskSidePercent":null,"putAskSidePercent":null},"concentration":{"sweepPremium":0,"sweepVolumePercent":null,"shortDatedVolumePercent":null},"unusualContracts":[],"largestPremiumTrade":null,"flags":["NO_RECORDED_ACTIVITY","INSUFFICIENT_HISTORY"]}}}},"400":{"description":"Invalid query parameters. No payment is settled for an unsuccessful data response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required or insufficient prepaid credits. Add credits in the API dashboard, use an active API subscription, or approve one offered x402/MPP method and retry with its payment credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"PAYMENT-REQUIRED":{"description":"Base USDC x402 payment requirements when offered; retry using PAYMENT-SIGNATURE.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"MPP payment challenges when offered; retry using Authorization: Payment or Payment-Authorization.","schema":{"type":"string"}}}},"404":{"description":"No matching data is available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; honor Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds to wait before retrying."}}},"503":{"description":"Data or the selected payment method is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/data/historicalOptionsFlow":{"get":{"operationId":"bullflow_historical_options_flow","summary":"Historical options flow","description":"One page of recorded options trades, newest first. Supply date or both from and to, covering at most 30 days. Cancelled trades are excluded; unavailable fields are null. Follow nextCursor with the same filters. Limit: 60 requests per rolling 60 seconds separately per endpoint per credential or payer. Bursts are allowed within that quota. All ticker, date, filter, pagination, and mode variants of an endpoint share its limit. HTTP 429 includes Retry-After in seconds. With a prepaid API key, each successful response costs 5 credits ($0.05). Each page is a separate request. Failed responses do not consume credits. Active API subscriptions cover these requests without spending credits or an additional payment.","x-prepaid-credits":{"credits":5,"currency":"USD","amount":"0.05","charged_on":"successful_response"},"tags":["Market data"],"security":[{"apiKeyHeader":[]},{"apiKeyQuery":[]},{"bearerAuth":[]},{"x402Payment":[]},{"mppPayment":[]},{"mppPaymentHeader":[]}],"x-payment-info":{"protocols":[{"x402":{}},{"mpp":{"method":"stripe","intent":"charge","currency":"usd"}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC"}}],"price":{"mode":"dynamic","currency":"USD","min":"0.01","max":"0.50"}},"parameters":[{"name":"date","in":"query","required":false,"description":"Trading date in YYYY-MM-DD format.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Trading date in YYYY-MM-DD format."},"example":"2026-10-14"},{"name":"from","in":"query","required":false,"description":"Inclusive start date. Supply with to; do not combine with date.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Inclusive start date. Supply with to; do not combine with date."}},{"name":"to","in":"query","required":false,"description":"Inclusive end date. Supply with from; maximum range is 30 calendar days.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Inclusive end date. Supply with from; maximum range is 30 calendar days."}},{"name":"ticker","in":"query","required":false,"description":"Underlying stock, ETF, or supported index ticker.","schema":{"type":"string","description":"Underlying stock, ETF, or supported index ticker.","examples":["SPY"]},"example":"SPY"},{"name":"symbol","in":"query","required":false,"description":"Exact option contract symbol.","schema":{"type":"string","description":"Exact option contract symbol."}},{"name":"optionType","in":"query","required":false,"description":"optionType","schema":{"type":"string","enum":["C","P"]}},{"name":"tradeType","in":"query","required":false,"description":"tradeType","schema":{"type":"string","enum":["SWEEP","BLOCK","MULTI"]}},{"name":"side","in":"query","required":false,"description":"side","schema":{"type":"string","enum":["Ask","Above Ask","Mid","Bid","Below Bid"]}},{"name":"minPremium","in":"query","required":false,"description":"minPremium","schema":{"type":"number","minimum":0}},{"name":"maxPremium","in":"query","required":false,"description":"maxPremium","schema":{"type":"number","minimum":0}},{"name":"minSize","in":"query","required":false,"description":"minSize","schema":{"type":"integer","minimum":0}},{"name":"maxSize","in":"query","required":false,"description":"maxSize","schema":{"type":"integer","minimum":0}},{"name":"minScore","in":"query","required":false,"description":"minScore","schema":{"type":"number","minimum":0,"maximum":1}},{"name":"limit","in":"query","required":false,"description":"Maximum number of records in this page.","schema":{"type":"integer","minimum":1,"maximum":5000,"default":500,"description":"Maximum number of records in this page."},"example":10},{"name":"cursor","in":"query","required":false,"description":"Use nextCursor from the previous page with the same filters.","schema":{"type":"string","description":"Use nextCursor from the previous page with the same filters."}}],"responses":{"200":{"description":"Historical options flow. Example values are illustrative, not live data.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"from":{"type":"string","description":"Trading date in YYYY-MM-DD format."},"to":{"type":"string","description":"Trading date in YYYY-MM-DD format."},"timezone":{"type":"string","const":"America/New_York"},"ticker":{"type":["string","null"]},"symbol":{"type":["string","null"]},"optionType":{"anyOf":[{"type":"string","enum":["C","P"]},{"type":"null"}]},"tradeType":{"anyOf":[{"type":"string","enum":["SWEEP","BLOCK","MULTI"]},{"type":"null"}]},"side":{"anyOf":[{"type":"string","enum":["Ask","Above Ask","Mid","Bid","Below Bid"]},{"type":"null"}]},"minPremium":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"maxPremium":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"minSize":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"maxSize":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"minScore":{"type":["number","null"]},"count":{"type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"type":"integer","minimum":0,"maximum":9007199254740991},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]},"rows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tradeDate":{"type":"string","description":"Trading date in YYYY-MM-DD format."},"timestamp":{"type":"number","description":"Trade Unix timestamp in seconds."},"symbol":{"type":["string","null"]},"ticker":{"type":["string","null"]},"optionType":{"anyOf":[{"type":"string","enum":["C","P"]},{"type":"null"}]},"expirationDate":{"anyOf":[{"type":"string","description":"Trading date in YYYY-MM-DD format."},{"type":"null"}]},"strikePrice":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"premium":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"tradePrice":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"tradeSize":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"tradeType":{"type":["string","null"]},"side":{"type":["string","null"]},"spotPrice":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"currentBid":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"currentAsk":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"currentVolume":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"openInterest":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"impliedVolatility":{"description":"Implied volatility in percent.","type":["number","null"]},"sigScore":{"description":"Trade unusualness score, from 0 to 1.","type":["number","null"]},"delta":{"type":["number","null"]},"gamma":{"type":["number","null"]},"theta":{"type":["number","null"]},"vega":{"type":["number","null"]},"rho":{"type":["number","null"]}},"required":["id","tradeDate","timestamp","symbol","ticker","optionType","expirationDate","strikePrice","premium","tradePrice","tradeSize","tradeType","side","spotPrice","currentBid","currentAsk","currentVolume","openInterest","impliedVolatility","sigScore","delta","gamma","theta","vega","rho"]},"description":"One page of recorded options trades. Unavailable values are null."}},"required":["from","to","timezone","ticker","symbol","optionType","tradeType","side","minPremium","maxPremium","minSize","maxSize","minScore","count","limit","hasMore","nextCursor","rows"]},"example":{"from":"2026-10-14","to":"2026-10-14","timezone":"America/New_York","ticker":"SPY","symbol":null,"optionType":null,"tradeType":null,"side":null,"minPremium":null,"maxPremium":null,"minSize":null,"maxSize":null,"minScore":null,"count":0,"limit":10,"hasMore":false,"nextCursor":null,"rows":[]}}}},"400":{"description":"Invalid query parameters. No payment is settled for an unsuccessful data response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required or insufficient prepaid credits. Add credits in the API dashboard, use an active API subscription, or approve one offered x402/MPP method and retry with its payment credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"PAYMENT-REQUIRED":{"description":"Base USDC x402 payment requirements when offered; retry using PAYMENT-SIGNATURE.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"MPP payment challenges when offered; retry using Authorization: Payment or Payment-Authorization.","schema":{"type":"string"}}}},"404":{"description":"No matching data is available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; honor Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds to wait before retrying."}}},"503":{"description":"Data or the selected payment method is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/data/gexAlerts":{"get":{"operationId":"bullflow_gex_alerts","summary":"Gamma exposure alerts","description":"Near-node and largest-node movement alerts for the closest options expiration. Defaults to the current U.S. Eastern date; days without alerts return an empty list. Supply date or a from/to range of at most 30 days. Limit: 60 requests per rolling 60 seconds separately per endpoint per credential or payer. Bursts are allowed within that quota. All ticker, date, filter, pagination, and mode variants of an endpoint share its limit. HTTP 429 includes Retry-After in seconds. With a prepaid API key, each successful response costs 2 credits ($0.02). Each page is a separate request. Failed responses do not consume credits. Active API subscriptions cover these requests without spending credits or an additional payment.","x-prepaid-credits":{"credits":2,"currency":"USD","amount":"0.02","charged_on":"successful_response"},"tags":["Market data"],"security":[{"apiKeyHeader":[]},{"apiKeyQuery":[]},{"bearerAuth":[]},{"x402Payment":[]},{"mppPayment":[]},{"mppPaymentHeader":[]}],"x-payment-info":{"protocols":[{"x402":{}},{"mpp":{"method":"stripe","intent":"charge","currency":"usd"}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC"}}],"price":{"mode":"dynamic","currency":"USD","min":"0.01","max":"0.50"}},"parameters":[{"name":"date","in":"query","required":false,"description":"Trading date in YYYY-MM-DD format.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Trading date in YYYY-MM-DD format."}},{"name":"from","in":"query","required":false,"description":"Inclusive start date. Supply with to; do not combine with date.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Inclusive start date. Supply with to; do not combine with date."}},{"name":"to","in":"query","required":false,"description":"Inclusive end date. Supply with from; maximum range is 30 calendar days.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Inclusive end date. Supply with from; maximum range is 30 calendar days."}},{"name":"ticker","in":"query","required":false,"description":"Underlying stock, ETF, or supported index ticker.","schema":{"type":"string","description":"Underlying stock, ETF, or supported index ticker.","examples":["SPY"]},"example":"SPY"},{"name":"type","in":"query","required":false,"description":"type","schema":{"type":"string","enum":["gex_node_proximity","largest_node_moved_higher","largest_node_moved_lower"]}},{"name":"limit","in":"query","required":false,"description":"Maximum number of records in this page.","schema":{"type":"integer","minimum":1,"maximum":5000,"default":500,"description":"Maximum number of records in this page."},"example":10},{"name":"cursor","in":"query","required":false,"description":"Use nextCursor from the previous page with the same filters.","schema":{"type":"string","description":"Use nextCursor from the previous page with the same filters."}}],"responses":{"200":{"description":"Gamma exposure alerts. Example values are illustrative, not live data.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"version":{"type":"number","const":1},"from":{"type":"string","description":"Trading date in YYYY-MM-DD format."},"to":{"type":"string","description":"Trading date in YYYY-MM-DD format."},"timezone":{"type":"string","const":"America/New_York"},"ticker":{"type":["string","null"]},"type":{"anyOf":[{"type":"string","enum":["gex_node_proximity","largest_node_moved_higher","largest_node_moved_lower"]},{"type":"null"}]},"count":{"type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"type":"integer","minimum":0,"maximum":9007199254740991},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]},"alerts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":0,"maximum":9007199254740991},"type":{"type":"string","enum":["gex_node_proximity","largest_node_moved_higher","largest_node_moved_lower"]},"ticker":{"type":"string"},"date":{"type":"string","description":"Trading date in YYYY-MM-DD format."},"alertedAt":{"type":"string","description":"ISO 8601 timestamp."},"classification":{"type":["string","null"]},"severity":{"type":["string","null"]},"title":{"type":["string","null"]},"message":{"type":["string","null"]},"spotPrice":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"previousSpotPrice":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"thresholdPercent":{"type":["number","null"]},"expiration":{"type":["string","null"]},"nodeStrike":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"nodeGex":{"type":["number","null"]},"distancePercent":{"type":["number","null"]},"absoluteDistancePercent":{"type":["number","null"]},"oldNodeStrike":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"newNodeStrike":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"oldNodeExpiration":{"type":["string","null"]},"newNodeExpiration":{"type":["string","null"]},"oldNodeGex":{"type":["number","null"]},"newNodeGex":{"type":["number","null"]},"severityScore":{"type":["number","null"]}},"required":["id","type","ticker","date","alertedAt","classification","severity","title","message","spotPrice","previousSpotPrice","thresholdPercent","expiration","nodeStrike","nodeGex","distancePercent","absoluteDistancePercent","oldNodeStrike","newNodeStrike","oldNodeExpiration","newNodeExpiration","oldNodeGex","newNodeGex","severityScore"]}}},"required":["version","from","to","timezone","ticker","type","count","limit","hasMore","nextCursor","alerts"]},"example":{"version":1,"from":"2026-10-14","to":"2026-10-14","timezone":"America/New_York","ticker":"SPY","type":null,"count":0,"limit":10,"hasMore":false,"nextCursor":null,"alerts":[]}}}},"400":{"description":"Invalid query parameters. No payment is settled for an unsuccessful data response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required or insufficient prepaid credits. Add credits in the API dashboard, use an active API subscription, or approve one offered x402/MPP method and retry with its payment credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"PAYMENT-REQUIRED":{"description":"Base USDC x402 payment requirements when offered; retry using PAYMENT-SIGNATURE.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"MPP payment challenges when offered; retry using Authorization: Payment or Payment-Authorization.","schema":{"type":"string"}}}},"404":{"description":"No matching data is available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; honor Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds to wait before retrying."}}},"503":{"description":"Data or the selected payment method is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/gexDelayedSnapshot":{"get":{"operationId":"bullflow_free_delayed_gex_snapshot","summary":"Free 15-minute-delayed GEX snapshot","description":"No account, API key, or payment required. The most recent eligible open-interest gamma-exposure snapshot, delayed by at least 15 minutes, with spot price, the full strike-by-expiration heat map, strike and expiration totals, and strongest positive and negative net-exposure levels. Values are USD per 1% underlying-price move. These levels are not estimated call walls, put walls, or gamma-flip prices. Captures normally arrive every five minutes, and the latest available snapshot can be older outside the trading session or during a data interruption. Related ticker snapshots have their own timestamps and the same minimum delay. Limit: 60 requests per fixed minute per client IP, shared across all free closing-data and delayed-GEX REST endpoints and their MCP tools. REST HTTP 429 includes Retry-After in seconds. MCP tool errors set isError and structuredContent.status=429 with data.retryAfterSeconds; the HTTP transport can still return 200.","tags":["Free market data"],"security":[],"parameters":[{"name":"ticker","in":"query","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","pattern":"^[A-Za-z]{1,5}(?:\\.[A-Za-z])?$","description":"Ticker from the corresponding free availability catalog, for example SPY."},"example":"SPY"}],"responses":{"200":{"description":"Free 15-minute-delayed GEX snapshot","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"response_type":{"type":"string","const":"gex_delayed_snapshot"},"ticker":{"type":"string"},"snapshot_date":{"type":"string","description":"Snapshot session date in America/New_York, formatted YYYY-MM-DD."},"snapshot_timestamp":{"type":"string","description":"Actual snapshot completion time as an ISO 8601 UTC timestamp, at least 15 minutes before the response."},"timezone":{"type":"string","const":"America/New_York"},"delay_minutes":{"type":"number","const":15},"source_interval_minutes":{"type":"number","const":5},"spot_price":{"type":"number"},"total_net_gex":{"type":"number"},"positive_gex":{"type":"number","description":"Sum of positive net-GEX strike/expiration cells, in USD per 1% move."},"negative_gex":{"type":"number","description":"Signed sum of negative net-GEX strike/expiration cells, in USD per 1% move."},"gross_gex":{"type":"number","description":"Sum of absolute net-GEX strike/expiration cells, in USD per 1% move."},"max_positive":{"anyOf":[{"type":"object","properties":{"strike":{"type":"number"},"net_gex":{"type":"number","description":"USD per 1% underlying-price move."}},"required":["strike","net_gex"],"additionalProperties":false},{"type":"null"}]},"max_negative":{"anyOf":[{"type":"object","properties":{"strike":{"type":"number"},"net_gex":{"type":"number","description":"USD per 1% underlying-price move."}},"required":["strike","net_gex"],"additionalProperties":false},{"type":"null"}]},"strike_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expiration_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pair_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"strikes":{"type":"array","items":{"type":"object","properties":{"strike":{"type":"number"},"net_gex":{"type":"number","description":"USD per 1% underlying-price move."}},"required":["strike","net_gex"],"additionalProperties":false}},"expirations":{"type":"array","items":{"type":"string","description":"Expiration date in YYYY-MM-DD format."}},"expiration_totals":{"type":"array","items":{"type":"object","properties":{"expiration":{"type":"string"},"net_gex":{"type":"number"},"positive_gex":{"type":"number"},"negative_gex":{"type":"number"}},"required":["expiration","net_gex","positive_gex","negative_gex"],"additionalProperties":false}},"heatmap":{"type":"array","items":{"type":"object","properties":{"strike":{"type":"number"},"expiration":{"type":"string"},"net_gex":{"type":"number"}},"required":["strike","expiration","net_gex"],"additionalProperties":false}},"company":{"type":"object","properties":{"name":{"type":"string"},"short":{"type":"string"},"exchange":{"type":["string","null"]},"sector":{"type":["string","null"]}},"required":["name","short","exchange","sector"],"additionalProperties":false},"related_tickers":{"maxItems":6,"type":"array","items":{"type":"object","properties":{"ticker":{"type":"string"},"company_name":{"type":"string"},"snapshot_date":{"type":"string","description":"Snapshot session date in America/New_York, formatted YYYY-MM-DD."},"snapshot_timestamp":{"type":"string","description":"Actual snapshot completion time as an ISO 8601 UTC timestamp, at least 15 minutes before the response."},"total_net_gex":{"type":"number"},"spot_price":{"type":"number"}},"required":["ticker","company_name","snapshot_date","snapshot_timestamp","total_net_gex","spot_price"],"additionalProperties":false}}},"required":["response_type","ticker","snapshot_date","snapshot_timestamp","timezone","delay_minutes","source_interval_minutes","spot_price","total_net_gex","positive_gex","negative_gex","gross_gex","max_positive","max_negative","strike_count","expiration_count","pair_count","strikes","expirations","expiration_totals","heatmap","company","related_tickers"],"additionalProperties":{}}}}},"400":{"description":"Invalid ticker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Public data is not offered for this ticker; use the corresponding availability catalog.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"60 requests per fixed minute per client IP, shared across all free closing-data and delayed-GEX REST endpoints and their MCP tools. REST HTTP 429 includes Retry-After in seconds. MCP tool errors set isError and structuredContent.status=429 with data.retryAfterSeconds; the HTTP transport can still return 200.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds to wait before retrying."}}},"503":{"description":"Public data is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}}}}}},"/v1/gexDelayedSnapshots":{"get":{"operationId":"bullflow_free_delayed_gex_tickers","summary":"Free delayed GEX availability","description":"No account, API key, or payment required. List tickers with an available public GEX snapshot delayed by at least 15 minutes, including each ticker's actual snapshot timestamp and session date. Coverage changes with available data; use each ticker's timestamp rather than assuming the entire list has the same capture time. Limit: 60 requests per fixed minute per client IP, shared across all free closing-data and delayed-GEX REST endpoints and their MCP tools. REST HTTP 429 includes Retry-After in seconds. MCP tool errors set isError and structuredContent.status=429 with data.retryAfterSeconds; the HTTP transport can still return 200.","tags":["Free market data"],"security":[],"parameters":[],"responses":{"200":{"description":"Free delayed GEX availability","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"response_type":{"type":"string","const":"gex_delayed_availability"},"snapshot_date":{"type":"string","description":"Snapshot session date in America/New_York, formatted YYYY-MM-DD."},"timezone":{"type":"string","const":"America/New_York"},"delay_minutes":{"type":"number","const":15},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"snapshots":{"type":"array","items":{"type":"object","properties":{"ticker":{"type":"string"},"snapshot_date":{"type":"string","description":"Snapshot session date in America/New_York, formatted YYYY-MM-DD."},"snapshot_timestamp":{"type":"string","description":"Actual snapshot completion time as an ISO 8601 UTC timestamp, at least 15 minutes before the response."}},"required":["ticker","snapshot_date","snapshot_timestamp"],"additionalProperties":false}}},"required":["response_type","snapshot_date","timezone","delay_minutes","count","snapshots"],"additionalProperties":false}}}},"400":{"description":"Invalid ticker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Public data is not offered for this ticker; use the corresponding availability catalog.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"60 requests per fixed minute per client IP, shared across all free closing-data and delayed-GEX REST endpoints and their MCP tools. REST HTTP 429 includes Retry-After in seconds. MCP tool errors set isError and structuredContent.status=429 with data.retryAfterSeconds; the HTTP transport can still return 200.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds to wait before retrying."}}},"503":{"description":"Public data is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}}}}}},"/v1/gexClosingSnapshotSummary":{"get":{"operationId":"bullflow_free_gex_summary","summary":"Free closing GEX summary","description":"No account, API key, or payment required. Previous-trading-session closing spot, total net GEX and up to 12 strikes with the largest absolute exposure. Use the free GEX ticker catalog for coverage. This is delayed summary data, not live GEX or full history. Limit: 60 requests per fixed minute per client IP, shared across all free closing-data and delayed-GEX REST endpoints and their MCP tools. REST HTTP 429 includes Retry-After in seconds. MCP tool errors set isError and structuredContent.status=429 with data.retryAfterSeconds; the HTTP transport can still return 200.","tags":["Free market data"],"security":[],"parameters":[{"name":"ticker","in":"query","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","pattern":"^[A-Za-z]{1,5}(?:\\.[A-Za-z])?$","description":"Ticker from the corresponding free availability catalog, for example SPY."},"example":"SPY"}],"responses":{"200":{"description":"Free closing GEX summary","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"response_type":{"type":"string","const":"eod_snapshot_summary"},"ticker":{"type":"string"},"snapshot_date":{"type":"string","description":"Closing trading session in YYYY-MM-DD format; read this field rather than assuming today."},"snapshot_timestamp":{"type":"string"},"timezone":{"type":"string","const":"America/New_York"},"spot_price":{"type":"number"},"total_net_gex":{"type":"number"},"top_strikes":{"maxItems":12,"type":"array","items":{"type":"object","properties":{"strike":{"type":"number"},"net_gex":{"type":"number","description":"USD per 1% underlying-price move."}},"required":["strike","net_gex"],"additionalProperties":false}}},"required":["response_type","ticker","snapshot_date","snapshot_timestamp","timezone","spot_price","total_net_gex","top_strikes"],"additionalProperties":{}}}}},"400":{"description":"Invalid ticker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Public data is not offered for this ticker; use the corresponding availability catalog.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"60 requests per fixed minute per client IP, shared across all free closing-data and delayed-GEX REST endpoints and their MCP tools. REST HTTP 429 includes Retry-After in seconds. MCP tool errors set isError and structuredContent.status=429 with data.retryAfterSeconds; the HTTP transport can still return 200.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds to wait before retrying."}}},"503":{"description":"Public data is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}}}}}},"/v1/gexClosingSnapshots":{"get":{"operationId":"bullflow_free_gex_tickers","summary":"Free closing GEX availability","description":"No account, API key, or payment required. List tickers with an available public GEX closing summary and their session date. Coverage changes with available data. Limit: 60 requests per fixed minute per client IP, shared across all free closing-data and delayed-GEX REST endpoints and their MCP tools. REST HTTP 429 includes Retry-After in seconds. MCP tool errors set isError and structuredContent.status=429 with data.retryAfterSeconds; the HTTP transport can still return 200.","tags":["Free market data"],"security":[],"parameters":[],"responses":{"200":{"description":"Free closing GEX availability","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"snapshot_date":{"type":"string","description":"Closing trading session in YYYY-MM-DD format; read this field rather than assuming today."},"timezone":{"type":"string","const":"America/New_York"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"snapshots":{"type":"array","items":{"type":"object","properties":{"ticker":{"type":"string"},"snapshot_date":{"type":"string","description":"Closing trading session in YYYY-MM-DD format; read this field rather than assuming today."}},"required":["ticker","snapshot_date"],"additionalProperties":{}}}},"required":["snapshot_date","timezone","count","snapshots"],"additionalProperties":{}}}}},"400":{"description":"Invalid ticker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Public data is not offered for this ticker; use the corresponding availability catalog.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"60 requests per fixed minute per client IP, shared across all free closing-data and delayed-GEX REST endpoints and their MCP tools. REST HTTP 429 includes Retry-After in seconds. MCP tool errors set isError and structuredContent.status=429 with data.retryAfterSeconds; the HTTP transport can still return 200.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds to wait before retrying."}}},"503":{"description":"Public data is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}}}}}},"/v1/optionsFlowClosingSnapshotSummary":{"get":{"operationId":"bullflow_free_options_flow_summary","summary":"Free closing options-flow summary","description":"No account, API key, or payment required. Previous-trading-session recorded options-flow totals and up to 12 largest-premium trades. Use the free options-flow ticker catalog for coverage. This is delayed summary data, not a full trade feed or live data. Limit: 60 requests per fixed minute per client IP, shared across all free closing-data and delayed-GEX REST endpoints and their MCP tools. REST HTTP 429 includes Retry-After in seconds. MCP tool errors set isError and structuredContent.status=429 with data.retryAfterSeconds; the HTTP transport can still return 200.","tags":["Free market data"],"security":[],"parameters":[{"name":"ticker","in":"query","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","pattern":"^[A-Za-z]{1,5}(?:\\.[A-Za-z])?$","description":"Ticker from the corresponding free availability catalog, for example SPY."},"example":"SPY"}],"responses":{"200":{"description":"Free closing options-flow summary","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"response_type":{"type":"string","const":"options_flow_closing_summary"},"ticker":{"type":"string"},"snapshot_date":{"type":"string","description":"Closing trading session in YYYY-MM-DD format; read this field rather than assuming today."},"timezone":{"type":"string","const":"America/New_York"},"currency":{"type":"string","const":"USD"},"trade_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"total_premium":{"type":"number"},"call_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"put_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"call_premium":{"type":"number"},"put_premium":{"type":"number"},"latest_trade_at":{"type":"string"},"top_trades":{"maxItems":12,"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"timestamp":{"type":"string"},"option_type":{"type":"string","enum":["Call","Put"]},"expiration":{"type":"string"},"strike":{"type":"number"},"premium":{"type":"number"},"size":{"type":["number","null"]},"execution":{"type":"string"},"trade_type":{"type":"string"}},"required":["symbol","timestamp","option_type","expiration","strike","premium","size","execution","trade_type"],"additionalProperties":false}},"company":{"type":"object","properties":{"name":{"type":"string"},"short":{"type":"string"},"exchange":{"type":["string","null"]},"sector":{"type":["string","null"]}},"required":["name","short","exchange","sector"],"additionalProperties":false},"quote":{"anyOf":[{"type":"object","properties":{"snapshot_date":{"type":"string","description":"Closing trading session in YYYY-MM-DD format; read this field rather than assuming today."},"close":{"type":"number"},"previous_close":{"type":["number","null"]}},"required":["snapshot_date","close","previous_close"],"additionalProperties":false},{"type":"null"}]},"price_history":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string"},"close":{"type":"number"}},"required":["timestamp","close"],"additionalProperties":false},"description":"Available one-minute regular-session closing prices for snapshot_date, timestamped at interval end and delayed at least 15 minutes."},"price_history_interval_ms":{"type":"number","const":60000},"price_history_timestamp_is_end":{"type":"boolean","const":true},"gex_summary":{"anyOf":[{"type":"object","properties":{"response_type":{"type":"string","const":"eod_snapshot_summary"},"ticker":{"type":"string"},"snapshot_date":{"type":"string","description":"Closing trading session in YYYY-MM-DD format; read this field rather than assuming today."},"snapshot_timestamp":{"type":"string"},"timezone":{"type":"string","const":"America/New_York"},"spot_price":{"type":"number"},"total_net_gex":{"type":"number"},"top_strikes":{"maxItems":12,"type":"array","items":{"type":"object","properties":{"strike":{"type":"number"},"net_gex":{"type":"number","description":"USD per 1% underlying-price move."}},"required":["strike","net_gex"],"additionalProperties":false}}},"required":["response_type","ticker","snapshot_date","snapshot_timestamp","timezone","spot_price","total_net_gex","top_strikes"],"additionalProperties":{}},{"type":"null"}]},"related_tickers":{"maxItems":6,"type":"array","items":{"type":"object","properties":{"ticker":{"type":"string"},"company_name":{"type":"string"},"snapshot_date":{"type":"string","description":"Closing trading session in YYYY-MM-DD format; read this field rather than assuming today."},"trade_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"total_premium":{"type":"number"},"call_premium":{"type":"number"},"put_premium":{"type":"number"}},"required":["ticker","company_name","snapshot_date","trade_count","total_premium","call_premium","put_premium"],"additionalProperties":false}}},"required":["response_type","ticker","snapshot_date","timezone","currency","trade_count","total_premium","call_count","put_count","call_premium","put_premium","latest_trade_at","top_trades"],"additionalProperties":{}}}}},"400":{"description":"Invalid ticker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Public data is not offered for this ticker; use the corresponding availability catalog.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"60 requests per fixed minute per client IP, shared across all free closing-data and delayed-GEX REST endpoints and their MCP tools. REST HTTP 429 includes Retry-After in seconds. MCP tool errors set isError and structuredContent.status=429 with data.retryAfterSeconds; the HTTP transport can still return 200.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds to wait before retrying."}}},"503":{"description":"Public data is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}}}}}},"/v1/optionsFlowClosingSnapshots":{"get":{"operationId":"bullflow_free_options_flow_tickers","summary":"Free closing options-flow availability","description":"No account, API key, or payment required. List tickers with a public closing options-flow summary and their session date. Coverage can differ from GEX. Limit: 60 requests per fixed minute per client IP, shared across all free closing-data and delayed-GEX REST endpoints and their MCP tools. REST HTTP 429 includes Retry-After in seconds. MCP tool errors set isError and structuredContent.status=429 with data.retryAfterSeconds; the HTTP transport can still return 200.","tags":["Free market data"],"security":[],"parameters":[],"responses":{"200":{"description":"Free closing options-flow availability","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"snapshot_date":{"type":"string","description":"Closing trading session in YYYY-MM-DD format; read this field rather than assuming today."},"timezone":{"type":"string","const":"America/New_York"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"snapshots":{"type":"array","items":{"type":"object","properties":{"ticker":{"type":"string"},"snapshot_date":{"type":"string","description":"Closing trading session in YYYY-MM-DD format; read this field rather than assuming today."}},"required":["ticker","snapshot_date"],"additionalProperties":{}}}},"required":["snapshot_date","timezone","count","snapshots"],"additionalProperties":{}}}}},"400":{"description":"Invalid ticker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Public data is not offered for this ticker; use the corresponding availability catalog.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"60 requests per fixed minute per client IP, shared across all free closing-data and delayed-GEX REST endpoints and their MCP tools. REST HTTP 429 includes Retry-After in seconds. MCP tool errors set isError and structuredContent.status=429 with data.retryAfterSeconds; the HTTP transport can still return 200.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds to wait before retrying."}}},"503":{"description":"Public data is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}}}}}},"/v1/optionsFlowRelatedTickers":{"get":{"operationId":"bullflow_free_options_flow_related_tickers","summary":"Free related options-flow summaries","description":"No account, API key, or payment required. Up to six related tickers with recorded options-flow premium and trade totals from the same closing session. The related ticker list is saved for seven days; premium and trade statistics come from the current closing session. Peers without qualifying data for that session are omitted without replacing the saved relationships. Relationships reflect business or industry similarity. This is delayed summary data, not live data. Limit: 60 requests per fixed minute per client IP, shared across all free closing-data and delayed-GEX REST endpoints and their MCP tools. REST HTTP 429 includes Retry-After in seconds. MCP tool errors set isError and structuredContent.status=429 with data.retryAfterSeconds; the HTTP transport can still return 200.","tags":["Free market data"],"security":[],"parameters":[{"name":"ticker","in":"query","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","pattern":"^[A-Za-z]{1,5}(?:\\.[A-Za-z])?$","description":"Ticker from the corresponding free availability catalog, for example SPY."},"example":"SPY"}],"responses":{"200":{"description":"Free related options-flow summaries","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ticker":{"type":"string"},"snapshot_date":{"type":"string","description":"Closing trading session in YYYY-MM-DD format; read this field rather than assuming today."},"timezone":{"type":"string","const":"America/New_York"},"company":{"type":"object","properties":{"name":{"type":"string"},"short":{"type":"string"},"exchange":{"type":["string","null"]},"sector":{"type":["string","null"]}},"required":["name","short","exchange","sector"],"additionalProperties":false},"related_tickers":{"maxItems":6,"type":"array","items":{"type":"object","properties":{"ticker":{"type":"string"},"company_name":{"type":"string"},"snapshot_date":{"type":"string","description":"Closing trading session in YYYY-MM-DD format; read this field rather than assuming today."},"trade_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"total_premium":{"type":"number"},"call_premium":{"type":"number"},"put_premium":{"type":"number"}},"required":["ticker","company_name","snapshot_date","trade_count","total_premium","call_premium","put_premium"],"additionalProperties":false}}},"required":["ticker","snapshot_date","timezone","company","related_tickers"],"additionalProperties":false}}}},"400":{"description":"Invalid ticker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Public data is not offered for this ticker; use the corresponding availability catalog.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"60 requests per fixed minute per client IP, shared across all free closing-data and delayed-GEX REST endpoints and their MCP tools. REST HTTP 429 includes Retry-After in seconds. MCP tool errors set isError and structuredContent.status=429 with data.retryAfterSeconds; the HTTP transport can still return 200.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds to wait before retrying."}}},"503":{"description":"Public data is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}}}}}}},"components":{"securitySchemes":{"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"},"apiKeyQuery":{"type":"apiKey","in":"query","name":"key"},"bearerAuth":{"type":"http","scheme":"bearer","description":"Bullflow API key or OAuth access token with api:read permission."},"x402Payment":{"type":"apiKey","in":"header","name":"PAYMENT-SIGNATURE","description":"An x402 payment credential, not a Bullflow API key. First request without credentials to receive HTTP 402 and PAYMENT-REQUIRED. After the user approves the live quote, create the payment credential with an x402 client and retry with PAYMENT-SIGNATURE. Send only one payment credential per request."},"mppPayment":{"type":"http","scheme":"Payment","description":"An MPP payment credential. First request without credentials to receive HTTP 402 and WWW-Authenticate. After the user approves an offered method and its live quote, retry with Authorization: Payment <credential>. Send only one payment credential per request."},"mppPaymentHeader":{"type":"apiKey","in":"header","name":"Payment-Authorization","description":"Alternative MPP header, not a Bullflow API key. After the user approves the live HTTP 402 challenge, send the full Payment <credential> value in Payment-Authorization instead of Authorization. Send only one payment credential per request."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}