Integration Checklist

Exchange integration details

Phoenix needs the operator code, display name, Ed25519 public key, supported currencies, allowed parent origins, and wallet base URL for each environment.

You keep the private key. Phoenix only receives the public key.

Set up sandbox and production

Sandbox and production are separate operational boundaries. Confirm these values for both:

• Ed25519 public key
• Allowed parent origins
• Wallet base URL
• Supported currencies
• Discovery configuration and listing setup
• Trading model and settlement workflow

Do not reuse sandbox assumptions in production. A sandbox launch can pass while production still rejects tokens because the key, origin, or wallet mode is different. The environment value is prod (the display label is "Production"); a token with env production is rejected at connect.

Confirm wallet operations

Confirm the wallet base URL and the operation contract for each environment.

Phoenix calls your wallet when prediction-market cash has to move:

• reserve_cash before a buy order opens on the book
• release_cash when unused reserved cash should unlock
• capture_cash when a buy-side fill consumes reserved cash
• credit_cash for sell proceeds, settlement payouts, refunds, voids, and corrections
• balance for bootstrapping and reconciliation
• transaction_status after an uncertain timeout

Each money-moving operation is signed by Phoenix. Your backend must verify the signature and make every idempotency key safe to retry.

Mint launch tokens

Your backend mints short-lived EdDSA JWTs:

• Visitor tokens let users browse public prediction content.
• Player tokens let authenticated users place orders, view positions, and use player-only features.

Never mint launch tokens in browser code. The signing key belongs on your server only.

Every token must include env. Use sandbox for test traffic and prod for production traffic.

Decide appearance and policy

The embed has no saved profile to configure. Its configuration is delivered three ways:

• Appearance rides the iframe URL as optional seed params: mode, accent, radius, cb, yes, no, font, plus sizing and density. The embed derives a full, contrast-safe theme from these seeds; omit them all to get the Phoenix default. See Iframe Launch.
• Per-user UI policy (for example deposit or profile button visibility) rides the signed launch token's cfg claim. A missing flag means shown. Only the operator can sign it, so it cannot be changed by editing the URL.
• Operator-fixed identity, branding, legal links, supported currencies, and allowed parent origins live on your operator account and are served by GET /embed/api/config.

Embed the iframe

Use the operator code and launch token. Add appearance seeds only when you want to override the default theme:

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

Phoenix will provide the final embed host for your environment.

Connect parent events

The iframe asks your site to handle operator-owned actions:

• Login or registration when a visitor clicks a player-only action
• Deposit when the player has insufficient funds
• Token refresh before a launch token expires
• Optional iframe resizing in auto-sizing mode

Do not pass wallet balances, private account state, or cashier instructions through iframe bridge messages unless Phoenix explicitly documents that field. The bridge is for product coordination, not for replacing your backend integration.

Validate before launch

Before production traffic:

• Repeat launch-token, origin, and wallet tests in the prod environment.

• Test visitor launch, player launch, token refresh, and deposit flow.

• Test category browsing, listing detail, order placement, order history, and positions.

• Confirm your allowed parent origins match your production and staging domains.

• Verify Phoenix signatures on wallet requests.

• Replay the same wallet idempotency key and confirm your backend does not double-process it.

• Test reserve, release, capture, credit, transaction status, insufficient funds, and retry behavior.