Reconciliation
Match Phoenix wallet operations to the operator ledger
Reconciliation proves that Phoenix Prediction wallet operations and the operator wallet ledger agree.
The practical question is simple: every Phoenix Prediction idempotency key should affect the operator wallet exactly once.
Reconcile by environment
Keep sandbox and prod reports separate. The same player identifier or market pattern can appear in both environments during rollout, but money movement belongs to only one ledger.
What to Store
For every money-moving wallet operation, store:
| Field | Why |
|---|---|
idempotency_key | The primary join key. Always present, opaque, and platform-generated |
operation | reserve_cash, release_cash, capture_cash, or credit_cash |
operator_id and environment | Environment-scoped reconciliation (sandbox or prod) |
player.external_id | Operator-side player account |
currency_code and amount object | Exact wallet movement amount |
references object | Store it verbatim. Under wallet API 1.0 the keys Phoenix sends are order_id (reserve, capture, release, a maker rebate on a mint), taker_order_id plus maker_order_id (trade and merge credits), claim_side (settlement payouts), and payout_id plus claim_side (payout corrections). Under 1.1 every move also carries venue_id, market_id, outcome and final, and a final move its mode (Positions) |
| Request fingerprint | Detects idempotency key reuse with different payloads |
| Request body | Audit and support |
| Response body | Proves what your wallet returned |
| Final available and reserved balance | Support and accounting |
| Signature result | Security audit |
| Processed timestamp | Ordering and investigation |
Join on idempotency_key first. It is the platform-generated dedup identity and the only field guaranteed on every operation, so it is the spine of every report. The references keys are correlation hints to map a wallet move back to a Phoenix order or settlement: order_id ties a reserve, capture, or release to one buy order; taker_order_id plus maker_order_id tie a sell-proceeds or merge credit to the matched trade; claim_side tags a settlement payout. Treat idempotency_key as opaque and never parse it; its internal prefix records the trigger (for example reserve:, capture:, release:, credit:, settle:) but that format is internal and not a contract.
Daily Reconciliation
Run these checks at least daily during launch:
Count reserve_cash operations against accepted buy orders.
Count capture_cash operations against buy-side fills.
Count release_cash operations against cancelled, expired, partially filled and refused orders, and buys that filled below the price they reserved for.
Count credit_cash operations against sell and merge proceeds, maker rebates, settlement payouts and refunds (including zero-amount finals under wallet API 1.1), and corrections.
Find duplicate idempotency keys and confirm they had one wallet effect.
Compare Phoenix trading ledger totals with operator available and reserved wallet movement.
Player Support Flow
When a player asks about a prediction:
- Find the player by your
player.external_id. - Find Phoenix Prediction wallet transactions by
idempotency_key(primary), then narrow with thereferenceskeys you stored:order_idfor a reserve, capture, or release;taker_order_idandmaker_order_idfor a trade or merge credit;claim_sidefor a settlement payout. - Confirm whether cash was reserved for the order.
- Confirm whether reserved cash was captured or released.
- Confirm whether settlement, refund, void, or correction credit was applied.
- Compare final balance with your wallet ledger.
Do not rely only on iframe UI state for wallet support. The operator wallet ledger is the financial source of truth.
Phoenix's Side of the Ledger
Your finance team can compare against Phoenix's own records in the back office:
- Finance > Reconciliation lists one row per day and currency: the day's money totals (staked, sold, paid out, refunded, and so on down to the net) and the number of wallet moves.
- Finance > Wallet moves lists every wallet move, searchable by idempotency key, player or order id.
- Trades shows each player action with the wallet moves it caused and their keys.
Each can be exported as CSV. See Players, Trades and Finance.
Common Mismatches
| Symptom | Likely cause |
|---|---|
| Player cash reserved twice | Duplicate reserve_cash idempotency key was not handled correctly |
| Player has stuck reserved cash | release_cash failed, is still retrying, or was applied against the wrong order_id |
| Player missing proceeds | credit_cash is still being retried, or your wallet refused it for 24 hours and Phoenix has raised it with you |
| Player missing a payout | The payout is still being retried, or your wallet refused it for 24 hours and it shows as Refused in the back office |
| Operator captured too much | Cumulative capture plus release exceeded the original reservation |
| Operator ledger has unknown Phoenix transaction | Missing request logging or shared wallet endpoint reuse |
| An order was rejected with a wallet reason | Your wallet declined the reservation (wallet_declined:<code>), did not fund it within 60 seconds (expired), or Phoenix did not send the call (wallet_not_called:<code>, for example wallet_url_not_public) |
Launch Recommendation
During the first production rollout, reconcile more often than usual. Prediction markets create new support questions because players are watching open positions, market close, resolution, and wallet settlement as separate moments.