> For the complete documentation index, see [llms.txt](https://suigar.gitbook.io/suigar-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://suigar.gitbook.io/suigar-docs/public/sdk.md).

# 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](https://github.com/Suigar-Gaming/ts-sdks) Playground: [playground.suigar.com](https://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.

Register the SDK with your partner wallet address before building any transaction:

```ts
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, Range, and Wheel
* PvP Coinflip create, join, cancel, and unresolved-lobby lookup helpers
* typed onchain game parameter reads through `client.suigar.getGameParameters(game, 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
* 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
* a live integration example and playground flow you can test at [playground.suigar.com](https://playground.suigar.com)
* support for Sui TypeScript SDK v2 only
* the `@suigar/mcp` server and MCP App for read-only, build, and dry-run transaction 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:

1. Create a Sui client for `mainnet` or `testnet`.
2. Register the SDK extension with `suigar()`.
3. Read config or parameters if your UI needs live limits or supported coins.
4. Build a transaction with `client.suigar.tx`.
5. Sign and execute it, or serialize it for another signer.
6. 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` and `SuigarClient`
* `@suigar/sdk/games` for game option types such as `BuildCoinflipTransactionOptions`, `BuildCreatePvPCoinflipTransactionOptions`, `BuildJoinPvPCoinflipTransactionOptions`, `BuildCancelPvPCoinflipTransactionOptions`, `CoinSide`, and `PvPCoinflipAction`
* `@suigar/sdk/utils` for helpers and constants such as `parseGameDetails`, `parseCoinType`, `fromMoveFloat`, `fromMoveI64`, `toBigInt`, `toU8`, `toU16`, `DEFAULT_GAS_BUDGET_MIST`, `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](https://sdk.mystenlabs.com/sui/migrations/sui-2.0) 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, options?)`
* `client.suigar.serializeTransactionToBase64(transaction, options?)`
* `client.suigar.getPvPCoinflipGames(options?)`
* `client.suigar.bcs`
* `client.suigar.tx`

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:

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

If you want to rename the extension:

```ts
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:

* [Coinflip](https://github.com/Suigar-Gaming/suigar/tree/main/docs/public/sdk/coinflip.md)
* [Limbo](https://github.com/Suigar-Gaming/suigar/tree/main/docs/public/sdk/limbo.md)
* [Plinko](https://github.com/Suigar-Gaming/suigar/tree/main/docs/public/sdk/plinko.md)
* [Range](https://github.com/Suigar-Gaming/suigar/tree/main/docs/public/sdk/range.md)
* [Wheel](https://github.com/Suigar-Gaming/suigar/tree/main/docs/public/sdk/wheel.md)

PvP flow:

* [PvP Coinflip](https://github.com/Suigar-Gaming/suigar/tree/main/docs/public/sdk/pvp-coinflip.md)

## Integration flow

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

Continue with the full [integration guide](https://github.com/Suigar-Gaming/suigar/tree/main/docs/public/sdk/integration.md).

## MCP and agent skills

For agent-assisted workflows, the TypeScript SDKs repository also publishes `@suigar/mcp`. It exposes read-only config and metadata tools, unsigned transaction builders, dry-runs, and a compact MCP App inspector. See the [MCP guide](/suigar-docs/public/mcp.md).

Suigar agent skills live in [Suigar-Gaming/agent-skills](https://github.com/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:

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

Install a specific skill:

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

Install all Suigar skills:

```bash
npx skills add Suigar-Gaming/agent-skills
```