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, listing feed, listing detail, comments, positions, and market UI
Trading UI	Deposit/cashier handoff when requested	Order ticket, order submission, order status, portfolio view
Wallet	Operator ledger and cashier	Signed wallet operations for reservation, capture, release, credit, balance, and status
Operations	Operator policy, content approval, support process	Admin tools, market state, settlement state, bridge events

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 operator's public config: identity, branding, legal, currencies, the player session, the per-user UI policy from the launch JWT `cfg` claim, the allowed iframe origins, and the socket URL. Theme is derived from the iframe URL params, not stored server-side.
6. The iframe connects to Phoenix services and renders the configured view.
7. The iframe uses `pmm:*` bridge events when it needs the parent page.

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

Player Journey Inside the Iframe

The iframe experience is listing-first:

Players browse categories, filters, and featured listing groups.
A listing opens a player-facing page for an event, question, or collection.
The listing detail view shows one or more binary markets.
Players choose side A or side B through the order ticket.
Phoenix records accepted orders and shows positions/order history inside the iframe.
Resolution and settlement state appear after the market closes and resolves.

Operators should think in listings first, then markets. A listing 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 the operator cashier.
profile.requested when a player opens their account.
token.expiring when the iframe needs a fresh launch token.
resize when auto sizing is enabled (the SDK applies it for you).
navigation and order.placed for analytics or product state.

In turn, your page can drive the embed: navigate, openMarket, openTicket, setToken, and setTheme (runtime re-theming, no reload). 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. (Operators who want to render their own UI use the headless @phoenix-games-io/pmm-sdk data SDK - a separate, more involved path.)

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, confirm the wallet base URL, currency scale, signature keys, idempotency behavior, and reconciliation reports for sandbox and production.