Iframe Parameters

All widget configuration is passed via query parameters on the iframe src URL. Parameters fall into four categories: theme, display, filters, and entity scoping.

Basic Embed

<iframe
  src="https://widget.example.com/?preset=brand_dark_v2"
  width="100%"
  height="480"
  frameborder="0"
  style="border: none;"
></iframe>

Theme Parameters

Control the visual appearance of the widget.

Parameter	Type	Description
preset	string	Name of the preset JSON file to load (without .json). The widget fetches it from your configured preset hosting location.
bg	string	Page background color — hex value without # (e.g., bg=1e293b). Defaults to 0a0a1a. If the loaded preset also contains a pageBgHex field, the preset value takes precedence.

<iframe
  src="https://widget.example.com/?preset=brand_dark_v2&bg=1e293b"
  width="100%"
  height="480"
  frameborder="0"
  style="border: none;"
></iframe>

tip

Setting backgroundColor on the <iframe> element itself does not affect content inside the frame. Use the bg query parameter instead.

Language

Parameter	Type	Default	Description
lang	string	en-US	UI language for filter labels, button text, etc.

Supported values:

Code	Language
en-US	English
de-DE	German
es-ES	Spanish
it-IT	Italian
nl-NL	Dutch

<iframe
  src="https://widget.example.com/?preset=brand_dark_v2&lang=it-IT"
  ...
></iframe>

Priority: ?lang= query param overrides the default language. Falls back to en-US.

Unsupported codes fall back to en-US.

info

The lang parameter controls UI labels only (filter names, button text, etc.). Bet content such as player names and narratives is returned in the language configured on the API side.

Odds & Currency Parameters

Override the odds format and currency set by the preset. These take precedence over preset values.

Parameter	Type	Default	Description
oddsFormat	string	american	Odds display format
currency	string	USD	Currency code for betslip amounts

Supported oddsFormat values:

Value	Display	Example
american	American odds (default)	+150, -200
decimal	Decimal odds	2.50, 1.50
fractional	Fractional odds	3/2, 1/2
probability	Implied probability %	40.0%, 66.7%

The probability format computes implied probability from decimal odds: (1 / decimalOdds) × 100. This is useful for prediction market integrations.

<!-- Prediction market style: probability odds in euros -->
<iframe
  src="https://widget.example.com/?preset=brand_dark_v2&oddsFormat=probability&currency=EUR"
  width="100%"
  height="480"
  frameborder="0"
  style="border: none;"
></iframe>

Priority: defaults → preset → iframe params. If the preset sets oddsType: "decimal" but the iframe URL has ?oddsFormat=probability, probability wins.

tip

The oddsFormat and currency parameters are applied after the preset loads, so they always override preset values regardless of timing.

Filter Parameters

Pre-set the widget's initial filter state. These control which flows are fetched from the API.

Parameter	UI Filter	Valid Values
flowType	Context	fact, fun, plain
betType	Wager Type	singles, parlay, same_game_parlay
bettingMarketEntityType	Market Type	player, team, event
likelihoodType	Probability	likely, possible, longshot
splitType	Bet Type	overs, unders
factFlowType	Fact Flow Display	base, expanded, multi

<!-- Show only fact flows with singles bets, overs only -->
<iframe
  src="https://widget.example.com/?preset=brand_dark_v2&flowType=fact&betType=singles&splitType=overs"
  width="100%"
  height="480"
  frameborder="0"
  style="border: none;"
></iframe>

How Filters Work

1. Server-side rendering — filter params are parsed from the URL and included in the initial API call, so the first page load already returns filtered data.
2. Client hydration — the filter UI reflects the iframe params immediately after hydration.
3. Subsequent fetches — pagination and user-initiated filter changes use the current filter state (seeded from iframe params).

Filter Locking

When the preset includes allowOverrideIframeFilters: false, filter categories set via iframe params are locked in the UI — they show locked chip styling and their options are disabled. Filters not set via iframe remain editable.

When allowOverrideIframeFilters: true (default), users can freely change all filters, including those initially set via iframe params.

Interaction with Presets

• Iframe filter params always take precedence over preset values.
• Presets never contain filter state — filter state is controlled exclusively by iframe params and user interaction.
• Exception: factFlowType is stored in presets but can also be set via iframe params. The iframe param wins during initial state seeding.

Entity Parameters

Narrow the widget feed to a specific league, sport, player, or team. All are optional and can be combined.

Parameter	Type	API Field	Description
leagueId	number	league_id	Filter by league ID
leagueKey	string	league_key	Filter by league key
sportId	number	sport_id	Filter by sport ID
sportKey	string	sport_key	Filter by sport key
playerId	number	player_id	Filter by player ID
playerKey	string	player_key	Filter by player key
teamId	number	team_id	Filter by team ID
teamKey	string	team_key	Filter by team key

<!-- NFL only, scoped to a specific team -->
<iframe
  src="https://widget.example.com/?preset=brand_dark_v2&leagueKey=nfl&teamKey=chiefs"
  width="100%"
  height="480"
  frameborder="0"
  style="border: none;"
></iframe>

Entity parameters are forwarded to the backend on every API call (both SSR and client-side). Only parameters present in the URL are included — omitted parameters have no effect. Integer parameters that cannot be parsed are silently ignored.

Complete Example

Combining all parameter types in a single embed:

<iframe
  src="https://widget.example.com/?preset=brand_dark_v2&bg=1e293b&lang=it-IT&oddsFormat=probability&currency=EUR&flowType=fact&betType=singles&splitType=overs&leagueKey=nfl&bettingMarketEntityType=player"
  width="100%"
  height="480"
  frameborder="0"
  style="border: none;"
></iframe>

This embed:

• Loads the brand_dark_v2 theme preset
• Sets the page background to #1e293b
• Displays UI labels in Italian
• Shows odds as implied probability percentages
• Uses EUR currency for betslip amounts
• Shows only fact flows with singles bets and overs
• Scopes to NFL content
• Filters to player market type only

API Parameter Mapping

For reference, here is how iframe filter parameters map to the backend API:

Iframe Parameter	API Parameter (snake_case)
flowType	flow_type
betType	bet_type
bettingMarketEntityType	betting_market_entity_type
likelihoodType	likelihood_type
splitType	split_type
factFlowType	fact_flow_type
leagueId	league_id
leagueKey	league_key
sportId	sport_id
sportKey	sport_key
playerId	player_id
playerKey	player_key
teamId	team_id
teamKey	team_key

Next Steps

• Widget Overview — introduction and flow types
• Playground — design your theme
• Presets — preset structure and deployment
• Widget Events — handle postMessage events from the widget