Guide · Architecture
How does a casino API work?
A casino API connects an operator's platform to games it does not host. This guide follows one game round from lobby to report, explains what each system is responsible for and covers the failures that cause most production incidents.
9 min readUpdated By the Turnkeyxgaming team
The three parties in every round
Every casino game round involves three systems. The operator platform owns the player: account, balance, limits and KYC. The studio owns the game: its maths, its certified random number generator and the client the player sees. The aggregator sits between them, translating each studio's protocol into one contract the operator builds once.
Keeping those boundaries clear explains almost every design decision. The studio never sees the player's identity documents. The aggregator never holds the player's money. The operator never runs game maths. Each party is accountable for the part it controls, and regulators audit them on exactly those lines.
One round, step by step
- 01
Catalogue
Your platform has already fetched the game list and rendered the lobby from it.
- 02
Launch
The player taps a game. Your backend asks the aggregator for a session, and the aggregator asks the studio. A launch URL comes back.
- 03
Balance
The game client loads and asks for the balance. The request travels studio → aggregator → your wallet, and the answer travels back.
- 04
Bet
The player spins. A debit request reaches your wallet, which checks funds and limits, deducts the stake and confirms.
- 05
Result
The studio's certified RNG decides the outcome and the client animates it.
- 06
Win
A credit request reaches your wallet with the win amount, even when the win is zero, which closes the round.
- 07
Report
The round is logged with stake, win, studio and currency for GGR reporting and reconciliation.
Why the wallet is the centre of the design
Almost every modern integration uses a seamless wallet: the balance lives only in your ledger, and every money movement is a synchronous call to it. The alternative, a transfer wallet, moves money into separate game balances. That splits the player's funds and creates transfers that can fail half-way. The seamless vs transfer wallet guide covers the trade-off.
With a seamless wallet, your wallet's correctness is the integration's correctness. That is why most integration effort goes into idempotency (the same request twice moves money once), rollbacks (reversing a debit when a round fails) and response time under load.
What goes wrong, and how a good integration handles it
| Failure | What happens | Correct handling |
|---|---|---|
| Debit times out | The studio doesn't know whether the stake was taken | The round is cancelled and a rollback is sent; your wallet refunds if it had debited |
| Credit times out | The player has won but the wallet hasn't confirmed | The credit is retried with the same transaction ID until acknowledged |
| Duplicate request | A retry arrives after the original succeeded | The wallet returns the stored result without moving money again |
| Studio outage | Games from one studio fail to launch | The catalogue marks the studio unavailable; other studios are unaffected |
| Session expires | The player returns to an old tab | The game asks for a fresh launch; no money moves on an expired session |
Security: encryption, allowlists and secrets
Because wallet callbacks move real money, both directions are authenticated. Calls you make carry your operator key and a timestamp, and the wallet callbacks we send are AES-encrypted with the key issued for your environment, so a body that cannot be decrypted is rejected before any wallet movement. The cipher, key handling and protocol version for your account are stated in the credentials pack. IP allowlists add a network-level check, and credentials are separate per environment, so a staging key can never touch production money.
Where to go next
If you are planning the build, the integration guide lays out the phases and the API documentation overview shows the endpoint groups. If you are still deciding whether you need an aggregator at all, read casino API vs aggregator.
One baccarat hand, one lost response, one rollback
Speed baccarat, €50 on the player hand, balance €312. At 20:14:07 the player taps the tile and the launch call returns a URL two seconds later. The client asks for a balance and the wallet answers from the ledger. The betting window opens at 20:14:18; the stake leaves as a debit at 20:14:22 carrying round `BJ-77120`, player `p-40118`, €50, table id and currency.
The wallet commits at 20:14:22.940, writing the idempotency row in the same transaction, and then the response is lost when a load balancer in front of it drops the connection. The studio has not been told the stake was taken. Its timer expires three seconds later: at 20:14:26 it voids the hand and sends a rollback naming `BJ-77120`. That rollback is the only thing that recovers the €50, and it works because the debit was stored before the money moved. The wallet looks up the id, sees a committed debit, refunds, stores the acknowledgement and returns success.
The player sees a hand that never happened and a balance back at €312, which is correct and still opens a ticket. Two omissions would have made it worse. A commit followed by the id insert would leave the rollback with nothing to find and €50 gone. A handler that treated the dropped connection as a refusal would have told the studio the stake was declined, then committed it, so the player paid for a voided hand. The timeout guide covers the second case in detail.
Instrument the round, not only the endpoint
A wallet dashboard that shows request counts will look healthy through most of the failures on this page. These are the measures that describe a round.
- Log the round id on every wallet row it touches, so one lookup returns the balance read, the debit, the credit or rollback, and the studio callback in a single list.
- Count successful debits per round id. A round with two is a bug even when the amounts differ, and it will never show up in a revenue total.
- Compare launch count with round count per game every morning. A launch that produced no round is where the balance call or the client load is failing.
- Map every studio error code into your own short list, and alert on codes you have not mapped instead of passing them through as a generic refusal.
- Time the debit from the request leaving your edge to the response leaving it, not from the first line of the handler. A queued job after the answer is invisible either way.
- Track the rollback rate per studio. One studio drifting upward is a build problem, not a run of bad luck.
- Record the studio's timeout setting per game type, so an incident review can say whether the wallet was late or the window was short.
FAQ
Questions operators ask
How does a casino API work with a live dealer game?
The same way, with timing differences. Bets arrive in bursts during the betting window, and results settle every bet at the table at once.
How many wallet calls does a single round make?
Two on a simple slot: a debit when the player stakes and a credit when the round settles, even when the win is zero. A balance call usually arrives at launch and again on return to the lobby. Live tables may batch several players' stakes, so the count per round is not fixed across game types.
What happens to open rounds if our wallet is down for two minutes?
New launches should fail closed, so no session opens against a balance nobody can read. Rounds already open follow the studio's timeout rules: a silent debit is voided and rolled back, a silent credit is retried until answered. Maintenance is not a reason to refuse a credit.
Keep reading
Related pages
- Product · Casino APICasino APIThe casino API is one contract — a catalogue, a launch call and wallet callbacks — built once and reused for every studio we connect.Read
- IntegrationIntegrationSandbox keys, AES-encrypted wallet callbacks and the four wallet endpoints, then a 24–72 hour go-live once decryption and retries pass.Read
- Product · WalletWalletBalance, bet, win and rollback on one seamless wallet: idempotent transaction ids shared by casino games and sportsbook alike.Read
- Guide · AggregationHow aggregators workAn aggregator turns many studio protocols into one wallet contract and one reconciliation file, so your team builds four endpoints once.Read
Get a written quote and sandbox access
Tell us your licence, target markets and products. You get the GGR rate in writing, the studio list for your markets and sandbox credentials.