Skip to main content

Integration

This page shows the common setup for using @suigar/sdk inside a frontend, backend, or game aggregator.

If you want a working reference before wiring your own product, use the live SDK playground: playground.suigar.com

Install​

npm install --save @suigar/sdk @mysten/sui @mysten/bcs

Runtime requirements:

  • Node.js >=22
  • ESM project setup
  • @mysten/sui v2
  • @mysten/bcs v2

Create a Suigar-enabled Sui client​

import { SuiGrpcClient } from '@mysten/sui/grpc';
import { suigar } from '@suigar/sdk';

export function createSuigarClient(
  network: 'mainnet' | 'testnet',
  partner?: string,
) {
  const baseUrl =
    network === 'mainnet'
      ? 'https://fullnode.mainnet.sui.io:443'
      : 'https://fullnode.testnet.sui.io:443';

  return new SuiGrpcClient({
    baseUrl,
    network,
  }).$extend(suigar({ partner }));
}

The SDK uses the connected client network to resolve:

  • Suigar package ids
  • Suigar registry ids
  • supported coin types
  • price info object ids

Partner setup​

If you are a partner, this setup should be treated as required. Do it when the extension is registered, before any transaction builder is used.

const client = createSuigarClient('mainnet', '0xpartner_wallet_address');

Do this:

  • partner must be the partner wallet address that should receive attribution onchain
  • the SDK injects the partner wallet into supported metadata automatically
  • this applies to both standard game transactions and PvP Coinflip flows

Do not do this:

  • do not pass a partner slug, brand name, or display label
  • do not wait until createBetTransaction(...) or createPvPCoinflipTransaction(...) to think about partner attribution
  • do not try to override attribution with manual metadata.partner or metadata.referrer

The reason to keep it here:

  • one registration point covers the whole SDK client
  • every supported builder reuses the same partner attribution setup
  • manual partner metadata patching is more error-prone and the reserved keys are ignored with a warning anyway

Build a standard game transaction​

If you are a partner, the only extra setup is still the extension registration above. The transaction builder call itself stays clean.

const client = createSuigarClient('mainnet');

const tx = client.suigar.tx.createBetTransaction('coinflip', {
  playerAddress: '0x123',
  coinType: '0x2::sui::SUI',
  stake: 1_000_000_000n,
  side: 'heads',
});

What the SDK handles for you:

  • creates the transaction
  • sets the transaction sender from playerAddress and applies the default gas budget
  • normalizes the wallet address and coin type
  • withdraws the coin being wagered
  • injects the correct Suigar package id for the selected game
  • injects the matching price info object for the selected coin
  • transfers the reward object back to playerAddress
  • prepends partner attribution metadata automatically when the extension was registered with partner

Serialize for wallet or transport​

If you need the built transaction as base64 bytes:

const base64 = await client.suigar.serializeTransactionToBase64(tx);

This is useful when the signing step happens somewhere else.

Inspect the resolved config​

const config = client.suigar.getConfig();

console.log(config.packageIds);
console.log(config.coinTypes);
console.log(config.priceInfoObjectIds);

Use this when you want to verify what the SDK resolved for the current network.

PvP Coinflip helpers​

The current SDK also includes runtime helpers for the PvP Coinflip lobby flow:

  • client.suigar.getPvPCoinflipGames(options?)
  • client.suigar.resolvePvPConflipGame(gameId, options?)

Example:

const games = await client.suigar.getPvPCoinflipGames({ limit: 20 });
const game = await client.suigar.resolvePvPConflipGame('0xGAME_ID');

Use these when you need to render open lobbies, inspect a live game, or prepare a join flow from the current onchain state.

Decode Suigar events​

The SDK also exposes BCS structs for common events:

const {
  BetResultEvent,
  PvPCoinflipGameCreatedEvent,
  PvPCoinflipGameResolvedEvent,
  PvPCoinflipGameCancelledEvent,
} = client.suigar.bcs;

Shared standard-game options​

Every standard bet builder shares this base shape:

  • playerAddress: wallet that should receive the reward object back
  • coinType: supported wager coin type
  • stake: logical stake sent to the game contract
  • cashStake: optional withdrawn amount, defaults to stake
  • betCount: optional number of bets, defaults to 1
  • metadata: optional metadata map encoded to byte arrays
  • gasBudget: optional custom gas budget
  • allowGasCoinShortcut: lets the builder use the gas coin path when possible

Notes:

  • playerAddress is the single explicit player identity field used by current builders
  • sender is no longer passed separately
  • partner attribution should come from extension registration, not per-call metadata patching
  • partner integrations should treat suigar({ partner: '0xpartner_wallet_address' }) as the default client setup

Supported coins​

The SDK currently resolves supported coins from internal config:

  • SUI
  • USDC

If an unsupported coin type is passed, the SDK throws before building the transaction.

Example app and playground​

The SDK repository also ships a Next.js integration example app, and the hosted version is available at playground.suigar.com.

Use it when you want to:

  • inspect the current transaction builder inputs and outputs
  • test standard and PvP flows against the current SDK
  • validate partner-oriented integration assumptions with a working reference before wiring your own app

Per-game examples​