SDK

The Suigar SDK is the TypeScript package that helps integrators build valid Suigar v2 game transactions on Sui without manually assembling each Move call.

GitHub: Suigar TypeScript SDKs repository Playground: playground.suigar.com

What this is for

Use the SDK when your app needs to:

Build standard Suigar game transactions from normal application inputs
Read live game limits from chain instead of hardcoding them
List or inspect open PvP coinflip lobbies
Decode Suigar event payloads into application-friendly values
Hand a built transaction to a wallet, backend signer, or transport layer

The SDK is not a full app framework. It does not manage wallet connection, signatures, or your UI state. Its job is to give you the correct Suigar-aware client surface on top of a Sui client.

Partner integrations

If you are a Suigar partner, this is the setup to follow.

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

const client = new SuiGrpcClient({
	baseUrl: 'https://fullnode.mainnet.sui.io:443',
	network: 'mainnet',
}).$extend(
	suigar({
		partner: '0xpartner_wallet_address',
	}),
);

Partner rule:

Always configure partner during extension registration
Always pass the partner wallet address
Never pass a slug, project name, or display label
Never try to inject partner attribution manually in each builder call

Why this is the recommended setup:

Partner attribution is injected automatically into supported onchain metadata
The same partner configuration is reused for standard and PvP flows
Reserved metadata keys such as partner and referrer are ignored when passed manually

What has shipped so far

The current SDK project already includes:

Network-aware config for mainnet and testnet
Standard game builders for Coinflip, Limbo, Plinko, Soccer, Range, and Wheel
PvP Coinflip create, join, cancel, and unresolved-lobby lookup helpers
Typed onchain game parameter reads through client.suigar.getGameParameters({ game, coinType, ...options })
Public @suigar/sdk/games exports for shared game option types
Public @suigar/sdk/utils exports for parser helpers, numeric helpers, and shared constants
Generated BCS event parsers for standard and PvP game flows
Generated NFT V1 factory and owned-NFT decoders
Automatic partner metadata injection when the extension is registered with a partner wallet
SDK-managed caching for repeated onchain reads such as game parameter lookups
Bulk PvP Coinflip lobby lookups that skip per-object fetch or parse failures unless throwOnError: true is passed
Referral commission and level-up USD reward read helpers, backed by claim-transaction simulation
Referral claim transaction builders
NFT V1 mint transaction builder
A live integration example and playground flow you can test at playground.suigar.com
Support for Sui TypeScript SDK v2 only
The @suigar/mcp server and MCP App for read-only, build, dry-run, paired-wallet execute, and session-wallet execute workflows

What the SDK does

Registers a Suigar extension on top of a Sui client.
Resolves the right Suigar package ids for mainnet and testnet.
Resolves supported coin types and matching price info object ids.
Builds ready-to-send Transaction objects for Suigar games.
Reads and caches live onchain game parameters such as min and max stake.
Encodes optional metadata into the byte arrays expected by the contracts.
Exposes BCS event structs for decoding game result events.
Can serialize built transactions to base64 when a wallet or backend expects that format.
Can register under a custom extension name instead of client.suigar.

Typical usage flow

Most integrations follow the same sequence:

Create a Sui client for mainnet or testnet.
Register the SDK extension with suigar().
Read config or parameters if your UI needs live limits or supported coins.
Build a transaction with client.suigar.tx.
Sign and execute it, or serialize it for another signer.
Decode returned events when you want structured result data.

If your app has a betting form, step 3 is usually part of the form load. If your app receives already-validated bet requests from another system, you may skip that read and move directly to building.

Public package exports

The package has three public entrypoints:

