{"openapi":"3.1.0","info":{"title":"FlowFrame API (beta)","version":"1.0.0-beta","description":"# FlowFrame Public API v1\n\nPublic API for prediction-market intelligence:\n- **Kelly calculator** — stateless fractional-Kelly position sizing\n- **Pulse** — published market-event feed\n- **Polymarket movers** — biggest YES-price movers over 1h/4h/12h/24h\n- **Kalshi movers** — biggest Kalshi YES-price movers since midnight UTC\n- **Kalshi catalogue** — event-grouped markets from FlowFrame's cached top-500 Kalshi event slice\n- **Kalshi trending** — top open Kalshi markets by 24h volume\n- **Live trade feed** — recent large trades from FlowFrame's tracked top-trader wallets\n- **Blog** — FlowFrame Research articles (Deep Research + Market Insights)\n- **Smart Money Skew** — markets where top traders are concentrated on one side\n- **Political Smart Money** — wallets ranked by politics-only USD P&L and election race positioning (distinct from the generic top-30 Smart Money Skew cohort)\n- **Mentions Hub** — keyword search across political-speech transcripts (Trump, Vance, Powell, Warsh, Rubio, Hegseth, Leavitt, Sanders) and NFL broadcast commentary (nfl-announcers)\n- **Football Sharps** — NFL + College Football traders ranked by realized Polymarket P&L, plus a live trade feed with unusual-size flags\n\n## Authentication\nAll endpoints under `/v1/*` (except `/v1/openapi.json`) require an API key:\n```\nAuthorization: Bearer flowframe_live_<32 chars>\n```\nGenerate keys at https://flowframe.xyz/account/api-keys.\n\n## Rate limits\nPer-key, fixed 1-hour window. Free tier = 20 requests/hour, FlowFrame Pro ($19/mo) = 100/hour, API Starter ($29/mo) = 600/hour, Institutional = 60,000/hour. Political Smart Money routes are accessible to all keys, with free-tier results clamped to 5 rows/positions. Tier is resolved from live entitlements. All Mentions Hub endpoints (`/v1/mentions/speakers`, `/v1/mentions/search`, `/v1/mentions/frequency`) and both Football Sharps endpoints (`/v1/football-sharps/leaderboard`, `/v1/football-sharps/feed`) are currently free. Seven paid endpoints — `/v1/markets/{conditionId}/price-history`, `/v1/markets/{conditionId}/snapshot-history`, `/v1/cross-venue/{conditionId}`, `/v1/signals/breakout`, `/v1/signals/spread-widening`, `/v1/sportsbook/events`, `/v1/sportsbook/odds` — require Pro or API Starter on both REST and MCP and return 403 on free keys regardless of transport.\nResponses include IETF draft-7 headers: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`. 429 responses also include `Retry-After`.\nThe window is fixed (not sliding): the counter resets at the boundary indicated by `RateLimit-Reset`.\n\n## Errors\nStandard error codes: `unauthorized`, `forbidden`, `rate_limit_exceeded`, `not_found`, `validation_error`, `internal_error`."},"servers":[{"url":"https://flowframe.xyz","description":"Production"}],"security":[{"bearerAuth":[]}],"paths":{"/v1/calculators/kelly":{"post":{"summary":"Calculate a Kelly position size","description":"Stateless standalone Kelly calculation. `probability`, `edge`, and percentage outputs use percent/percentage points rather than 0-1 decimals. Decimal odds are derived from probability. This endpoint does not read or modify user portfolios.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["probability","edge","bankroll","riskTolerance"],"properties":{"probability":{"type":"number","minimum":0.01,"maximum":99,"description":"Current market-implied probability in percent, not a 0-1 decimal."},"edge":{"type":"number","minimum":0,"maximum":20,"description":"Estimated informational edge in percentage points, added to probability and capped at 99%."},"bankroll":{"type":"number","exclusiveMinimum":0,"maximum":1000000000000,"description":"Available bankroll in any currency. recommendedBet uses the same currency units."},"riskTolerance":{"type":"string","enum":["conservative","moderate","aggressive"],"description":"Quarter Kelly (25%), half Kelly (50%), or full Kelly (100%)."}}},"example":{"probability":75,"edge":2,"bankroll":1000,"riskTolerance":"moderate"}}}},"responses":{"200":{"description":"Kelly calculation envelope.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["probability","odds","edge","trueProbability","bankroll","riskTolerance","kellyMultiplier","fullKellyFraction","kellyFraction","recommendedBet","expectedValue","maxDrawdown"],"properties":{"probability":{"type":"number","description":"Input market probability in percent."},"odds":{"type":"number","description":"Derived decimal odds, rounded to two decimals to match the FlowFrame calculator."},"edge":{"type":"number","description":"Input estimated edge in percentage points."},"trueProbability":{"type":"number","description":"Probability plus edge, capped at 99%, in percent."},"bankroll":{"type":"number","description":"Input bankroll in caller-selected currency units."},"riskTolerance":{"type":"string","enum":["conservative","moderate","aggressive"],"description":"Quarter Kelly (25%), half Kelly (50%), or full Kelly (100%)."},"kellyMultiplier":{"type":"number","enum":[0.25,0.5,1]},"fullKellyFraction":{"type":"number","description":"Unadjusted full-Kelly bankroll allocation in percent."},"kellyFraction":{"type":"number","description":"Risk-adjusted bankroll allocation in percent."},"recommendedBet":{"type":"number","description":"Recommended stake in the same currency units as bankroll."},"expectedValue":{"type":"number","description":"Expected return in percent."},"maxDrawdown":{"type":"number","description":"Existing standalone-calculator drawdown estimate in percent."}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/pulse":{"get":{"summary":"List Pulse items","description":"Returns published Pulse items in reverse chronological order. Cursor pagination via `meta.nextCursor`.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor returned in `meta.nextCursor`."},{"name":"source","in":"query","schema":{"type":"string"},"description":"Filter by source."},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601 timestamp; only items published after."}],"responses":{"200":{"description":"Pulse items envelope.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":["string","null"]},"subject":{"type":"string"},"source":{"type":"string"},"publishedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"content":{"type":"string"},"polymarketUrl":{"type":["string","null"]},"conditionId":{"type":["string","null"],"description":"Polymarket conditionId if derivable from polymarketUrl."},"isPinned":{"type":"boolean"},"permalink":{"type":"string","format":"uri"}}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/pulse/by-market/{conditionId}":{"get":{"summary":"List Pulse items by Polymarket conditionId","description":"Returns published Pulse items linked to the given Polymarket conditionId. Items without a derivable conditionId (e.g., Kalshi-only) are excluded.","parameters":[{"name":"conditionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Pulse items envelope.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":["string","null"]},"subject":{"type":"string"},"source":{"type":"string"},"publishedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"content":{"type":"string"},"polymarketUrl":{"type":["string","null"]},"conditionId":{"type":["string","null"],"description":"Polymarket conditionId if derivable from polymarketUrl."},"isPinned":{"type":"boolean"},"permalink":{"type":"string","format":"uri"}}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/pulse/{identifier}":{"get":{"summary":"Get a single Pulse item","description":"Identifier is either the UUID id or the slug. Returns 404 if not found or unpublished.","parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Single Pulse item envelope.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":["string","null"]},"subject":{"type":"string"},"source":{"type":"string"},"publishedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"content":{"type":"string"},"polymarketUrl":{"type":["string","null"]},"conditionId":{"type":["string","null"],"description":"Polymarket conditionId if derivable from polymarketUrl."},"isPinned":{"type":"boolean"},"permalink":{"type":"string","format":"uri"}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/movers/polymarket":{"get":{"summary":"Polymarket biggest movers","description":"Markets with the largest YES-price changes over the selected window.","parameters":[{"name":"window","in":"query","schema":{"type":"string","enum":["1h","4h","12h","24h"],"default":"24h"}},{"name":"direction","in":"query","schema":{"type":"string","enum":["up","down","both"],"default":"both"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Mover items envelope.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"conditionId":{"type":["string","null"]},"marketTitle":{"type":["string","null"]},"currentPrice":{"type":"number","description":"YES probability as a 0–1 fraction."},"priceFrom":{"type":"number","description":"Previous YES probability as a 0–1 fraction."},"priceTo":{"type":"number","description":"Current YES probability as a 0–1 fraction."},"deltaPct":{"type":"number","description":"Signed change in percentage points (e.g., 6 for +6 pp)."},"deltaAbsPct":{"type":"number","description":"Absolute change in percentage points (e.g., 6 for 6 pp)."},"volume24h":{"type":["number","null"]},"liquidity":{"type":["number","null"]},"polymarketUrl":{"type":["string","null"]}}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/movers/kalshi":{"get":{"summary":"Kalshi biggest movers","description":"Kalshi markets with the largest YES-price changes since midnight UTC (Kalshi's `previous_yes_bid` reference resets daily — the effective window is 0–24h). Sorted by absolute price change. Excludes settled, sub-2¢ moves, and terminal-priced markets (≤1¢ or ≥99¢).","parameters":[{"name":"direction","in":"query","schema":{"type":"string","enum":["up","down","both"],"default":"both"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Kalshi mover items envelope.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"ticker":{"type":"string","description":"Kalshi market ticker (e.g., KXBTCD-25MAY0817-T92500)."},"eventTicker":{"type":"string","description":"Parent event ticker."},"title":{"type":"string"},"eventTitle":{"type":"string"},"category":{"type":"string"},"currentPrice":{"type":"number","description":"Current YES price in cents (0–100)."},"previousPrice":{"type":"number","description":"Reference YES price in cents (0–100), set by Kalshi at midnight UTC."},"priceChange":{"type":"number","description":"Signed cent change vs. previousPrice."},"priceChangePercent":{"type":"number"},"volume24h":{"type":"number"},"openInterest":{"type":"number"},"closeTime":{"type":"string","format":"date-time"},"direction":{"type":"string","enum":["up","down"]},"kalshiUrl":{"type":"string","format":"uri"}}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/markets/kalshi/trending":{"get":{"summary":"Kalshi trending markets","description":"Top open Kalshi markets ranked by 24h volume. Sports categories (NFL/NBA/NHL/MLB/NCAA) are excluded; all others (Politics, Economics, Crypto, etc.) are included.","parameters":[{"name":"category","in":"query","schema":{"type":"string"},"description":"Optional case-insensitive category filter (e.g., 'Politics', 'Economics', 'Crypto')."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Kalshi trending items envelope.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"ticker":{"type":"string"},"title":{"type":"string"},"yesPrice":{"type":"number","description":"Current YES price (0–1)."},"volume24h":{"type":"number"},"openInterest":{"type":"number"},"category":{"type":"string"},"closeTime":{"type":"string","format":"date-time"},"kalshiUrl":{"type":"string","format":"uri"}}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/markets/kalshi":{"get":{"summary":"List the cached Kalshi event catalogue","description":"Event-grouped Kalshi catalogue matching the scope and normalized categories used by FlowFrame's Kalshi UI. FlowFrame loads up to 500 events from the 30-minute cached source, applies category filtering before local offset pagination, and does not apply trending-only sports exclusions. The result is not all exchange markets, and pagination is not a stable exchange snapshot. Prices are cached normalized catalogue values, not live or executable quotes; missing upstream normalized prices are returned as zero.","parameters":[{"name":"category","in":"query","schema":{"type":"string","enum":["all","Politics","Economics","Finance","Tech","Climate","Entertainment","Health","Sports","Other"],"default":"all"},"description":"Case-insensitive exact match against FlowFrame UI categories."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Maximum number of events, not markets."},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":499,"default":0}}],"responses":{"200":{"description":"A page of event-grouped catalogue data. Empty filtered or out-of-range pages are successful.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["eventTicker","title","category","kalshiUrl","markets"],"properties":{"eventTicker":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"kalshiUrl":{"type":"string","format":"uri"},"markets":{"type":"array","items":{"type":"object","required":["ticker","title","status","yesLabel","noLabel","yesPrice","yesBid","yesAsk","noBid","noAsk","volume","volume24h","openInterest","closeTime"],"properties":{"ticker":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"yesLabel":{"type":"string"},"noLabel":{"type":"string"},"yesPrice":{"type":"number","minimum":0,"maximum":1,"description":"Last-trade YES price, converted from normalized cents to 0-1. Missing upstream values are zero."},"yesBid":{"type":"number","minimum":0,"maximum":1},"yesAsk":{"type":"number","minimum":0,"maximum":1},"noBid":{"type":"number","minimum":0,"maximum":1},"noAsk":{"type":"number","minimum":0,"maximum":1},"volume":{"type":"number"},"volume24h":{"type":"number"},"openInterest":{"type":"number"},"closeTime":{"type":"string","description":"Kalshi close time, normally ISO 8601."}}}}}}},"meta":{"type":"object","required":["fetchedAt","brand","count","total","limit","offset","hasMore","nextOffset","coverage","priceUnit","priceBasis"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer","description":"Events in this page."},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}},"total":{"type":"integer","description":"Matching events in the top-500 source slice, after category filtering."},"limit":{"type":"integer"},"offset":{"type":"integer"},"hasMore":{"type":"boolean"},"nextOffset":{"type":["integer","null"]},"coverage":{"type":"string","const":"Flowframe cached Kalshi catalogue, not all exchange markets"},"priceUnit":{"type":"string","const":"decimal_probability_0_to_1"},"priceBasis":{"type":"string","description":"Explains that values are cached catalogue fields, not live or executable quotes."},"sourceCacheAgeMs":{"type":["number","null"],"description":"Age of the server-side event catalogue cache after this request; not a price as-of timestamp."},"sourceCacheIsStale":{"type":["boolean","null"]}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"The Kalshi catalogue source failed or returned no raw events.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["unauthorized","forbidden","rate_limit_exceeded","not_found","validation_error","internal_error","query_timeout","service_unavailable"]},"details":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}}}},"retryAfterSeconds":{"type":"integer"}}},"example":{"error":"internal_error","details":[{"message":"Kalshi catalogue is temporarily unavailable"}]}}}}}}},"/v1/midterms":{"get":{"summary":"2026 Midterms Event Hub","description":"Returns the initial Midterms hub in one request: active 2026 election markets from Polymarket, purpose-built Kalshi election events, election-related Smart Money rows, and preset links into Mentions Hub. Sections load independently; `meta.partial` and `meta.errors` identify unavailable sources. This launch-scope endpoint intentionally excludes Pulse/research and later analytics.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":25},"description":"Maximum Polymarket markets and Kalshi events returned."},{"name":"smartMoneyLimit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"description":"Maximum election-related Smart Money rows. Free-tier keys are clamped to 5."}],"responses":{"200":{"description":"Midterms Event Hub envelope. Check `meta.partial` before assuming every section is current.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"season":{"type":"string","enum":["2026-midterms"]},"title":{"type":"string"},"polymarketMarkets":{"type":"array","items":{"type":"object","properties":{"conditionId":{"type":["string","null"]},"title":{"type":"string"},"yesPrice":{"type":"number"},"noPrice":{"type":"number"},"volume24h":{"type":["number","null"]},"liquidity":{"type":["number","null"]},"closeTime":{"type":["string","null"],"format":"date-time"},"polymarketUrl":{"type":["string","null"],"format":"uri"}}}},"kalshiEvents":{"type":"array","items":{"type":"object","properties":{"eventTicker":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"},"category":{"type":"string"},"chamber":{"type":"string","enum":["senate","house","governor","primary","other"]},"volume24h":{"type":"number"},"openInterest":{"type":"number"},"closeTime":{"type":["string","null"],"format":"date-time"},"kalshiUrl":{"type":"string","format":"uri"},"markets":{"type":"array","items":{"type":"object","properties":{"ticker":{"type":"string"},"title":{"type":"string"},"yesPrice":{"type":"number","description":"Current YES price from 0 to 1."},"yesBid":{"type":"number","description":"Current YES bid from 0 to 1."},"yesAsk":{"type":"number","description":"Current YES ask from 0 to 1."},"volume24h":{"type":"number"},"openInterest":{"type":"number"},"closeTime":{"type":["string","null"],"format":"date-time"}}}}}}},"smartMoney":{"type":"array","items":{"type":"object","properties":{"conditionId":{"type":"string"},"marketTitle":{"type":"string"},"marketPrice":{"type":"number","description":"Market YES probability as a 0–1 fraction."},"impliedFairValue":{"type":"number","description":"Smart-money fair YES probability as a 0–1 fraction."},"edgePct":{"type":"number","description":"Signed fair value minus market price, in percentage points (e.g., -6 for -6 pp)."},"compositeSkewScore":{"type":"number"},"tiers":{"type":"object","properties":{"sharp":{"$ref":"#/components/schemas/SkewTier"},"profitable":{"$ref":"#/components/schemas/SkewTier"},"recreational":{"$ref":"#/components/schemas/SkewTier"}}},"polymarketUrl":{"type":["string","null"]}}}},"mentionTopics":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"query":{"type":"string"},"searchPath":{"type":"string"},"frequencyPath":{"type":"string"}}},"description":"Preset links into the existing Mentions search and frequency endpoints."}}},"meta":{"type":"object","required":["fetchedAt","brand","generatedAt","partial","errors","counts","requestedLimit","requestedSmartMoneyLimit","effectiveSmartMoneyLimit","smartMoneyClamped","effectiveTier"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}},"generatedAt":{"type":"string","format":"date-time"},"partial":{"type":"boolean","description":"True when one or more live source sections failed."},"errors":{"type":"array","items":{"type":"object","required":["section","code"],"properties":{"section":{"type":"string","enum":["polymarket","kalshi","smartMoney"]},"code":{"type":"string","enum":["timeout","unavailable"]}}}},"counts":{"type":"object","required":["polymarketMarkets","kalshiEvents","smartMoney","mentionTopics"],"properties":{"polymarketMarkets":{"type":"integer"},"kalshiEvents":{"type":"integer"},"smartMoney":{"type":"integer"},"mentionTopics":{"type":"integer"}}},"smartMoneyLastUpdated":{"type":["string","null"],"format":"date-time"},"smartMoneyWalletCount":{"type":["integer","null"]},"requestedLimit":{"type":"integer"},"requestedSmartMoneyLimit":{"type":"integer"},"effectiveSmartMoneyLimit":{"type":"integer"},"smartMoneyClamped":{"type":"boolean"},"effectiveTier":{"type":"string","enum":["free","starter","pro","institutional"]}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"All live Midterms data sources are unavailable.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["unauthorized","forbidden","rate_limit_exceeded","not_found","validation_error","internal_error","query_timeout","service_unavailable"]},"details":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}}}},"retryAfterSeconds":{"type":"integer"}}},"example":{"error":"internal_error","details":[{"message":"Midterms Event Hub is temporarily unavailable"}]}}}}}}},"/v1/trades/recent":{"get":{"summary":"Live whale trade feed","description":"Recent trades (sorted newest first) executed by FlowFrame's tracked top-trader wallets on Polymarket. Filter by minimum USDC size, side (BUY/SELL), and a `since` timestamp.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"minSize","in":"query","schema":{"type":"number","minimum":0,"maximum":10000000,"default":1000},"description":"Minimum USDC notional. Default $1,000."},{"name":"side","in":"query","schema":{"type":"string","enum":["BUY","SELL"]}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Only return trades at or after this ISO 8601 timestamp."}],"responses":{"200":{"description":"Trade items envelope.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"wallet":{"type":"string","description":"Polymarket proxy wallet address of the trader."},"conditionId":{"type":"string"},"marketTitle":{"type":"string"},"marketSlug":{"type":"string"},"outcome":{"type":"string","description":"Outcome name (e.g., 'Yes', 'No', or a multi-outcome label)."},"side":{"type":"string","enum":["BUY","SELL"]},"price":{"type":"number","description":"Execution price (0–1)."},"size":{"type":"number","description":"Share count."},"usdcSize":{"type":"number","description":"USDC notional of the trade."},"transactionHash":{"type":"string"},"polymarketProfileUrl":{"type":"string","format":"uri"},"polymarketMarketUrl":{"type":["string","null"],"format":"uri"}}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/blog":{"get":{"summary":"List FlowFrame Research articles","description":"Returns published blog articles in reverse chronological order. List view omits the full markdown `content` to keep payloads small — fetch `/v1/blog/{identifier}` (slug or UUID) for the full body. Cursor pagination via `meta.nextCursor`.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor returned in `meta.nextCursor`."},{"name":"source","in":"query","schema":{"type":"string","enum":["blog","seo"]},"description":"'blog' = Deep Research; 'seo' = Market Insights."},{"name":"category","in":"query","schema":{"type":"string"},"description":"Case-insensitive exact match on category."},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Only articles published at or after this ISO 8601 timestamp."}],"responses":{"200":{"description":"Blog summary items envelope.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":["string","null"]},"title":{"type":"string"},"summary":{"type":"string"},"coverImage":{"type":["string","null"]},"author":{"type":"string"},"category":{"type":["string","null"]},"readTimeMinutes":{"type":"integer"},"publishedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"source":{"type":["string","null"],"enum":["blog","seo",null],"description":"'blog' = Deep Research; 'seo' = Market Insights."},"keywords":{"type":"array","items":{"type":"string"}},"polymarketLinks":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":["string","null"]}}}},"permalink":{"type":["string","null"],"format":"uri"}}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/blog/{identifier}":{"get":{"summary":"Get a single blog article","description":"Identifier is either the article UUID or its slug. Returns the full article including markdown `content`. 404 if not found.","parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Single blog article envelope.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":["string","null"]},"title":{"type":"string"},"summary":{"type":"string"},"coverImage":{"type":["string","null"]},"author":{"type":"string"},"category":{"type":["string","null"]},"readTimeMinutes":{"type":"integer"},"publishedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"source":{"type":["string","null"],"enum":["blog","seo",null],"description":"'blog' = Deep Research; 'seo' = Market Insights."},"keywords":{"type":"array","items":{"type":"string"}},"polymarketLinks":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":["string","null"]}}}},"permalink":{"type":["string","null"],"format":"uri"},"content":{"type":"string","description":"Full markdown article body."},"metaDescription":{"type":["string","null"]}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/political-smart-money/wallets":{"get":{"tags":["Political Smart Money"],"summary":"Rank wallets by politics-only USD P&L","description":"Cached politics-specific realized plus unrealized P&L ranking; independent of the generic predicting.top top-30 smart-money skew cohort. No refresh or force parameter.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Free tier clamped to 5, paid up to 200."}],"responses":{"200":{"description":"Ranked wallets, ordered by politicsTotalPnl descending.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["walletAddress","politicsRealizedPnl","politicsUnrealizedPnl","politicsTotalPnl","politicsVolume","politicsTradeCount","electionPositionsValue","electionOpenPositions","closedPositionsConsidered","winRate","lastTradeAt","source","discoveredAt","lastRefreshedAt"],"properties":{"walletAddress":{"type":"string","description":"Polygon proxy wallet address."},"politicsRealizedPnl":{"type":"number","description":"Politics-only realized USD P&L."},"politicsUnrealizedPnl":{"type":"number","description":"Politics-only unrealized USD P&L."},"politicsTotalPnl":{"type":"number","description":"Politics-only realized plus unrealized USD P&L; ranking sort key."},"politicsVolume":{"type":"number","description":"Politics cost basis/volume in USD."},"politicsTradeCount":{"type":"integer"},"electionPositionsValue":{"type":"number","description":"Current USD value of open election positions."},"electionOpenPositions":{"type":"integer"},"closedPositionsConsidered":{"type":"integer","description":"Decided positions used for win rate."},"winRate":{"type":"number","description":"Fraction 0–1 of decided positions profitable; inspect closedPositionsConsidered before interpreting zero."},"lastTradeAt":{"type":["string","null"],"format":"date-time"},"source":{"type":"string","description":"Discovery source (leaderboard, holders, live_scanner, manual)."},"discoveredAt":{"type":"string","format":"date-time"},"lastRefreshedAt":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}},"requestedLimit":{"type":"integer","description":"Caller requested limit, before tier cap."},"effectiveLimit":{"type":"integer","description":"Applied row limit after tier cap."},"effectiveTier":{"type":"string","enum":["free","starter","pro","institutional"],"description":"Resolved from live entitlements."},"clamped":{"type":"boolean","description":"True if the free-tier cap reduced the requested limit."},"lastRefresh":{"anyOf":[{"type":"null"},{"type":"object","properties":{"ranAt":{"type":"number","description":"Unix milliseconds."},"ms":{"type":"number"},"marketsDiscovered":{"type":"integer"},"candidatesFromHolders":{"type":"integer"},"candidatesFromLeaderboard":{"type":"integer"},"candidatesScored":{"type":"integer"},"walletsPersisted":{"type":"integer"},"errors":{"type":"integer"}}}],"description":"Last scheduler refresh stats, or null if none has run in this process."},"walletCount":{"type":"integer","description":"Wallets contributing to race aggregates (up to 30)."},"cachedAt":{"type":"number","description":"Aggregate cache creation Unix milliseconds."}},"additionalProperties":true}}},"example":{"data":[{"walletAddress":"0x1111111111111111111111111111111111111111","politicsRealizedPnl":1250,"politicsUnrealizedPnl":350,"politicsTotalPnl":1600,"politicsVolume":8000,"politicsTradeCount":12,"electionPositionsValue":2300,"electionOpenPositions":3,"closedPositionsConsidered":8,"winRate":0.625,"lastTradeAt":"2026-05-08T12:00:00.000Z","source":"holders","discoveredAt":"2026-05-01T12:00:00.000Z","lastRefreshedAt":"2026-05-08T12:00:00.000Z"}],"meta":{"fetchedAt":"2026-05-08T12:01:00.000Z","count":1,"requestedLimit":50,"effectiveLimit":5,"effectiveTier":"free","clamped":true,"lastRefresh":null}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"Political Smart Money source temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["unauthorized","forbidden","rate_limit_exceeded","not_found","validation_error","internal_error","query_timeout","service_unavailable"]},"details":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}}}},"retryAfterSeconds":{"type":"integer"}}},"example":{"error":"service_unavailable","details":[{"message":"Political Smart Money is temporarily unavailable"}]}}}}}}},"/v1/political-smart-money/wallets/{address}":{"get":{"tags":["Political Smart Money"],"summary":"Political smart money wallet positions","description":"Open politics positions ordered by current USD value. wallet is null for an unranked address; positions can still exist. totalOpenCount is the full count before limit; markets contains discovered election markets. No refresh or force parameter.","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"description":"Polymarket proxy wallet address."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":30,"default":30},"description":"Free tier clamped to 5 positions; paid up to 30."}],"responses":{"200":{"description":"Ranked wallet (nullable), positions, count and election market catalogue.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["wallet","positions","totalOpenCount","markets"],"properties":{"wallet":{"anyOf":[{"type":"object","required":["walletAddress","politicsRealizedPnl","politicsUnrealizedPnl","politicsTotalPnl","politicsVolume","politicsTradeCount","electionPositionsValue","electionOpenPositions","closedPositionsConsidered","winRate","lastTradeAt","source","discoveredAt","lastRefreshedAt"],"properties":{"walletAddress":{"type":"string","description":"Polygon proxy wallet address."},"politicsRealizedPnl":{"type":"number","description":"Politics-only realized USD P&L."},"politicsUnrealizedPnl":{"type":"number","description":"Politics-only unrealized USD P&L."},"politicsTotalPnl":{"type":"number","description":"Politics-only realized plus unrealized USD P&L; ranking sort key."},"politicsVolume":{"type":"number","description":"Politics cost basis/volume in USD."},"politicsTradeCount":{"type":"integer"},"electionPositionsValue":{"type":"number","description":"Current USD value of open election positions."},"electionOpenPositions":{"type":"integer"},"closedPositionsConsidered":{"type":"integer","description":"Decided positions used for win rate."},"winRate":{"type":"number","description":"Fraction 0–1 of decided positions profitable; inspect closedPositionsConsidered before interpreting zero."},"lastTradeAt":{"type":["string","null"],"format":"date-time"},"source":{"type":"string","description":"Discovery source (leaderboard, holders, live_scanner, manual)."},"discoveredAt":{"type":"string","format":"date-time"},"lastRefreshedAt":{"type":"string","format":"date-time"}}},{"type":"null"}]},"positions":{"type":"array","items":{"type":"object","description":"Polymarket open position. Fields are optional as supplied by the upstream position feed.","properties":{"conditionId":{"type":"string"},"asset":{"type":"string"},"title":{"type":"string"},"slug":{"type":"string"},"eventSlug":{"type":"string"},"outcome":{"type":"string"},"size":{"type":"number","description":"Share count."},"avgPrice":{"type":"number","description":"Average entry price as a 0–1 fraction."},"curPrice":{"type":"number","description":"Current price as a 0–1 fraction."},"currentValue":{"type":"number","description":"Current position value in USD."},"cashPnl":{"type":"number","description":"Open position P&L in USD."},"realizedPnl":{"type":"number","description":"Realized P&L in USD from the upstream position."},"initialValue":{"type":"number","description":"Initial USD cost."},"redeemable":{"type":"boolean"},"endDate":{"type":"string"},"polymarketUrl":{"type":["string","null"],"description":"Affiliate-linked event or market URL when a slug exists."}}}},"totalOpenCount":{"type":"integer"},"markets":{"type":"array","items":{"type":"object","properties":{"conditionId":{"type":"string"},"slug":{"type":"string"},"question":{"type":"string"},"eventSlug":{"type":"string"},"endDate":{"type":"string"},"volume":{"type":"number","description":"USD volume."},"liquidity":{"type":"number","description":"USD liquidity."},"clobTokenIds":{"type":"array","items":{"type":"string"}},"raceType":{"type":"string","enum":["senate","house","governor","president","control","primary","other"]},"state":{"type":["string","null"]},"polymarketUrl":{"type":["string","null"],"description":"Affiliate-linked event or market URL."}}}}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}},"requestedLimit":{"type":"integer","description":"Caller requested limit, before tier cap."},"effectiveLimit":{"type":"integer","description":"Applied row limit after tier cap."},"effectiveTier":{"type":"string","enum":["free","starter","pro","institutional"],"description":"Resolved from live entitlements."},"clamped":{"type":"boolean","description":"True if the free-tier cap reduced the requested limit."},"lastRefresh":{"anyOf":[{"type":"null"},{"type":"object","properties":{"ranAt":{"type":"number","description":"Unix milliseconds."},"ms":{"type":"number"},"marketsDiscovered":{"type":"integer"},"candidatesFromHolders":{"type":"integer"},"candidatesFromLeaderboard":{"type":"integer"},"candidatesScored":{"type":"integer"},"walletsPersisted":{"type":"integer"},"errors":{"type":"integer"}}}],"description":"Last scheduler refresh stats, or null if none has run in this process."},"walletCount":{"type":"integer","description":"Wallets contributing to race aggregates (up to 30)."},"cachedAt":{"type":"number","description":"Aggregate cache creation Unix milliseconds."}},"additionalProperties":true}}},"example":{"data":{"wallet":null,"positions":[{"conditionId":"0xabc","title":"Election outcome?","outcome":"Yes","avgPrice":0.4,"curPrice":0.55,"currentValue":550,"cashPnl":150}],"totalOpenCount":7,"markets":[]},"meta":{"fetchedAt":"2026-05-08T12:01:00.000Z","requestedLimit":30,"effectiveLimit":5,"effectiveTier":"free","clamped":true}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"Political Smart Money source temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["unauthorized","forbidden","rate_limit_exceeded","not_found","validation_error","internal_error","query_timeout","service_unavailable"]},"details":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}}}},"retryAfterSeconds":{"type":"integer"}}}}}}}}},"/v1/political-smart-money/aggregates":{"get":{"tags":["Political Smart Money"],"summary":"Election race positioning of top politics-P&L wallets","description":"YES/NO USD position values from up to 30 politics-ranked wallets, sorted by absolute net YES USD conviction. Not a probability estimate and not the generic smart-money skew cohort. Cached; force is not supported.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Free tier clamped to 5, paid up to 200."}],"responses":{"200":{"description":"Race aggregates and cache metadata.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["conditionId","question","slug","raceType","state","yesSharpCount","noSharpCount","yesSharpDollars","noSharpDollars","netSharpDollars","topSharps"],"properties":{"conditionId":{"type":"string"},"question":{"type":"string"},"slug":{"type":"string"},"raceType":{"type":"string","enum":["senate","house","governor","president","control","primary","other"]},"state":{"type":["string","null"]},"endDate":{"type":"string"},"yesSharpCount":{"type":"integer"},"noSharpCount":{"type":"integer"},"yesSharpDollars":{"type":"number","description":"Current USD YES position values."},"noSharpDollars":{"type":"number","description":"Current USD NO position values."},"netSharpDollars":{"type":"number","description":"YES minus NO USD position value. Not a probability."},"topSharps":{"type":"array","maxItems":8,"items":{"type":"object","properties":{"wallet":{"type":"string"},"outcome":{"type":"string","enum":["YES","NO"]},"currentValue":{"type":"number","description":"USD value."}}}},"polymarketUrl":{"type":["string","null"],"description":"Affiliate-linked Polymarket market URL."}}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}},"requestedLimit":{"type":"integer","description":"Caller requested limit, before tier cap."},"effectiveLimit":{"type":"integer","description":"Applied row limit after tier cap."},"effectiveTier":{"type":"string","enum":["free","starter","pro","institutional"],"description":"Resolved from live entitlements."},"clamped":{"type":"boolean","description":"True if the free-tier cap reduced the requested limit."},"lastRefresh":{"anyOf":[{"type":"null"},{"type":"object","properties":{"ranAt":{"type":"number","description":"Unix milliseconds."},"ms":{"type":"number"},"marketsDiscovered":{"type":"integer"},"candidatesFromHolders":{"type":"integer"},"candidatesFromLeaderboard":{"type":"integer"},"candidatesScored":{"type":"integer"},"walletsPersisted":{"type":"integer"},"errors":{"type":"integer"}}}],"description":"Last scheduler refresh stats, or null if none has run in this process."},"walletCount":{"type":"integer","description":"Wallets contributing to race aggregates (up to 30)."},"cachedAt":{"type":"number","description":"Aggregate cache creation Unix milliseconds."}},"additionalProperties":true}}},"example":{"data":[{"conditionId":"0xabc","question":"Election outcome?","slug":"election-outcome","raceType":"senate","state":"PA","yesSharpCount":2,"noSharpCount":1,"yesSharpDollars":1000,"noSharpDollars":400,"netSharpDollars":600,"topSharps":[{"wallet":"0x1111111111111111111111111111111111111111","outcome":"YES","currentValue":600}]}],"meta":{"fetchedAt":"2026-05-08T12:01:00.000Z","count":1,"walletCount":30,"cachedAt":1778241600000,"requestedLimit":50,"effectiveLimit":5,"effectiveTier":"free","clamped":true}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"Political Smart Money source temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["unauthorized","forbidden","rate_limit_exceeded","not_found","validation_error","internal_error","query_timeout","service_unavailable"]},"details":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}}}},"retryAfterSeconds":{"type":"integer"}}}}}}}}},"/v1/smart-money/skew":{"get":{"summary":"Smart Money Skew","description":"Markets where top profitable traders are concentrated on one side, ranked by absolute composite skew score.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"minScore","in":"query","schema":{"type":"number"},"description":"Filter to markets with `|compositeSkewScore| >= minScore`."}],"responses":{"200":{"description":"Skew items envelope.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"conditionId":{"type":"string"},"marketTitle":{"type":"string"},"marketPrice":{"type":"number","description":"Market YES probability as a 0–1 fraction."},"impliedFairValue":{"type":"number","description":"Smart-money fair YES probability as a 0–1 fraction."},"edgePct":{"type":"number","description":"Signed fair value minus market price, in percentage points (e.g., -6 for -6 pp)."},"compositeSkewScore":{"type":"number"},"tiers":{"type":"object","properties":{"sharp":{"$ref":"#/components/schemas/SkewTier"},"profitable":{"$ref":"#/components/schemas/SkewTier"},"recreational":{"$ref":"#/components/schemas/SkewTier"}}},"polymarketUrl":{"type":["string","null"]}}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/markets/{conditionId}/price-history":{"get":{"summary":"Historical price + volume series for a market (paid)","description":"Returns 30-min snapshots of YES/NO price and trailing-24h volume for the given Polymarket conditionId, downsampled to the requested interval. Backed by the persistent `correlation_market_snapshots` table; coverage depends on when FlowFrame began tracking the market. **Requires a paid tier (Starter, Pro, or Institutional).**","parameters":[{"name":"conditionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"interval","in":"query","schema":{"type":"string","enum":["30m","1h","4h","1d"],"default":"1h"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Only snapshots at or after this ISO 8601 timestamp."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":200},"description":"Maximum number of bucketed points returned (most recent first-trimmed window)."}],"responses":{"200":{"description":"Price-history envelope.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"yesPrice":{"type":"number","description":"YES outcome price (0–1)."},"noPrice":{"type":["number","null"]},"volume24h":{"type":["number","null"],"description":"Trailing 24h USDC volume at snapshot time."}}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/markets/{conditionId}/snapshot-history":{"get":{"summary":"Full microstructure snapshot history (paid)","description":"Returns a time-aligned history of every Polymarket microstructure field — YES/NO price, best bid/ask, spread, all volume views (24h, per-hour rate, cumulative), and liquidity — for a single conditionId. Backed by `correlation_market_snapshots` (~30-min cadence), downsampled to the requested interval. Distinct from `/v1/markets/{conditionId}/price-history`, which only returns YES/NO + 24h volume. **Requires a paid FlowFrame tier (Pro or API Starter), via either REST or the FlowFrame MCP server.**","parameters":[{"name":"conditionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"interval","in":"query","schema":{"type":"string","enum":["30m","1h","4h","1d"],"default":"1h"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Only snapshots at or after this ISO 8601 timestamp."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":200},"description":"Maximum number of bucketed points returned (most recent first-trimmed window)."}],"responses":{"200":{"description":"Snapshot-history envelope.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"yesPrice":{"type":["number","null"]},"noPrice":{"type":["number","null"]},"bestBid":{"type":["number","null"]},"bestAsk":{"type":["number","null"]},"spreadPercent":{"type":["number","null"],"description":"(ask - bid) / mid × 100."},"volume24h":{"type":["number","null"],"description":"Polymarket Gamma's rolling trailing-24h USDC volume at snapshot time."},"volumePerHourRate":{"type":["number","null"],"description":"Cadence-agnostic USDC/hour, derived from interval volume delta. Comparable to volume_24h/24."},"cumulativeVolume":{"type":["number","null"],"description":"All-time cumulative USDC volume since market inception."},"liquidity":{"type":["number","null"],"description":"Polymarket-reported aggregate liquidity at snapshot time."}}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/markets/search":{"get":{"summary":"Search Polymarket markets by name → conditionId (free)","description":"Resolve a market by name/topic/keywords to its `conditionId` — the identifier every other market endpoint (`/v1/cross-venue`, `/v1/snapshot-history`, etc.) requires. Returns active (still-tradeable) Polymarket markets only; resolved/closed markets are excluded. Free on every tier.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":120},"description":"Market name, topic, or keywords, e.g. 'fed rate cut july'."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}}],"responses":{"200":{"description":"Matched markets envelope.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"conditionId":{"type":"string","description":"Polymarket conditionId — pass to other market endpoints."},"title":{"type":["string","null"]},"slug":{"type":["string","null"]},"yesPrice":{"type":["number","null"],"description":"Current YES outcome price (0–1)."},"volumeTotal":{"type":["number","null"],"description":"All-time USDC volume."},"endDate":{"type":["string","null"],"format":"date-time"},"polymarketUrl":{"type":["string","null"]}}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/cross-venue/symbols":{"get":{"summary":"List tracked cross-venue Hyperliquid symbols (free)","description":"Lists the Hyperliquid symbols FlowFrame tracks for use in the `symbols` argument of `/v1/cross-venue`: core perps (no prefix: `BTC`, `ETH`, `SOL`, `HYPE`), xyz builder-dex symbols (equities/FX/commodities/indices, prefixed `xyz:`), and common-name aliases (e.g. `WTI`→`xyz:CL`, `BRENT`→`xyz:BRENTOIL`). Free on every tier.","responses":{"200":{"description":"Tracked symbols envelope.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"core":{"type":"array","items":{"type":"string"},"description":"Core perps with no prefix (BTC, ETH, SOL, HYPE)."},"xyz":{"type":"array","items":{"type":"string"},"description":"xyz builder-dex symbols (equities/FX/commodities/indices), prefixed 'xyz:'."},"aliases":{"type":"array","description":"Common-name aliases auto-mapped to canonical symbols.","items":{"type":"object","properties":{"alias":{"type":"string"},"canonical":{"type":"string"}}}}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/cross-venue/{conditionId}":{"get":{"summary":"Cross-venue Polymarket × Hyperliquid time series (paid)","description":"Bucket-aligned series joining a Polymarket market's microstructure with the Hyperliquid perp(s) for the underlying asset(s). Both venues are snapshotted on the same 30-minute schedule by FlowFrame's correlation collector, and rows are merged on bucket timestamp (rounded to the requested `interval`). Each row is anchored on a Polymarket bucket; when no Hyperliquid snapshot exists in that bucket for a requested symbol, that symbol is simply absent from the row's `hyperliquid` map (the row's `hyperliquid` object may be `{}` if the HL collector tick failed). If `symbols` is omitted, FlowFrame auto-detects from the market title using the curated crypto set (`BTC`, `ETH`, `SOL`, `HYPE`); for any other underlying (equities, FX, commodities), pass an explicit `?symbols=xyz:AAPL`. **Requires a paid FlowFrame tier (Pro or API Starter), via either REST or the FlowFrame MCP server.**","parameters":[{"name":"conditionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"symbols","in":"query","schema":{"type":"string"},"description":"Comma-separated Hyperliquid symbols (max 8). Curated crypto: `BTC`, `ETH`, `SOL`, `HYPE`. xyz builder dex: `xyz:AAPL`, `xyz:GOLD`, etc. If omitted, FlowFrame auto-detects from the market title."},{"name":"interval","in":"query","schema":{"type":"string","enum":["30m","1h","4h","1d"],"default":"1h"}},{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":365,"default":7},"description":"Trailing window in days (1-365). For windows over ~30 days use a wider `interval` (4h/1d); requests estimated at >5000 buckets return 400."},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601 timestamp; only snapshots at or after this time. Overrides `days` and is not capped at 30 days — reaches the full snapshot archive. For long windows use a wider `interval` (4h/1d); requests estimated at >5000 buckets return 400."}],"responses":{"200":{"description":"Cross-venue envelope.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"polymarket":{"type":"object","properties":{"yesPrice":{"type":["number","null"]},"spreadPercent":{"type":["number","null"]},"volume24h":{"type":["number","null"]},"liquidity":{"type":["number","null"]}}},"hyperliquid":{"type":"object","additionalProperties":{"type":"object","properties":{"oraclePrice":{"type":["number","null"],"description":"External reference price (Pyth/Chainlink). Use this for correlation work."},"midPrice":{"type":["number","null"],"description":"Best bid/ask average on Hyperliquid."},"fundingRate":{"type":["number","null"],"description":"Per-funding-period rate. Signal of perp drift from underlying."},"dayNotionalVolume":{"type":["number","null"],"description":"Trailing 24h notional USD volume."},"openInterestUsd":{"type":["number","null"],"description":"Open interest converted to USD (openInterest × oraclePrice)."}}},"description":"Map keyed by Hyperliquid symbol (e.g. `BTC`, `ETH`, `xyz:AAPL`). Empty object if no HL data exists at this snapshot_time."}}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/signals/breakout":{"get":{"summary":"Volume-velocity breakout signal (paid)","description":"Polymarket markets ranked by **volume velocity** (24h volume as a fraction of all-time volume). Tiers: `breaking` (>6%), `trending` (3-6%), `heating-up` (1-3%). Excludes already-resolved (>95% / <5%), Bitcoin/Ethereum, and 2028-presidential markets. **Requires a paid tier.**","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"minVelocityPercent","in":"query","schema":{"type":"number","minimum":0,"maximum":100,"default":1},"description":"Minimum velocity (24h vol / total vol × 100). Default 1."},{"name":"minVolume24h","in":"query","schema":{"type":"number","minimum":0,"default":10000},"description":"Minimum 24h USDC volume. Default $10,000."}],"responses":{"200":{"description":"Breakout items envelope.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"conditionId":{"type":["string","null"]},"marketTitle":{"type":["string","null"]},"velocityPercent":{"type":"number","description":"volume_24h / volume_total × 100."},"tier":{"type":"string","enum":["breaking","trending","heating-up"]},"volume24h":{"type":"number"},"volumeTotal":{"type":"number"},"currentYesPrice":{"type":["number","null"]},"priceChange24hYes":{"type":["number","null"]},"liquidity":{"type":["number","null"]},"polymarketUrl":{"type":["string","null"]}}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/signals/spread-widening":{"get":{"summary":"Spread-widening fragility signal (paid)","description":"Markets whose current bid-ask spread is `minRatio`× larger than their 7-day baseline (excluding the most recent 6 hours). A precursor to volatility — widening spreads often lead price moves. **Requires a paid tier.**","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"minRatio","in":"query","schema":{"type":"number","minimum":1.05,"default":1.5},"description":"Spread-widening threshold. 1.5 = current spread ≥ 150% of baseline."},{"name":"min24hVolume","in":"query","schema":{"type":"number","minimum":0,"default":5000}},{"name":"minLiquidity","in":"query","schema":{"type":"number","minimum":0,"default":2000}}],"responses":{"200":{"description":"Spread-widening items envelope.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"conditionId":{"type":"string"},"marketSlug":{"type":["string","null"]},"marketTitle":{"type":"string"},"category":{"type":"string"},"yesPrice":{"type":"number"},"snapshotTime":{"type":"string","format":"date-time"},"currentSpreadPercent":{"type":"number"},"baselineSpreadPercent":{"type":"number","description":"7-day rolling mean spread (excluding the most recent 6 hours)."},"wideningRatio":{"type":"number","description":"currentSpreadPercent / baselineSpreadPercent."},"liquidity":{"type":"number"},"volume24h":{"type":"number"},"polymarketUrl":{"type":["string","null"]}}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/sportsbook/events":{"get":{"summary":"Upcoming sportsbook games (paid)","description":"Lists a sport's upcoming and in-play games with their `eventId` and team names. Use the `eventId` with `/v1/sportsbook/odds` to pull player props for a single game. **Requires a paid tier.**","parameters":[{"name":"sport","in":"query","required":true,"schema":{"type":"string","enum":["basketball_nba","americanfootball_nfl","americanfootball_ncaaf","baseball_mlb","icehockey_nhl"]},"description":"League key."}],"responses":{"200":{"description":"Sportsbook event items envelope.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"eventId":{"type":"string","description":"Pass to /v1/sportsbook/odds for player props."},"sport":{"type":"string"},"commenceTime":{"type":"string","format":"date-time"},"homeTeam":{"type":"string"},"awayTeam":{"type":"string"}}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/sportsbook/odds":{"get":{"summary":"Live sportsbook odds + de-vig (paid)","description":"Live odds with FlowFrame's de-vig engine applied. Omit `eventId` for game markets (`h2h`, `spreads`, `totals`) across all of a sport's upcoming games. Pass `eventId` (from `/v1/sportsbook/events`) for a single game — that path also returns player props (e.g. `player_points`). Every two-way line a book posts is returned with its no-vig `fairProb`; Pinnacle is the sharp reference. **Requires a paid tier.**","parameters":[{"name":"sport","in":"query","required":true,"schema":{"type":"string","enum":["basketball_nba","americanfootball_nfl","americanfootball_ncaaf","baseball_mlb","icehockey_nhl"]},"description":"League key."},{"name":"eventId","in":"query","schema":{"type":"string"},"description":"Omit for bulk game markets; required to fetch player props for a single game."},{"name":"markets","in":"query","schema":{"type":"string"},"description":"Comma list. Game: h2h, spreads, totals (default). Player props (need eventId): player_points, player_rebounds, etc. For the per-event path, markets × regions is capped at 20 per request to bound upstream cost."},{"name":"regions","in":"query","schema":{"type":"string"},"description":"Comma list, only used with eventId. Default us."},{"name":"bookmakers","in":"query","schema":{"type":"string"},"description":"Comma list of book keys to restrict results, e.g. pinnacle,draftkings,fanduel."}],"responses":{"200":{"description":"Sportsbook game items envelope (per-event requests return a one-element array).","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"eventId":{"type":"string"},"sport":{"type":"string"},"commenceTime":{"type":"string","format":"date-time"},"homeTeam":{"type":"string"},"awayTeam":{"type":"string"},"books":{"type":"array","items":{"type":"object","properties":{"bookmaker":{"type":"string"},"bookmakerTitle":{"type":"string"},"market":{"type":"string","description":"h2h | spreads | totals | player_points | …"},"lastUpdate":{"type":"string","format":"date-time"},"outcomes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Team, or Over/Under, or Yes/No."},"description":{"type":"string","description":"Player name (player props only)."},"point":{"type":"number","description":"Spread / total / prop line."},"decimal":{"type":"number","description":"Raw decimal odds posted by the book."},"american":{"type":"string","description":"Same odds in American display form."},"impliedProb":{"type":["number","null"],"description":"1/decimal — the book's price WITH vig."},"fairProb":{"type":["number","null"],"description":"Two-way de-vigged fair probability for this book+market+line. Null when no opposing side was found."}}}}}}}}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/mentions/speakers":{"get":{"summary":"List speakers covered by Mentions Hub","description":"Curated whitelist of public-domain political speakers plus NFL broadcast commentary, with transcript counts and date ranges. TV-host transcripts (cable news, podcasts) are not included in the public API.","responses":{"200":{"description":"Speakers envelope.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"title":{"type":["string","null"]},"party":{"type":["string","null"]},"transcriptCount":{"type":"integer"},"earliestDate":{"type":["string","null"],"description":"Earliest transcript date (YYYY-MM-DD)."},"latestDate":{"type":["string","null"],"description":"Most recent transcript date (YYYY-MM-DD)."},"mentionsUrl":{"type":"string","format":"uri"}}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/mentions/search":{"get":{"summary":"Keyword search across speech transcripts","description":"Returns transcripts that mention the keyword `q`, each with up to several ±250-character snippets centered on the match. Slash-separated terms (e.g., `tariff / tariffs`) are treated as alternation. Documents are deduplicated by speaker/date/normalized first 400 characters and ordered newest-first. `mentionCount` and `meta.totalMentions` are exact occurrences in paragraph-deduplicated transcript text, not excerpt counts; snippets from separate transcripts are not globally deduplicated. Use `offset` for pagination — counts in `meta.totalDocuments`/`totalMentions` reflect the full unpaginated result.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":80},"description":"Keyword (2-80 chars). Slash means OR (e.g., `recession / depression`)."},{"name":"speaker","in":"query","schema":{"type":"string","enum":["donald-trump","jd-vance","karoline-leavitt","pete-hegseth","marco-rubio","jerome-powell","kevin-warsh","bernie-sanders","nfl-announcers"]},"description":"Optional speaker slug. Omit to search all whitelisted speakers."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":1000,"default":0}}],"responses":{"200":{"description":"Mentions search envelope.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"transcriptId":{"type":"string"},"speakerSlug":{"type":"string"},"speakerName":{"type":"string"},"date":{"type":"string","description":"YYYY-MM-DD."},"title":{"type":"string"},"source":{"type":"string"},"eventFormat":{"type":["string","null"],"description":"Inferred event format (rally, press_conference, formal_address, etc.)."},"url":{"type":["string","null"]},"mentionCount":{"type":"integer","description":"Exact number of q occurrences in this transcript after substantive repeated paragraphs are deduplicated. This can exceed the number of snippets because nearby matches share one excerpt window."},"snippets":{"type":"array","items":{"type":"string"},"description":"±250 character context windows around each match."}}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"},"504":{"$ref":"#/components/responses/MentionsQueryTimeout"}}}},"/v1/mentions/frequency":{"get":{"summary":"Mention frequency time series","description":"Returns the exact paragraph-deduplicated count of times `q` appears across speech transcripts, bucketed by `granularity`. Use this to track how often a topic is discussed over time and correlate it with prediction-market price moves.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":80}},{"name":"speaker","in":"query","schema":{"type":"string","enum":["donald-trump","jd-vance","karoline-leavitt","pete-hegseth","marco-rubio","jerome-powell","kevin-warsh","bernie-sanders","nfl-announcers"]}},{"name":"granularity","in":"query","schema":{"type":"string","enum":["day","week","month","year"],"default":"month"}}],"responses":{"200":{"description":"Mention frequency envelope.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"period":{"type":"string","description":"Bucket label. Format depends on granularity: day=YYYY-MM-DD, week=YYYY-MM-DD (Sunday), month=YYYY-MM, year=YYYY."},"mentionCount":{"type":"integer","description":"Total occurrences of `q` across all transcripts in this period."},"transcriptCount":{"type":"integer","description":"Number of distinct transcripts containing `q` in this period."}}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"},"504":{"$ref":"#/components/responses/MentionsQueryTimeout"}}}},"/v1/smart-money/skew/{conditionId}":{"get":{"summary":"Smart Money Skew for a single market","parameters":[{"name":"conditionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Single skew item envelope.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"conditionId":{"type":"string"},"marketTitle":{"type":"string"},"marketPrice":{"type":"number","description":"Market YES probability as a 0–1 fraction."},"impliedFairValue":{"type":"number","description":"Smart-money fair YES probability as a 0–1 fraction."},"edgePct":{"type":"number","description":"Signed fair value minus market price, in percentage points (e.g., -6 for -6 pp)."},"compositeSkewScore":{"type":"number"},"tiers":{"type":"object","properties":{"sharp":{"$ref":"#/components/schemas/SkewTier"},"profitable":{"$ref":"#/components/schemas/SkewTier"},"recreational":{"$ref":"#/components/schemas/SkewTier"}}},"polymarketUrl":{"type":["string","null"]}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/football-sharps/leaderboard":{"get":{"summary":"Football Sharps leaderboard","description":"Top NFL + College Football traders on Polymarket, ranked by realized trading results — fully exited and resolved positions only, scored ROI-first: winsorized ROI carries the ranking, with profit scale, win consistency (Wilson lower bound), and recent activity as secondary factors. Wallets flagged as likely market-makers are excluded unless includeMm=true. Rankings refresh on a daily scan; meta.backfillDone=false means the first historical scan is still running and rankings are partial.","parameters":[{"name":"window","in":"query","schema":{"type":"string","enum":["30d","90d","season","all"],"default":"season"},"description":"Ranking window. season = rolling football season (from Aug 1)."},{"name":"league","in":"query","schema":{"type":"string","enum":["all","nfl","cfb"],"default":"all"}},{"name":"includeFutures","in":"query","schema":{"type":"boolean","default":false},"description":"Include futures markets (Super Bowl winner, MVP, win totals) in the record, not just games."},{"name":"includeMm","in":"query","schema":{"type":"boolean","default":false},"description":"Include wallets flagged as likely market-makers."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Ranked wallets envelope.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"integer"},"wallet":{"type":"string","description":"Polygon wallet address (0x…). Profile: polymarket.com/profile/{wallet}?r=flowframe"},"score":{"type":"number","description":"0-100 composite, ROI-led: winsorized ROI (full credit at +30%), profit scale, win consistency (Wilson LB), recency."},"realizedPnl":{"type":"number","description":"Realized P&L in USD over the window (exited + resolved positions only)."},"roi":{"type":"number","description":"Realized P&L ÷ cost basis (e.g. 0.18 = +18%)."},"winRate":{"type":"number","description":"Share of realized positions closed profitable (0-1)."},"realizedCount":{"type":"integer","description":"Realized positions in the window."},"nflCount":{"type":"integer"},"cfbCount":{"type":"integer"},"medianStake":{"type":"number","description":"Median USD cost basis per position — the wallet's 'normal' bet size."},"likelyMm":{"type":"boolean","description":"Flagged as likely market-maker/arb: both outcomes held in >30% of markets, OR the wallet's closed-position history is too large to fetch completely (count-based stats like win rate would be unreliable). Hidden unless includeMm=true."},"lastRealizedAt":{"type":["string","null"],"format":"date-time"}}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/football-sharps/feed":{"get":{"summary":"Live trades from top-ranked football wallets","description":"Recent Polymarket trades (last 72h) from the top 40 leaderboard wallets, newest first. Trades under $100 notional are hidden by default — `minUsd` adjusts the floor, `minUsd=0` disables it (`meta.minUsd` echoes what was applied). Each trade carries the wallet's rank/score and an `unusual` flag when the bet is ≥3× that wallet's median stake — i.e. they're betting bigger than their normal. Server-side cache refreshes about every 10 minutes (meta.refreshedAt).","parameters":[{"name":"minUsd","in":"query","schema":{"type":"number","minimum":0,"maximum":100000,"default":100},"description":"Hide trades below this USD notional. 0 disables the floor."}],"responses":{"200":{"description":"Trade feed envelope.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"wallet":{"type":"string"},"walletRank":{"type":"integer","description":"Wallet's current leaderboard rank."},"walletScore":{"type":"number"},"side":{"type":"string","enum":["BUY","SELL"]},"outcome":{"type":"string"},"title":{"type":"string","description":"Market question."},"slug":{"type":"string","description":"Market slug — link via polymarket.com/market/{slug}?r=flowframe."},"eventSlug":{"type":"string"},"league":{"type":"string","enum":["nfl","cfb"]},"price":{"type":"number","description":"Trade price (0-1 implied probability)."},"usdSize":{"type":"number"},"timestamp":{"type":"integer","description":"Trade time, unix milliseconds."},"unusual":{"type":"boolean","description":"True when usdSize ≥ 3× the wallet's median stake (min $200) — bigger than their normal."},"usualMultiple":{"type":["number","null"],"description":"usdSize ÷ wallet median stake."}}}},"meta":{"type":"object","required":["fetchedAt","brand"],"properties":{"fetchedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]},"count":{"type":"integer"},"brand":{"type":"object","description":"FlowFrame branding + attribution metadata. Free-tier keys MUST display the attribution label in any UI built on top of this API; paid tiers may suppress it.","required":["source","docs","attribution"],"properties":{"source":{"type":"string","example":"flowframe.xyz"},"docs":{"type":"string","format":"uri"},"attribution":{"type":"object","required":["required","label","url","tier"],"properties":{"required":{"type":"boolean","description":"True for free-tier keys, false for paid tiers."},"label":{"type":"string","example":"Powered by FlowFrame"},"url":{"type":"string","format":"uri"},"terms":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","starter","pro","institutional"]}}}}}},"additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key in the form `flowframe_live_*` or `flowframe_test_*`."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["unauthorized","forbidden","rate_limit_exceeded","not_found","validation_error","internal_error","query_timeout","service_unavailable"]},"details":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}}}},"retryAfterSeconds":{"type":"integer"}}},"SkewTier":{"type":"object","properties":{"yesDollars":{"type":"number"},"noDollars":{"type":"number"},"yesCount":{"type":"integer"},"noCount":{"type":"integer"},"skew":{"type":"number"}}}},"headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests permitted per hour for this key."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining requests in the current hour."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the current window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the client may retry (sent on 429)."}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["unauthorized","forbidden","rate_limit_exceeded","not_found","validation_error","internal_error","query_timeout","service_unavailable"]},"details":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}}}},"retryAfterSeconds":{"type":"integer"}}},"example":{"error":"unauthorized"}}}},"Forbidden":{"description":"API key valid but lacks permission.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["unauthorized","forbidden","rate_limit_exceeded","not_found","validation_error","internal_error","query_timeout","service_unavailable"]},"details":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}}}},"retryAfterSeconds":{"type":"integer"}}},"example":{"error":"forbidden"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["unauthorized","forbidden","rate_limit_exceeded","not_found","validation_error","internal_error","query_timeout","service_unavailable"]},"details":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}}}},"retryAfterSeconds":{"type":"integer"}}},"example":{"error":"not_found"}}}},"ValidationError":{"description":"Request parameters failed validation.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["unauthorized","forbidden","rate_limit_exceeded","not_found","validation_error","internal_error","query_timeout","service_unavailable"]},"details":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}}}},"retryAfterSeconds":{"type":"integer"}}},"example":{"error":"validation_error","details":[{"message":"limit must be integer between 1 and 100"}]}}}},"RateLimitExceeded":{"description":"Per-key rate limit exceeded for the current 1-hour window.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["unauthorized","forbidden","rate_limit_exceeded","not_found","validation_error","internal_error","query_timeout","service_unavailable"]},"details":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}}}},"retryAfterSeconds":{"type":"integer"}}},"example":{"error":"rate_limit_exceeded","retryAfterSeconds":1234}}}},"InternalError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["unauthorized","forbidden","rate_limit_exceeded","not_found","validation_error","internal_error","query_timeout","service_unavailable"]},"details":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}}}},"retryAfterSeconds":{"type":"integer"}}},"example":{"error":"internal_error"}}}},"MentionsQueryTimeout":{"description":"The mentions query exceeded its 25-second database statement timeout.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["unauthorized","forbidden","rate_limit_exceeded","not_found","validation_error","internal_error","query_timeout","service_unavailable"]},"details":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}}}},"retryAfterSeconds":{"type":"integer"}}},"example":{"error":"query_timeout","code":"mentions_query_timeout"}}}}}}}