How to Integrate Provably-Fair Games With an SDK

Suigar TeamJul 3, 202610 min read

SDK Integration Provably Fair On-Chain Developers

If you are a developer wiring up an on-chain casino, the games are not the hard part. The hard part is the plumbing: constructing a valid transaction, passing the right game parameters, submitting it, and then reading the result back out of the chain so your interface can show the player what happened. Get that loop right and everything else is presentation.

This is a practical look at casino game integration via an SDK, written for engineers. We will walk the full request-response cycle of a provably-fair bet on the Sui blockchain: building the transaction, reading game parameters, submitting it, and decoding the on-chain events that tell you the outcome. Throughout, the canonical reference is the Suigar integration guide, which documents the exact contract surface.

The goal is to make the moving parts concrete so you can estimate the work before you commit to it, and so the code you write maps cleanly onto a system whose fairness you never have to fake. If you are integrating because you intend to operate a brand, it is worth reading this alongside the business side of running a white-label casino on Sui, since the SDK is the technical half of that same partnership.

Why integrate provably-fair games through an SDK at all

You could, in theory, hand-craft every transaction against the raw contract ABI. An SDK exists so you do not have to. It wraps the contract entry points in typed builders, handles serialization, and gives you helpers for reading parameters and decoding events. That means less surface area for bugs and a faster path from idea to working bet. The Suigar integration guide is where these builders are documented end to end, and it is the single most useful page if you are scoping this work.

The deeper reason is trust. Because the games are provably fair and settle on-chain, your SDK is not asking you to trust a black-box server response. It is helping you submit a transaction whose outcome is decided by on-chain randomness and recorded publicly, which you can then verify independently. The SDK is a convenience layer over a system that is honest by construction.

What runs where in the stack

Before writing code, it pays to be clear about the division of responsibility, because it is unusual compared with a conventional backend. Your front end handles presentation, wallet connection, and the user flow. The SDK turns user intent into a valid Sui transaction and helps you read state back. The smart contracts hold the game logic, draw the randomness, and settle the bet. The chain stores the result. Notably, there is no game server of yours in that list.

That absence is the whole point. The trust-critical work, deciding outcomes and moving funds, happens in audited contracts on a public chain, not in infrastructure you stand up and secure. Your job is the glue and the experience around it. This keeps your attack surface small and your operational burden light, because you are not running an RNG, a custody system, or a settlement engine of your own.

The integration loop in 4 steps

At the highest level, every game interaction follows the same 4-step shape, and it is identical across all 8 first-party games. Understanding this loop before you read a single line of SDK reference makes the rest fall into place.

Read the game parameters. Fetch the current limits, payout multipliers, and configuration for the game you are integrating, so your interface offers only valid bets.
Build the bet transaction. Use the SDK transaction builder to assemble a valid call with the player’s stake, chosen parameters, and any partner attribution.
Submit and await settlement. Sign and send the transaction; on Sui it settles fast, so the player is not left waiting on a slow confirmation.
Decode the result event. Parse the on-chain event emitted by the contract to learn the outcome and payout, then update your interface from verified data.

Step one: reading game parameters

Before a player can place a bet, your client needs to know what a valid bet looks like: the minimum and maximum stake, the available options, and the payout structure. These live on-chain and the SDK exposes typed reads for them. Pulling parameters at load time keeps your interface in sync with the contract, so you never let a player submit a bet the chain will reject. The Suigar SDK reference lists the read functions per game; the Coinflip docs are a compact example to read first because the game has the fewest moving parts.

Treat these reads as the source of truth rather than caching hard-coded values in your front end. Parameters can be updated on-chain, and an interface that reads them live will always present the correct options without a redeploy.

Step two: building the bet transaction

This is the heart of the integration. The SDK gives you a transaction builder for each game that takes the player’s inputs and produces a programmable transaction ready to sign. You supply the stake, the chosen outcome or target, and your partner identifier; the builder handles encoding, type tags, and gas configuration. Because Sui uses programmable transaction blocks, you can also compose additional calls into the same transaction when your design needs it.

The most important discipline here is to build from live parameters, not assumptions. Validate the stake against the limits you read in step one before you build, so the transaction you submit is one the contract will accept. If you are new to assembling these on Sui, the integration guide shows the builder signatures and the partner-registration call that attaches your wallet to the bet for on-chain attribution.

In shape, the whole loop fits in a handful of lines. Install the SDK, read a parameter, build and sign the bet, then decode the settlement event:

pnpm add @suigar/sdk @mysten/sui @mysten/bcs

import { SuigarClient } from '@suigar/sdk';

const suigar = new SuigarClient({ network: 'mainnet' });

// Read a live game parameter before building the bet
const { minStake, maxStake } = await suigar.coinflip.getConfig();

// Build the bet transaction (stake is validated against the limits above)
const tx = suigar.coinflip.buildBet({ stake, choice: 'heads', partner });

// Sign and submit with your wallet, then decode the settlement event
const result = await wallet.signAndExecute(tx);
const { won, payout, roll } = suigar.coinflip.decodeResult(result);

This snippet is illustrative pseudo-code, not a copy-paste API; method names and shapes will differ. See the Suigar integration guide for the exact current builders, reads, and event decoders.

Step three: submitting and settling

