Knowledge · Architecture
iGaming wallet system architecture
A robust iGaming wallet is a double-entry, immutable, idempotent ledger. This guide covers the primitives that make bet, win and rollback safe at scale.
Updated January 2025 · AS Tech iGaming editorial
Double-entry ledger
Every wallet event is two ledger rows: a debit on one account and a credit on another (or on a virtual house account). Bets debit the player and credit the game round; wins debit the game round and credit the player. Never mutate historic rows — corrections are always compensating entries.
Idempotency
Every wallet write is keyed by (operator_id, player_id, transaction_id). Duplicate writes with the same key return the original response without re-applying — critical because game providers issue retries on any network timeout.
Atomic transactions
Bet + immediate settlement (win or loss) can be modeled as a single atomic transaction where the ledger locks the player row, writes debit, checks balance, writes credit (if win) and releases the lock. Row-level locking is preferred over table-level to keep p95 write latency under 50ms.
Rollback semantics
Rollback is a compensating entry, never an update. The original transaction stays in the ledger; the rollback carries the original transaction_id in its metadata for reconciliation. Rollback is idempotent — duplicate rollback calls return the original rollback response.
Multi-currency
Player currency is locked at signup. Deposits in other currencies are converted at spot on entry; wallet balance is always in the player's native currency. Cross-currency reconciliation happens at the operator level, not the player level.
Cross-vertical balance
Casino, sportsbook, crash and lottery share the same player balance. The vertical is metadata on each ledger entry, not a separate wallet. This is critical for cross-sell retention economics.
Frequently asked questions
Should I use a relational DB or a KV store?+
Relational (Postgres) — the double-entry model needs strong consistency, foreign keys and row-level locks. KV stores can serve reads but cannot safely serve writes.
What's the fastest way to check balance?+
Materialised balance-per-player view refreshed on every write. Reads hit the view (<1ms); writes update the view atomically with the ledger insert.
How do I handle refunds?+
Refunds are compensating credits with a refund reason code. Never edit or delete the original debit.
Do I need Kafka?+
Not for a small operator. Once you cross ~10k rps of wallet writes, Kafka helps decouple provider callbacks from the ledger writer.
Encryption at rest?+
Yes — every jurisdiction requires it. Player PII goes in an encrypted schema; ledger entries can stay in a standard schema.