10 min readIntegrate crash games into your casino without double cash-outs. Signed wallet callbacks, idempotent transactions, WebSocket events & verification code included.
Building a crash game integration?
Get a free technical estimate from our iGaming architects.
If you already run a casino or sportsbook, you don't need a second platform to offer a crash game (the Aviator-style format where a multiplier climbs until it crashes). You need a crash engine that plugs into the wallet, sessions and player accounts you already have. Done right, the player never leaves your site and your data stays yours.
Done wrong, it's where money leaks: double cash-outs, orphaned bets after a server restart, forged wallet callbacks, a client that gets to decide its own payout. This guide covers the architecture of a crash game API integration that avoids those failures, in the order you'd build it.
Note: The endpoint and field names below are an illustrative reference contract, and currency codes are placeholders. Your engine vendor's actual names will differ, but the pattern holds.
What a Crash Game API Integration Actually Involves
A crash engine integrates with your platform through four surfaces:
| Surface | Direction | Purpose |
|---|---|---|
| Session launch | Your platform → engine | Start an authenticated player session |
| Wallet callbacks | Engine → your platform | Debit, credit and roll back player balance |
| Bet / cash-out API | Client or your backend → engine | Place, cancel and settle bets |
| WebSocket events | Engine → client | Round state, multiplier, crash |
The engine owns the game: round lifecycle, crash point, settlement. Your platform owns the player: identity, balance, KYC, limits. Keep that boundary clean and every later decision gets easier. If you're still deciding between building and integrating, see our custom crash game development service and our breakdown of crash game development cost and timeline. This work sits inside our wider casino and sportsbook development practice, and if you don't have a platform to integrate into yet, start with our guide to white-label casino software.
Step 1: Launch an Authenticated Session
Your backend, never the browser, requests a session and hands the player a short-lived signed token.
POST /v1/sessions
{
"playerId": "plr_8841",
"currency": "USD",
"returnUrl": "https://casino.betadrix.tech/lobby",
"locale": "en"
}
Response:
{ "launchUrl": "https://crash.betadrix.tech/play?t=eyJ...", "expiresIn": 300 }
Rules that save you later:
- Authenticate the session request itself with a server-side API key or signed request. It must never be callable from a browser.
- Make the token single-use and expire it in minutes.
- Bind it to
playerIdand currency server-side. Don't trust values sent by the client. - Exchange the token for a session cookie or header on first load so it doesn't linger in URLs, logs or
Refererheaders, and serve the launch page withReferrer-Policy: no-referrer. - Reject a second concurrent session per player, or define explicitly how you handle it.
Step 2: Wire the Wallet With Signed, Idempotent Callbacks
In a seamless wallet model, the balance stays in your system and the engine calls you for every money movement. You implement three callbacks: debit (bet placed), credit (cash-out win) and rollback (round cancelled).
These endpoints move money, so they need two protections: proof that the caller is your engine, and safety against retries.
Authenticate every callback
Sign each request (HMAC over a timestamp plus the raw body, or mutual TLS) and reject anything unsigned, stale or tampered with. An unauthenticated wallet endpoint is a public "add money" button.
import { createHmac, timingSafeEqual } from "node:crypto";
// Capture the raw request body (req.rawBody) before JSON parsing.
function verifySignature(req, res, next) {
const ts = req.get("x-timestamp");
const sig = req.get("x-signature");
if (!ts || !sig || Math.abs(Date.now() - Number(ts)) > 30_000) return res.sendStatus(401);
const expected = createHmac("sha256", process.env.ENGINE_SECRET)
.update(`${ts}.${req.rawBody}`)
.digest();
const given = Buffer.from(sig, "hex");
if (given.length !== expected.length || !timingSafeEqual(given, expected)) {
return res.sendStatus(401);
}
next();
}
Make every callback idempotent
Every callback carries a unique transaction ID. Networks retry, so your handler must return the same result for the same ID instead of moving money twice. The order of operations matters: lock the wallet row first, then check for a prior result. If you check first, two concurrent retries can both pass the check and both debit.
app.post("/wallet/debit", verifySignature, async (req, res) => {
const { txId, playerId, amountMinor, roundId } = req.body;
if (!Number.isSafeInteger(amountMinor) || amountMinor <= 0) {
return res.status(400).json({ status: "INVALID_AMOUNT" });
}
const result = await db.transaction(async (trx) => {
// 1. Lock the wallet row. Concurrent retries of the same txId queue up here.
const wallet = await trx("wallets").where({ player_id: playerId }).forUpdate().first();
if (!wallet) return { status: "UNKNOWN_PLAYER" };
// 2. The replay check is now race-free.
const prior = await trx("wallet_tx").where({ tx_id: txId }).first();
if (prior) return prior.response;
// 3. Decide, then record the outcome either way so a replay answers identically.
let response;
if (wallet.minor < amountMinor) {
response = { status: "INSUFFICIENT_FUNDS", balanceMinor: wallet.minor };
} else {
await trx("wallets").where({ player_id: playerId }).decrement("minor", amountMinor);
response = { status: "OK", balanceMinor: wallet.minor - amountMinor };
}
await trx("wallet_tx").insert({
tx_id: txId,
player_id: playerId,
round_id: roundId,
type: "DEBIT",
amount_minor: amountMinor,
balance_after_minor: response.balanceMinor,
response,
});
return response;
});
res.json(result);
});
Back the handler with a database constraint as well, so a bug in application code can't double-spend:
ALTER TABLE wallet_tx ADD CONSTRAINT wallet_tx_tx_id_key UNIQUE (tx_id);
Non-negotiables:
- Store money as integers in minor units (cents, paise), never floats, and validate that incoming amounts are positive integers.
- Write a ledger entry for every balance change, with player, type, amount, resulting balance and the bet or round it belongs to.
- Make rollback idempotent too. A rollback for a debit you never saw should succeed as a no-op, and should leave a tombstone for that transaction ID so a late-arriving debit is rejected instead of applied.
For the ledger side in depth, read our guide to bet settlement engine design. The examples assume a relational database with row-level locking, such as PostgreSQL.
Step 3: Understand the Bet and Cash-Out Lifecycle
Crash is unforgiving because the timing is adversarial. Players will hammer cash-out in the final milliseconds. The rule that keeps you safe: the server decides every outcome; the browser only displays it.
A safe cash-out runs the same sequence every time:
- Lock the bet row.
- Confirm the bet is still active.
- Compute the multiplier from server time, never the client's clock, and confirm it is still below the round's crash point.
- Calculate the payout.
- Mark the bet
SETTLED_PENDING_CREDITand write an outbox row with a deterministic credit transaction ID (for examplecredit:<betId>) in the same database transaction, then commit. - A worker calls your wallet's credit callback from the outbox, retries until it is acknowledged, then marks the bet
SETTLED.
Don't call the wallet while holding the bet lock. If the network call fails after the bet is marked settled, you have a settled bet with no credit. The outbox pattern makes that state recoverable, and because the credit ID is derived from the bet, retries are idempotent on your side too.
If two cash-out requests hit one bet, the lock plus the state check means only one reaches the outbox. Test this explicitly (see Step 6).
Step 4: Handle WebSocket Events and Reconnection
Use WebSockets for round state. Polling can't keep up with a multiplier that changes continuously. A minimal event set, each carrying a sequence number:
{ "type": "round.betting_open", "seq": 1041, "roundId": "r_1042", "commit": "9f2c...", "closesAt": 1760000000000 }
{ "type": "round.started", "seq": 1042, "roundId": "r_1042", "startedAt": 1760000007000 }
{ "type": "bet.settled", "seq": 1043, "betId": "b_77", "multiplier": 2.31, "payoutMinor": 23100 }
{ "type": "round.crashed", "seq": 1044, "roundId": "r_1042", "crashPoint": 3.87, "serverSeed": "...", "clientSeed": "...", "nonce": 1042 }
Design notes:
- Send
startedAtin server time plus the curve parameters, so clients render the same exponential curve locally. Sync a clock offset on connect. The client draws; it never settles. - Use the monotonically increasing
seqso a reconnecting client can detect gaps and resync from current state. - Keep auto-cash-out on the server. It should fire even if the player's browser has closed.
- Scale horizontally with shared state (Redis is the usual choice) so any node can serve any player.
Background reading: the WebSockets API on MDN, the protocol itself in RFC 6455, and our Socket.io development page.
Step 5: Verify Provably Fair Crash Points
Fairness is checkable only if the server commits to the result before betting opens and reveals the seed after the round. Publish SHA-256(serverSeed) in round.betting_open, then reveal serverSeed in round.crashed. Players can then confirm both that the seed matches the commitment and that the crash point follows from it.
Commit-reveal alone is not enough. In a shared round, the clientSeed must be a public value the operator could not have known when it committed. If the operator knows it in advance, it can generate server seeds until one produces a crash point it likes, then publish that seed's hash. A common design is a hash chain: pre-generate a long chain of seeds, publish the final hash, play the chain in reverse so every commit is already fixed, and mix in a public client seed announced afterwards (for example a Bitcoin block hash). The nonce is the round number. Your engine's design may differ, but what the operator knew at commit time must be stated and checkable.
import { createHmac, createHash } from "node:crypto";
const E = 2n ** 52n;
export function verifyRound({ serverSeed, commit, clientSeed, nonce, crashPoint, houseEdgeBp = 100 }) {
const seedMatches = createHash("sha256").update(serverSeed).digest("hex") === commit;
const hex = createHmac("sha256", serverSeed).update(`${clientSeed}:${nonce}`).digest("hex");
const h = BigInt("0x" + hex.slice(0, 13)); // 52 bits, an integer in [0, 2^52)
const cents = (BigInt(10000 - houseEdgeBp) * E) / (100n * (E - h)); // integer math, floors
const expected = cents < 100n ? 100n : cents; // never below 1.00x
return seedMatches && expected === BigInt(Math.round(crashPoint * 100));
}
This uses integer arithmetic on purpose: floating-point results can differ between languages, and a public verifier has to give every player the same answer.
In this formula the house edge comes from the 0.99 numerator. The chance of reaching any multiplier x of 1.00 or more is 0.99 / x, so every cash-out target returns about 99% over time. A side effect is that roughly 2% of rounds end at exactly 1.00x. Your engine's exact derivation may differ. The point is that it must be published, deterministic and reproducible. The underlying primitive is HMAC, specified in RFC 2104.
Step 6: Test Before You Go Live
Run these against staging, with real concurrency:
- Double cash-out: fire two simultaneous requests at one bet. Exactly one credit should land.
- Mid-round restart: kill the engine during a round. Eligible bets should be refunded, with no orphaned debits.
- Duplicate callbacks: replay the same
txIdten times, including concurrently. Balance changes once and every reply is identical. - Out-of-order callbacks: send a rollback before its debit. The rollback is a no-op and the late debit is rejected.
- Wallet failure during credit: make your wallet time out or return 5xx on a credit. The outbox must retry until acknowledged, with exactly one credit at the end.
- Forged callbacks: send unsigned, stale and tampered requests to every wallet endpoint. All must be rejected.
- Disconnect on cash-out: drop the player's connection at the crash moment. Auto-cash-out still settles correctly.
- Reconciliation: after a load run, engine ledger and your wallet ledger must match to the minor unit.
- Load: simulate thousands of concurrent players, including the spike when a high multiplier crashes and everyone cashes out at once.
Common Integration Mistakes
- Letting the client compute payouts. A modified client will eventually lie.
- Floats for money. Rounding drift becomes a reconciliation nightmare.
- Non-idempotent wallet endpoints. Retries turn into double payouts. Checking for a duplicate before taking the lock is a common version of this bug.
- Unsigned wallet callbacks. Anyone who finds the URL can credit themselves.
- Calling the wallet while holding a database lock. A slow or failed call leaves bets settled but unpaid.
- Using client time for settlement. Always use server time.
- Skipping the crash-mid-round plan. Decide the refund behavior before launch, not after the first outage.
Frequently Asked Questions (FAQ)
What is a crash game API integration?
It's connecting a crash game engine to your existing casino or sportsbook through APIs for sessions, wallet movements, betting and real-time events, so players stay on your platform.
Seamless wallet or transfer wallet?
Seamless keeps the balance in your system and the engine calls your callbacks per transaction. Transfer moves funds into a separate game balance. Seamless gives you a single source of truth, but demands signed, strictly idempotent callbacks.
| Aspect | Seamless wallet | Transfer wallet |
|---|---|---|
| Where the balance lives | Your platform only | Copied into a game balance |
| Source of truth | One ledger | Two ledgers to reconcile |
| What you build | Signed, idempotent debit, credit and rollback endpoints | Deposit and withdraw flows to the game balance |
| Typical failure mode | Retries or timeouts mid-round | Funds stranded in the game balance |
| Best for | Operators who want one balance across casino, sportsbook and crash | Simpler or faster initial launches |
Why is WebSocket better than polling for crash games?
The multiplier changes continuously and bets close within milliseconds. Polling adds latency and load. WebSockets push state as it changes.
How do I prove a crash point wasn't manipulated?
Commit to a hashed server seed before the round, reveal it after, and let players recompute the crash point from the server seed, client seed and nonce. The client seed must be a public value the operator couldn't have known at commit time.
Do I need a license to offer crash games?
Licensing depends on your jurisdiction and is your responsibility. Some markets prohibit real-money games altogether, so confirm what is legal where you operate and consult local legal counsel before launching.
Ready to Integrate?
Betadrix builds crash game engines with an API layer designed to plug into existing casino and sportsbook stacks, with source code ownership and no rental licensing. Read how we built an owned crash platform for a Lahore operator, see how teams launch a white-label casino platform in 30 days, or talk to our architects about your integration.
Related Services from Betadrix
At Betadrix, we specialize in delivering enterprise-grade solutions. Explore our related services to see how we can assist with your technology goals: Custom Crash Game Development | Aviator-Style Platforms | Betadrix, B2B Casino, Sportsbook & Blockchain iGaming Platform Development in Brazil, Custom Software Development Company | Offshore Teams, Jaipur, Crypto Casino Software Development Company | Betadrix.
Prefer to own the engine?
See how custom crash game development gives you full source ownership and no rental licensing.
Betadrix In-House Crash and Instant-Win Originals
Crash
Real-time multiplier curve crash game where players cash out before the curve crashes.
Limbo
Instant-resolve multiplier game where players set a target payout and beat the roll.
Slide
Short-cycle multiplier game designed for high-frequency continuous action.
Trenball
Trend-based side betting engine on top of standard live crash multipliers.
Classic Dice
Customizable roll-over and roll-under provably fair dice betting mechanics.
Towers
Grid-climbing vertical tower survival game with progressive cash-out multipliers.
Wheel
Segmented instant multiplier wheel game featuring configurable risk levels.
Ready to integrate?
Book a free consultation and scope your crash game API integration with a senior architect.
Related Services
Series Guide
iGaming & Casino Gaming
Explore Categories
Browse More Technical Topics & Industry Guides
?Frequently Asked Questions
What is a crash game API integration?
Seamless wallet or transfer wallet?
Why is WebSocket better than polling for crash games?
How do I prove a crash point wasn't manipulated?
Do I need a license to offer crash games?

