Skip to main content

PvP Coinflip

PvP Coinflip uses a dedicated builder because the flow has multiple actions instead of a single bet entrypoint.

What the builder does​

createPvPCoinflipTransaction(action, options) builds one of three flows:

  • create
  • join
  • cancel

If you are a partner, configure suigar({ partner: '0xpartner_wallet_address' }) on the client before using any of these flows.

Shared optional options for all PvP actions:

  • metadata
  • gasBudget
  • allowGasCoinShortcut

Create a game​

Use this when a player opens a new PvP Coinflip lobby.

const tx = client.suigar.tx.createPvPCoinflipTransaction('create', {
	owner: '0x123',
	coinType: '0x2::sui::SUI',
	stake: 1_000_000_000n,
	side: 'heads',
	isPrivate: false,
});

Required action-specific fields:

  • stake
  • side

Optional action-specific fields:

  • isPrivate

Before creating a lobby, you can read the live PvP Coinflip parameters when you need current stake limits:

const parameters = await client.suigar.getGameParameters('pvp-coinflip', {
	coinType: '0x2::sui::SUI',
});

console.log(parameters.min_stake);
console.log(parameters.max_stake);

This is useful when you want to reject invalid lobby stakes before the creator signs the transaction.

Typical create flow:

  1. read live PvP stake limits
  2. collect stake, side, and optional privacy choice
  3. build the create transaction
  4. sign and execute it
  5. surface the resulting gameId in your UI

Join a game​

Use this when a second player joins an existing PvP Coinflip.

const tx = client.suigar.tx.createPvPCoinflipTransaction('join', {
	owner: '0x123',
	coinType: '0x2::sui::SUI',
	gameId: '0xGAME_ID',
});

Required action-specific fields:

  • gameId

The join flow intentionally does not ask you for stake. The SDK reads the live game object for gameId, derives the required join amount from that object, and uses the configured price info object automatically.

Typical join flow:

  1. discover a lobby from getPvPCoinflipGames() or by a pasted gameId
  2. fetch or inspect the live game state if needed
  3. build the join transaction
  4. sign and execute it

Cancel a game​

Use this when the creator needs to cancel an unresolved lobby.

const tx = client.suigar.tx.createPvPCoinflipTransaction('cancel', {
	owner: '0x123',
	coinType: '0x2::sui::SUI',
	gameId: '0xGAME_ID',
});

Required action-specific fields:

  • gameId

Typical cancel flow:

  1. identify one unresolved creator-owned lobby
  2. build the cancel transaction with that gameId
  3. sign and execute it

Discover open lobbies​

Use the runtime helpers when you need to render open games or inspect a live lobby before joining:

const games = await client.suigar.getPvPCoinflipGames({ limit: 20 });

Typical usage:

  • use getPvPCoinflipGames() to render the open lobby list
  • use client.suigar.bcs.PvPCoinflipGame.get(...) when a player lands directly on one known lobby
  • use throwOnError: true for admin or debugging surfaces where silent skipping would hide a real issue

getPvPCoinflipGames() reads the configured PvP Coinflip registry, bulk-loads the referenced game objects, and returns the parsed unresolved lobbies. Failed per-object fetches or parses are skipped by default so one stale entry does not break the whole lobby response.

Registry membership is the unresolved-state signal. Once a game resolves, the Move flow removes it from the registry and deletes the live Game object.

Each returned lobby also includes a derived coin_type, which is useful when your UI needs to group or label lobbies by wager coin without re-parsing the Move type string yourself.

Pass throwOnError: true when your integration should fail the whole lookup on the first bad object:

const games = await client.suigar.getPvPCoinflipGames({
	limit: 20,
	throwOnError: true,
});

For one known live game object, use the generated object helper:

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

Notes​

  • join derives the required stake from gameId and uses the configured price info object automatically
  • partner attribution is injected automatically when the extension is registered with partner
  • partner attribution should not be passed manually in each PvP builder call
  • reserved metadata keys such as partner and referrer are ignored with a warning when passed manually
  • PvP Coinflip also exposes BCS structs for created, resolved, and cancelled events through client.suigar.bcs.
  • unresolved-registry lookup is the source of truth for open lobbies, so prefer it over maintaining your own stale mirror of joinable games