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, and read the balance. Reporting a move's stored outcome is optional.
Wallet Path
Wallet movement follows the order lifecycle, on order-book and AMM markets alike:
Buy order placement
Phoenix calls reserve_cash before a buy order becomes open on the book. This is the one call your wallet may decline: the order is then rejected. The player reads what your code means, for example "You don't have enough funds for this bet." for insufficient_funds (see Player Protection). A buy your wallet has not funded within 60 seconds is refused at once as expired; Phoenix then keeps sending the same reserve until your wallet decides it and, if you had taken it, releases it (see Funding deadline).
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. A player's cash out is a sell order of the bet's shares, so it arrives the same way: a credit_cash with reason ORDER_FILLED.
Cancel or expire
When a buy order is cancelled, expires, only partially fills, or fills below the price it reserved for, Phoenix calls release_cash for the unused reserved amount. An order the book refuses after you funded it is released in full (reason ORDER_REJECTED).
Settlement
When a market settles or voids, Phoenix calls credit_cash for settlement payouts, refunds, and corrections. A payout your wallet keeps refusing for 24 hours stops and shows as Refused in the back office until Phoenix resends it (see credit_cash). Amounts are exact in the currency's smallest unit, rounded in the house's favour (see Exact amounts and rounding).
Balance and Status
Phoenix calls balance to show a player's cash when the embed connects. Balance is not the source of truth for open orders, fills, positions, or settlement.
When a money move times out or fails in transit, Phoenix sends the same move again with the same idempotency key, so your stored result answers it. Phoenix never calls transaction_status, which reports a move's stored outcome by its key without moving money; it is optional, for your own reconciliation.
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.
- Optionally, return a move's stored outcome by idempotency key, for your own reconciliation.
- Accept every capture, release and credit: only a reservation may be declined.
- Store signed request and response evidence for reconciliation.
Bridge events from the embed are useful for your UI, but they are not proof that money moved in your wallet.