Once the transaction is built and signed, you submit it like any Sui transaction. Sui finalizes quickly, in roughly 390 ms, so the player experience feels immediate rather than the multi-second wait some chains impose. Combined with fees of a fraction of a cent (under $0.01) per bet, this fast, low-fee settlement is one of the reasons theSui casino software stack is a good fit for real-time games. From a code standpoint, your job is to handle the success and failure paths cleanly and surface a clear message either way.

Randomness happens on-chain

You do not generate the randomness and you do not request it from a server. The contract draws from on-chain verifiable randomness on Sui as part of settlement. This is the structural reason the game is provably fair: there is no seed in your infrastructure to protect, unlike a classic 3-input scheme that hashes a server seed, a client seed, and a nonce through SHA-256 into a 256-bit value, and no place for an outcome to be tampered with between request and result. If you want the player-side intuition for what this guarantees, ourprovably-fair Plinko guide shows what a verifiable result looks like once it lands.

Step four: decoding on-chain events

When the contract settles a bet, it emits an event describing what happened: the player, the inputs, the random result, and the payout. Your client reads that event and updates the interface from it. This is the step that closes the trust loop, because the value you show the player comes from the chain, not from a hopeful guess your front end made after submitting.

Decoding events well also gives you everything you need for history, analytics, and dispute resolution. Since the data is on-chain, any result a player questions can be reconstructed independently, which is a support advantage you do not get with an off-chain RNG.

Handling the unhappy paths

Robust integrations spend most of their effort on what happens when things do not go cleanly. A transaction can fail validation if a stake slips outside the live limits, a wallet can reject a signature, or the network can be momentarily congested. Decide up front how your interface communicates each case: a rejected bet should never look like a lost one, and a pending transaction should never look like a settled result. Because the chain is the source of truth, the safe rule is to update the player’s balance and outcome only from a confirmed on-chain event, never from an optimistic guess your front end made at submit time.

On-chain partner attribution

For operators, the SDK does one more thing that matters commercially: it lets you register as a partner and attach your wallet address to the transactions your players generate. That attribution is recorded on-chain rather than in a dashboard that could change, so the revenue relationship is durable. Wiring this in during step two means every bet is attributed from the very first play. Which games you integrate first is partly a product decision, and the on-chain game catalog for operators breaks down what each title brings before you commit engineering time.

A comparison: SDK integration versus rolling your own

SDK integration: typed builders, parameter reads, and event decoders maintained against the live contract, so you ship faster with fewer encoding bugs.
Raw contract calls: full control but you own serialization, type tags, and ABI drift, which is a lot of fragile surface for no real upside.
Off-chain RNG service: familiar to build but reintroduces exactly the trust problem on-chain settlement was meant to remove, so you lose the provable-fairness story.

For almost every team, the SDK path wins because it keeps you close to the audited contracts while removing the tedious, error-prone glue.

Testing and going live

Build against test networks first. Exercise the full 4-step loop, read, build, submit, decode, with small stakes and confirm your event parsing matches the on-chain truth before you point real funds at it. Because the contracts behind all 8 Suigar games were independently audited by MoveBit on 2025-11-10, your integration risk concentrates in your own glue code rather than in the game logic, which is exactly where you want it to sit.

Frequently asked questions

What does the SDK actually give me?

Typed transaction builders for each game, helpers to read on-chain game parameters, partner-registration calls, and decoders for the events the contracts emit. It wraps the contract surface so you do not hand-roll serialization.

Do I generate the randomness in my code?

No. Randomness is drawn from on-chain verifiable randomness on Sui during settlement. There is no seed in your infrastructure, which is what makes the games provably fair.

How do I know the result is correct?

The contract emits an event with the inputs, the random draw, and the payout. You decode that event and show it. Because it is on-chain, any result can be reconstructed and verified independently.

How fast does a bet settle?

Sui finalizes transactions in roughly 390 ms for a fraction of a cent (under $0.01), so a bet feels immediate to the player. That speed is part of why the chain suits real-time games.

How is partner revenue tracked?

You register as a partner and attach your wallet to the bet transaction. The attribution is recorded on-chain, so the relationship persists regardless of interface changes.

Can I integrate just one game to start?

Yes. Each of the 8 games has its own builders and parameter reads, so you can start with a single title like Coinflip and add the other 7 later using the same loop.

Where should I begin reading?

Start with the integration guide for the overall flow, then the per-game SDK references. Coinflip is the simplest game to wire up first.

The takeaway

Integrating provably-fair games comes down to a clean 4-step loop: read parameters, build the transaction, submit it, decode the result. An SDK turns each of the 4 steps into a typed, documented call against audited contracts, so you spend your time on product instead of on serialization.

The payoff is that the fairness is real, not asserted. Your code submits a bet, the chain decides it with verifiable randomness, and your interface reports a result anyone can check. For a white-label operator, that is the difference between a casino you can defend and one you have to apologize for.

Sources and further reading

Sui on-chain randomness, Sui documentation.

Sui platform documentation, Sui docs.

Smart-contract audits, MoveBit.

On-chain betting market context, GambleFi overview.

Gambling involves risk and is intended for adults only. Operators are responsible for compliance, age verification, and responsible-gambling practices in every market they serve.