Integration Model | Phoenix Prediction Docs

The hosted iframe is the supported player integration path. Your product embeds Phoenix Prediction as a contained prediction-market experience, while your site keeps ownership of identity, cashier, compliance surfaces, and wallet-facing account history.

This means players should feel like they are still inside your product, but Phoenix owns the prediction UI inside the frame.

Responsibilities

Area	Owned by your product	Owned by Phoenix Prediction
Page placement	Where the iframe appears, page chrome, navigation around the iframe	The content rendered inside the iframe
Identity	Login, registration, player session, JWT minting	Launch-token validation and player session inside Phoenix
Prediction browsing	Parent page may choose the initial iframe view	Categories, the event feed, event pages, comments, positions, and market UI
Trading UI	Deposit/cashier handoff when requested	Order ticket, order submission, order status, portfolio view, cash out of open bets, and the player's own bets shown on every market
Wallet	Operator ledger and cashier	Signed wallet operations for reservation, capture, release, credit, balance, and status
Operations	Your policy, your own events and their results, curation, player support	The back office, platform events and their results, settlement

Launch Flow

1. Your page decides where to place the iframe.
2. Your backend mints a short-lived visitor or player launch JWT.
3. The iframe loads `/o/{operator_code}?token={JWT}`.
4. Phoenix validates the token and operator environment.
5. Phoenix returns the boot configuration: your operator's display name and currencies, the session (visitor or player, and its currency), the per-user UI policy from the token's `cfg` claim, the session language and your languages, and where to connect. The look comes from your saved look in the back office, then the iframe URL (see [Customization](/customization)).
6. The iframe connects to Phoenix with the same token and renders the requested view.
7. The iframe talks to your page through the bridge (`ns: 'pmm'` messages) when it needs you.

Use visitor tokens for browse-first flows. Use player tokens when the user is already signed in and should be able to place orders, view positions, and use player-specific features. Both need a currency.

The token stays the session's credential: every reconnect uses it again. See Sessions and Token Refresh.

Player Journey Inside the Iframe

The iframe experience is event-first:

Players browse the category bar and the featured events your team chose in Curation.
An event opens its page: a match, a crypto round, or a question.
The event page shows one or more Yes/No markets.
Players pick an outcome through the order ticket.
Phoenix records accepted orders and shows positions and order history inside the iframe.
The result and the payout appear after the market closes and settles.

An event is what players discover; a market is what players trade.

Parent Page Contract

The iframe coordinates with your page through a small bridge. The Host SDK is the recommended way to consume it - embed.on('deposit.requested', …) and embed.setToken(…) instead of raw postMessage. Your page should be ready to handle:

auth.requested when a visitor triggers a player-only action.
deposit.requested when a player needs your cashier.
profile.requested when a player opens their account.
token.expiring and session.expired when the iframe needs a fresh launch token.
reload.requested when the player taps Reload after a session ended (the SDK reloads your page).
resize when auto sizing is enabled (the SDK applies it for you).
navigation, order.placed and notification.received for analytics or your own UI.

In turn, your page can drive the embed: navigate, openMarket, openTicket, setToken, setLanguage, setTheme, setBranding, balanceUpdate, refresh, back, forward and getState. See the Host SDK for the full surface, or Parent Bridge for the raw wire format.

Do not build a separate player trading client unless Phoenix explicitly scopes that as a separate project. These docs are for the hosted iframe integration.

Wallet Contract

The order-book iframe uses wallet operations that match the trading lifecycle. Phoenix reserves cash before a buy order opens, captures reserved cash when fills occur, releases unused reserves when orders cancel or expire, and credits cash for proceeds, payouts, refunds, voids, and corrections.

Before launch, run the wallet test against each environment and walk the Go-Live Checklist.