Iframe Launch | Phoenix Prediction Docs

The Phoenix Prediction iframe is the prediction-market application that runs inside your site. Your page controls where it appears. Phoenix controls the market UI inside the frame.

Most integrations should use the Host SDK: it builds this iframe for you (with the correct sandbox and security) and turns the bridge into typed methods and events. This page documents the underlying URL and iframe if you prefer to build it by hand.

URL Shape

https://embed.prediction.phoenixverse.io/o/{operator_code}?token={JWT}

Part	Meaning
`{operator_code}`	Your Phoenix Prediction operator code, for example `acme`. May also be passed as `?operator=acme` instead of the `/o/{code}` path. It must match the token's `iss`
`token`	A visitor or player launch token minted by your backend (required)

token is the only required parameter. One embed host serves both of your environments: the token's env claim decides which one the launch belongs to.

Basic Embed

<iframe
  src="https://embed.prediction.phoenixverse.io/o/acme?token=JWT"
  style="width: 100%; height: 720px; border: 0"
></iframe>

This default mode works well when your page owns the frame size and the iframe scrolls internally.

Recommended Attributes

<iframe
  id="phoenix-prediction-embed"
  title="Prediction markets"
  src="https://embed.prediction.phoenixverse.io/o/acme?token=JWT"
  style="width: 100%; min-height: 720px; border: 0"
  sandbox="allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox allow-forms"
  allow="clipboard-write; fullscreen"
></iframe>

allow-same-origin is required (the embed needs its own origin for storage and its connection) and is safe because the embed is a different origin from your page.

The embed can only be framed by an https page, so test from an https host, not http://localhost. Keep launch tokens out of logs, analytics URLs, and third-party tracking.

Visitor and Player Launches

Mode	Use when	What the user can do
Visitor (no `sub`)	The user is not signed in on your site	Browse events, prices, charts, order books, activity and the leaderboard
Player (`sub` set)	The user is signed in on your site	Everything a visitor can, plus place and cancel orders, see their portfolio, save events, comment

When a visitor taps a player-only action, the iframe emits auth.requested. Your site signs the user in, mints a player token, and sends it back (embed.setToken(token) with the SDK, or a setToken command). See the Host SDK.

URL Parameters

Param	Meaning
`token`	Visitor or player launch token (required)
`operator`	Operator code, instead of the `/o/{code}` path
`view`	Initial view: `feed` (default), `portfolio`, `leaderboard`, `activity`, `saved`, or `listing`. A view the operator switched off opens the feed
`listing`	The event's slug, required with `view=listing`
`sizing`	`container` (default) or `auto`. See Sizing
`density`	`comfortable` or `compact`. Defaults to your look's spacing, else `comfortable`

The embed takes your page's origin from the browser, and talks only to the sites listed on the environment (see Allowed Origins). It does not read a parent_origin parameter.

Appearance parameters (mode, accent, radius, colors, font, layout and charts) override the look you saved in the back office for this page. They are documented in Customization. The odds parameter chooses a price format for this page, whichever formats your Betting settings allow (see Odds and Charts).

There is no language parameter: the language comes from the launch token's language claim, the embed's own picker, or setLanguage (see Languages).

What the Iframe Loads

On start, the iframe calls GET /o/{operator_code}/embed/api/config on the Phoenix backend with your token. The answer carries your operator's display name and currencies, the session (visitor or player, and its currency), the cfg UI policy from the token, the session's language and your operator's languages, and where to connect.

If the token is refused, the iframe shows the player why instead of the markets, tells your page with an error event carrying the refusal's code, and waits for a fresh setToken. The config call's response names the reason too (see Refusals You Can Read and Sessions and Token Refresh).

Initial View

?view=feed
?view=portfolio
?view=activity
?view=listing&listing=btc-daily-close

With no view, an unknown one, a view the operator switched off (leaderboard or activity, see Features), or view=listing without a listing, the iframe opens the feed.