Wallet Model
How wallet operations relate to trading and settlement
Phoenix owns the prediction-market trading subledger. The operator owns the player's external cash wallet.
That means Phoenix decides whether an order, fill, position, ledger entry, or settlement decision exists. The operator wallet records the external cash effect that lets the operator show, lock, unlock, or credit player funds outside Phoenix.
Contract shape
The wallet contract is operation-based: reserve cash, release unused reserves, capture filled reserves, credit cash, query balance, and check transaction status.
Order-Book Wallet Path
The hosted iframe is order-book based. Wallet movement follows the order lifecycle:
Buy order placement
Phoenix calls reserve_cash before a buy order becomes open on the book. If the operator rejects the reservation, the order is rejected and the player sees an insufficient-funds style state.
Fill execution
When a buy order fills, Phoenix records the fill and calls capture_cash for the buyer. When a sell order fills, Phoenix calls credit_cash for the seller proceeds.
Cancel or expire
When a buy order is cancelled, expires, or only partially fills, Phoenix calls release_cash for the unused reserved amount.
Settlement
When a market settles or voids, Phoenix calls credit_cash for settlement payouts, refunds, voids, and corrections.
Balance and Status
Phoenix can call balance to bootstrap or reconcile a player's available and reserved cash. Balance is not the source of truth for existing open orders, fills, positions, or settlement.
Phoenix calls transaction_status after an uncertain timeout. This lets Phoenix resolve the original idempotency key instead of sending a replacement money-moving request.
What Operators Should Build
Operators should build a wallet API that can:
- Reserve cash for buy orders.
- Release unused reserved cash.
- Capture reserved cash after fills.
- Credit available cash for proceeds, payouts, refunds, voids, and corrections.
- Return balance by player, currency, operator, and environment.
- Return transaction status by idempotency key.
- Store signed request and response evidence for reconciliation.
Phoenix UI events are useful for product state, but they are not proof that money moved in the operator wallet.