Shivam Swami
Founder & CEOShivam Swami is the Founder & CEO of Betadrix, driving technical vision, distributed systems engineering, high-throughput iGaming platforms, and enterprise AI architecture.
Build Your Custom Project
Connect with technical architects for scope and estimation.
More Articles in iGaming & Casino Gaming
Related services built to solve your specific challenges
Watch.
Learn.
Grow.
Discover how our engineered solutions transform industries and propel client operations forward.

Owning the Game, Not Renting It: Custom Crash Game Development for a Lahore-Based iGaming Operator
READ CASE STUDYTechnologies & Frameworks Powering This Service
Hire Specialized Developers For Your Service Project

Python Developers
Pre-vetted senior Python Developers ready to deploy into your existing architecture in 3-7 days.

Flutter Developers
Pre-vetted senior Flutter Developers ready to deploy into your existing architecture in 3-7 days.

Nodejs Developers
Pre-vetted senior Nodejs Developers ready to deploy into your existing architecture in 3-7 days.

React Developers
Pre-vetted senior React Developers ready to deploy into your existing architecture in 3-7 days.
What Our Clients Say
“Mobile app development and cloud migration were handled smoothly. Strong technical skills, clear communication, and dependable post-launch support stood out throughout the engagement.”

Sarah Mitchell
Director of Operations, HealthFirst Clinics
Have a Project in Mind?
Let's Build It Together.
Connect directly with our senior software architects and technical leads. We evaluate your requirements and deliver an actionable technical proposal within 24 hours.
Strict NDA Protection
Your intellectual property and technical specs remain 100% confidential.
24-Hour Response Guarantee
Guaranteed evaluation and scoping reply from an engineering manager.
Zero Obligation Estimate
Get accurate cost breakdowns and tech stack recommendations free of charge.
Request Free Technical Consultation
Let's build something serious.
Diagnose your system architecture, budget ranges, and roadmap parameters with an expert.
Scoping Diagnostic
Analyze your workflows in 60 seconds. A senior AI architect reviews every parameter personally.
Not sure where AI actually moves the needle for you?
Answer a few brief questions. We will deliver a highly concrete scoping plan within 24 hours including:
- Recommendations on automation use-cases and MVP components
- Calculations on expected ROI and engineering timelines
- A structural roadmap to make your legacy stack AI-native