@suigar/sdk for suigar, SuigarClient, SUPPORTED_SUI_NETWORKS, and core SDK types such as SuigarCoin and SuigarNetwork
@suigar/sdk/games for GAMES and game option types such as CreateGameBetOptions, CoinflipTransactionOptions, CreatePvPCoinflipTransactionOptions, JoinPvPCoinflipTransactionOptions, CancelPvPCoinflipTransactionOptions, SoccerTransactionOptions, and CoinSide
@suigar/sdk/utils for helpers and constants such as parseGameDetails, parseGameEvent, parseCoinType, fromMoveFloat, fromMoveI64, isMoveFloat, isMoveI64, toBigInt, toU8, toU16, DEFAULT_GAS_BUDGET_MIST, DEFAULT_QUERY_LIMIT, DEFAULT_LIMBO_MULTIPLIER_SCALE, DEFAULT_RANGE_SCALE, and RANGE_POINT_LIMIT

Individual transaction builders are not exported from the package root. Use the registered client extension under client.suigar.tx.

Runtime requirements:

Node.js ^22.18.0 || >=24.0.0
ESM project configuration ("type": "module")
@mysten/sui v2
@mysten/bcs v2

This SDK targets Sui TypeScript SDK 2.0+ only. Follow the official Sui 2.0 migration guide if your app still uses the pre-2.0 client API.

What you get at runtime

After registering the extension, the main runtime surface is:

client.suigar.getConfig()
client.suigar.getGameParameters({ game, coinType, ...options })
client.suigar.serializeTransactionToBase64({ transaction, ...options })
client.suigar.getPvPCoinflipGames(options?)
client.suigar.bcs
client.suigar.tx
client.suigar.view

Extension registration options:

partner to inject partner attribution automatically into supported metadata
cacheTtl to control the SDK onchain-read cache in milliseconds
name to register the extension under a different property such as client.games

How to think about these options:

Use partner only when your integration should write partner attribution onchain
Use cacheTtl when your product repeatedly reads parameters and you want to trade freshness for fewer chain reads
Use name only when suigar would collide with another client extension or you want a different local naming convention

For one specific live PvP Coinflip object, use the generated object helper:

const game = await client.suigar.bcs.PvPCoinflipGame.get({
	client,
	objectId: '0xGAME_ID',
});

If you want to rename the extension:

const client = new SuiGrpcClient({
	baseUrl: 'https://fullnode.mainnet.sui.io:443',
	network: 'mainnet',
}).$extend(
	suigar({
		name: 'games',
	}),
);

client.games.tx;
client.games.bcs;

Supported game flows

Standard bet builders:

PvP flow:

PvP Coinflip

Other transaction builders:

client.suigar.tx.referral.claimCommission(...)
client.suigar.tx.referral.claimLevelUpUsdRewards(...)
client.suigar.tx.nftV1.mint(...)

Read-only reward helpers:

client.suigar.view.referral.getCommission(...)
client.suigar.view.referral.getLevelUpUsdRewards(...)

Integration flow

Install the SDK and Sui peer dependencies.
Create a Sui client on mainnet or testnet.
If you are a partner, register the extension with suigar({ partner: '0xpartner_wallet_address' }) before building anything.
Build a game transaction with client.suigar.tx.createGameBet(...) or the action-specific PvP builder.
Sign and execute the transaction, or serialize it to base64 for another signer.

Continue with the full integration guide.

MCP and agent skills

For agent-assisted workflows, the TypeScript SDKs repository also publishes @suigar/mcp. It exposes read-only config and metadata tools, wallet pairing, wallet balance and coin-object reads, unsigned transaction builders, dry-runs, execute-mode approval flows, local session-wallet execution, and a compact MCP App inspector. See the MCP guide.

Suigar agent skills live in Suigar-Gaming/agent-skills. They help AI coding agents install the SDK, wire standard and PvP game flows, and configure the MCP server.

Browse available skills:

npx skills list Suigar-Gaming/agent-skills --list

Install a specific skill:

npx skills add Suigar-Gaming/agent-skills --skill suigar-mcp

Install all Suigar skills:

npx skills add Suigar-Gaming/agent-skills

What this is for​

Partner integrations​

What has shipped so far​

What the SDK does​

Typical usage flow​

Public package exports​

What you get at runtime​

Supported game flows​

Integration flow​

MCP and agent skills​