Getting Started

Use this checklist when bringing Phoenix into a new operator environment.

1. Exchange Integration Details

Phoenix needs these values from you:

Item	Purpose
Operator code	Stable public code used in iframe URLs and JWT `iss` claims
Operator display name	Shown in admin and support workflows
Ed25519 public key	Phoenix uses it to verify your launch JWTs and signed Operator API requests
Wallet base URL	Phoenix calls `{base}/debit`, `{base}/credit`, and `{base}/rollback`
Supported currencies	Currency codes that can appear in markets and wallet calls
Allowed parent origins	Web origins allowed to embed and communicate with the iframe

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

2. Implement Wallet Callbacks

Phoenix calls your wallet whenever money has to move:

POST /debit before a prediction is accepted
POST /credit after a prediction settles
POST /rollback if a previously accepted debit must be reversed

Each callback is signed by Phoenix. Your backend must verify the signature and make every tx_id idempotent.

3. Mint Launch Tokens

Your backend mints short-lived EdDSA JWTs:

Visitor tokens let users browse public prediction content.
Player tokens let authenticated users place predictions, view their portfolio, and use player-only features.

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

4. Configure an Experience

In Phoenix Prediction admin, create an embed experience for the operator. An experience chooses:

Template, initially classic
Theme settings
Feature toggles
Layout and sizing mode
Market and topic filters
Parent bridge behavior
Compliance and support links
Allowed parent origins

The iframe URL selects the saved experience by key.

5. Embed the Iframe

Use the operator code, launch token, and experience key:

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

Phoenix will provide the final embed host for your environment.

6. 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

7. Validate Before Launch

Before production traffic:

Verify Phoenix signatures on wallet requests.
Replay the same wallet tx_id and confirm your backend does not double-process it.
Test visitor launch, player launch, token refresh, and deposit flow.
Test debit success, debit rejection, credit success, and credit retry.
Confirm your allowed parent origins match your production and staging domains.