API reference

All SDK methods are available on window.RollerzSDK. The SDK uses Promises; use await or .then()/.catch().

---

Core

init(gameId, options?)

Initialize the SDK with a game ID. Must be called before any other SDK methods. Full guide (bridge lifecycle, options, and getGameId) →

Parameter	Type	Example	Description
gameId	string	'my-game-id'	Unique identifier for your game
options	InitOptions		Optional configuration
options.platformEvents	Record<string, (data?) => void>	{ mute: ({ muted }) => {} }	Callbacks for platform events. Host sends flat postMessages ({ type, ...fields }); SDK dispatches by data.type and invokes the matching callback with the full message object.
options.enableLogging	boolean	true	Enable SDK console logging.

The allowlist of accepted parent origins is baked at build time from the PLATFORM_ORIGINS env var (comma-separated); see the platform events section for details. It's not exposed through InitOptions — games can't widen or disable the allowlist at runtime.

Returns: Promise<void>

await sdk.init('my-game-id', {
  platformEvents: {
    mute: ({ muted }) => { myAudio.muted = muted; }
  }
});

getGameId()

Get the game ID passed to init().

Returns: string | null

getUser()

Fetch a player snapshot from the SDK server (POST /api/user). Returns balance, currency, optional session id, player alias, and optional session stats (seconds, rounds, winLoss) derived from Reelsoft-style RGS responses. Does not store data in the SDK.

Prerequisites: init() has completed, and a provider session exists (e.g. after openGame()). If there is no session for the current bridge client, the request fails (bridge surfaces an error).

Returns: Promise<User>

const user = await sdk.getUser();

Full behavior, HTTP details, and RGS field mapping: Player snapshot (getUser) on the Core SDK functionality page.

---

Events

on(event, callback)

Listen for bridge events.

Parameter	Type	Example	Description
event	string	'balance_updated'	Event name
callback	(payload) => void	(data) => console.log(data)	Callback function

off(event)

Remove an event listener.

Parameter	Type	Example	Description
event	string	'balance_updated'	Event name

---

Generic API

call(endpoint, body?, method?)

Make a generic API call through the bridge. Used internally by providers; can be used for custom endpoints. The bridge attaches an X-Client-Id header on every request so the SDK server can keep provider sessions isolated per browser load.

Parameter	Type	Example	Default	Description
endpoint	string	'/api/custom'	—	API path
body	object	{ key: 'value' }	—	Request body
method	string	'GET'	'POST'	HTTP method

Returns: Promise<T>

---

Bet types

A "bet type" is a per-provider hint that tells the math server which math model to use for a round. Providers like GO3 use it to pick between BASE and BOOSTED payout tables; Stepper uses it to pick a difficulty level (BEGINNER → INSANE); GP forwards arbitrary strings to the underlying math server.

Each provider exposes three accessors:

Accessor	Type	Description
getBetTypes()	readonly string[]	The full ordered list of supported bet types
getDefaultBetType()	string | null	The bet type used when placeBet is called with no betType opt
getBoostedBetType()	string | null	The bet type that the legacy boosted: true sugar resolves to

Provider defaults:

Provider	Bet types	Default	Boosted alias
GO3	['BASE', 'BOOSTED']	'BASE'	'BOOSTED'
RippinRumble	['BASE', 'BOOSTED', 'BASE_BUNDLE']	'BASE'	'BOOSTED'
Stepper	['BEGINNER', 'EASY', 'MEDIUM', 'HARD', 'INSANE']	'MEDIUM'	null (boosted not supported)
GP	[] (configurable)	null (configurable)	null (configurable)

Bet type resolution rules for placeBet(amount, opts?) and getValidBets(opts?):

1. If opts.betType is provided, it wins.
2. Else if opts.boosted === true, the resolved bet type is provider.getBoostedBetType(). Throws if the provider has no boosted alias.
3. Else the resolved bet type is provider.getDefaultBetType(). Throws if the provider has none (only happens for an unconfigured GP).
4. If the provider has a non-empty betTypes list, the resolved value must be a member — otherwise the call throws "invalid betType <x>" before any network request goes out.

The legacy positional form placeBet(amount, true) / getValidBets(true) still works as a deprecated shorthand for { boosted: true }.

Constants: the typed bet type lists are exported from @rollerz/types for use in UI code and tests:

import {
  GO3_BET_TYPES, GO3_DEFAULT_BET_TYPE, GO3_BOOSTED_BET_TYPE, type Go3BetType,
  STEPPER_BET_TYPES, STEPPER_DEFAULT_BET_TYPE, type StepperBetType,
  RIPPINRUMBLE_BET_TYPES, RIPPINRUMBLE_DEFAULT_BET_TYPE, RIPPINRUMBLE_BOOSTED_BET_TYPE, RIPPINRUMBLE_BASE_BUNDLE_BET_TYPE, type RippinRumbleBetType,
} from '@rollerz/types';

GP intentionally exports no constants — see the GP provider section for gp.configureBetTypes().

---

GO3 provider

Access via sdk.go3. All methods require an open session (call openGame() first).

go3.openGame()

Open a GO3 session.

Returns: Promise<Go3Session>

const session = await sdk.go3.openGame();
console.log(session.balance, session.chipLevels);

go3.getSession()

Get the current GO3 session, or null if no session is open.

Returns: Go3Session | null

go3.getValidBets(opts?)

Get valid bet amounts for the resolved bet type. The BOOSTED list is the chip levels multiplied by the boosted multiplier; the BASE list is the raw chip levels.

Parameter	Type	Example	Default	Description
opts.betType	string	'BOOSTED'	'BASE'	The bet type to fetch valid amounts for
opts.boosted	boolean	true	false	Sugar — same as betType: 'BOOSTED'

Returns: number[]

go3.placeBet(betAmount, opts?)

Place a bet. Validates the amount client-side before sending.

Parameter	Type	Example	Default	Description
betAmount	number	100	—	Bet amount
opts.betType	string	'BOOSTED'	'BASE'	Which bet type to send to the math server
opts.boosted	boolean	true	false	Sugar — same as betType: 'BOOSTED'

Returns: Promise<Go3BetResult>

const result = await sdk.go3.placeBet(100);
// result.count, result.hasBonus, result.multiplier, result.roundId

// Boosted (sugar):
await sdk.go3.placeBet(200, { boosted: true });
// Boosted (explicit):
await sdk.go3.placeBet(200, { betType: 'BOOSTED' });

go3.collect(roundId)

Collect winnings for a completed round.

Parameter	Type	Example	Description
roundId	string	'rnd_abc123'	Round ID from placeBet result

Returns: Promise<{ balance: number }>

await sdk.go3.collect(result.roundId);

---

Stepper provider

Access via sdk.stepper. All methods require an open session (call openGame() first).

stepper.openGame()

Open a Stepper session. Returns chip levels, balance, and bet constraints.

Returns: Promise<StepperSession>

const session = await sdk.stepper.openGame();
console.log(session.balance, session.chipLevels);

stepper.getSession()

Get the current Stepper session, or null if no session is open.

Returns: StepperSession | null

stepper.getValidBets(opts?)

Returns chip levels from the session. The same chip levels apply across all difficulty levels — betType selects the math model, not the amount range.

Parameter	Type	Example	Default	Description
opts.betType	'BEGINNER' | 'EASY' | 'MEDIUM' | 'HARD' | 'INSANE'	'HARD'	'MEDIUM'	Difficulty level (all return the same chip levels for now)

Returns: number[]

stepper.placeBet(betAmount, opts?)

Start a new round at the given difficulty. The betType is sent to the math server, which selects the matching payout table (steps + max multiplier). Stepper does not support the boosted sugar — pass betType explicitly to pick a non-default difficulty.

Parameter	Type	Example	Default	Description
betAmount	number	5	—	Bet amount (must be a valid bet level)
opts.betType	'BEGINNER' | 'EASY' | 'MEDIUM' | 'HARD' | 'INSANE'	'HARD'	'MEDIUM'	Difficulty / payout table

Returns: Promise<StepperBetResult>

// Default difficulty (MEDIUM):
const result = await sdk.stepper.placeBet(5);

// Pick a difficulty:
const insane = await sdk.stepper.placeBet(5, { betType: 'INSANE' });
// result.roundId, result.difficulty (matches the requested betType),
// result.steps, result.currentStep (0)

Difficulty cheat sheet (from the math server):

Difficulty	Steps	Max multiplier
BEGINNER	24	20×
EASY	22	100×
MEDIUM	20	500×
HARD	18	2000×
INSANE	16	10000×

stepper.step(roundId)

Advance one step in the ladder. The server reveals whether the step is SAFE (round continues) or CRASH (round ends, bet lost). After a safe step, the player can step again or collect.

Parameter	Type	Example	Description
roundId	string	'rnd_abc123'	Round ID from placeBet result

Returns: Promise<StepperBetResult>

const stepped = await sdk.stepper.step(result.roundId);
if (stepped.roundEnded) {
  console.log('Crashed! Bet lost.');
} else {
  console.log('Safe! Payout:', stepped.currentPayout);
}

stepper.collect(roundId)

Cash out at the current step payout. The round must have at least one successful step before collecting (the first step after placeBet is mandatory).

Parameter	Type	Example	Description
roundId	string	'rnd_abc123'	Round ID from placeBet result

Returns: Promise<{ balance: number }>

await sdk.stepper.collect(result.roundId);

---

GP (General Purpose) provider

Access via sdk.gp. The GP (General Purpose) provider is a passthrough provider that connects your game to any external math server. Unlike GO3 or Stepper, the GP provider does not define game-specific result fields — the raw math server response is passed through in the math field of the bet result.

All methods require an open session (call openGame() first).

gp.openGame(options)

Open a GP session. Requires the math server URL and an internal client code identifying the game type.

Parameter	Type	Example	Description
options.serverUrl	string	'https://math.example.com/mock'	URL of the math server
options.internalClientCode	string	'go3'	Game type identifier used by the math server
options.path	string	'/gameevent/v2'	Custom endpoint path (default: /gameevent)

Returns: Promise<GPSession>

const session = await sdk.gp.openGame({
  serverUrl: 'https://math.example.com/mock',
  internalClientCode: 'go3',
});
console.log(session.balance, session.chipLevels);

Overriding the /gameevent endpoint

By default, the SDK appends /gameevent to the server URL when communicating with the math server (per the Reelsoft contract). If your math server serves on a different path, pass the path parameter to override it:

const session = await sdk.gp.openGame({
  serverUrl: 'https://math.example.com/mock',
  internalClientCode: 'go3',
  path: '/gameevent/v2',
});

gp.getSession()

Get the current GP session, or null if no session is open.

Returns: GPSession | null

gp.configureBetTypes(types, options?)

GP-only. Register the bet types this GP session should accept and (optionally) which one to use as default / boosted alias. Available only on the GP provider — the predefined providers cannot be reconfigured.

When called, GP overwrites its internal bet type list, default, and boosted alias, invalidates the cached valid-bets, and re-fetches them from the server (if a session is already open). After configuration, placeBet and getValidBets validate the bet type against the registered list and throw "invalid betType" for unknown values — exactly the same behavior as the predefined providers.

Parameter	Type	Example	Description
types	readonly string[]	['STANDARD', 'MEGA']	The full ordered allow-list
options.defaultBetType	string	'STANDARD'	The bet type used when placeBet is called with no opts. Defaults to types[0]
options.boostedBetType	string | null	'MEGA'	The bet type the legacy boosted: true sugar resolves to. Defaults to null (boosted not supported)

// Minimal — first element becomes default; boosted sugar disabled.
sdk.gp.configureBetTypes(['STANDARD', 'MEGA', 'JACKPOT']);

// Fully explicit — works with the bet selector and boosted sugar.
sdk.gp.configureBetTypes(['BASE', 'BOOSTED'], {
  defaultBetType: 'BASE',
  boostedBetType: 'BOOSTED',
});

If defaultBetType or boostedBetType reference a value not in types, the call throws synchronously.

If GP is never configured, placeBet({ betType: 'ANYTHING' }) still works as a pure pass-through — the string is sent to the math server unchanged with no client-side validation. placeBet with no opts (and placeBet({ boosted: true })) throws because there's no default to fall back to.

gp.getValidBets(opts?)

Get valid bet amounts for the resolved bet type. Without configuration, GP returns the session's chip levels for any betType.

Parameter	Type	Example	Default	Description
opts.betType	string	'STANDARD'	(configured default, or throws)	Which bet type to fetch valid amounts for
opts.boosted	boolean	true	false	Sugar — resolves through the configured boostedBetType

Returns: number[]

gp.placeBet(betAmount, opts?)

Place a bet. Validates the amount client-side before sending. After configureBetTypes has been called, the resolved betType is also validated against the configured allow-list. The result includes a math field containing the raw response from the math server.

Parameter	Type	Example	Default	Description
betAmount	number	100	—	Bet amount
opts.betType	string	'STANDARD'	(configured default, or throws)	Which bet type to send to the math server
opts.boosted	boolean	true	false	Sugar — resolves through the configured boostedBetType

Returns: Promise<GPBetResult>

sdk.gp.configureBetTypes(['BASE', 'BOOSTED'], {
  defaultBetType: 'BASE',
  boostedBetType: 'BOOSTED',
});

const result = await sdk.gp.placeBet(100); // betType: 'BASE'
const boosted = await sdk.gp.placeBet(100, { boosted: true }); // betType: 'BOOSTED'
// result.roundId, result.totalWinAmount, result.math (raw RGS response)

// Extract game-specific fields from the math passthrough.
// Note: GP preserves the math server's wire field names — for a GO3-compatible
// server this is `rocksCrushed`, not the `count` that the sdk-server layer
// renames it to when fronting GO3 directly.
const details = result.math?.details || {};
const count = details.rocksCrushed || 0;

gp.collect(roundId)

Collect winnings for a completed round.

Parameter	Type	Example	Description
roundId	string	'rnd_abc123'	Round ID from placeBet result

Returns: Promise<{ balance: number }>

await sdk.gp.collect(result.roundId);

---

Types

Go3Session

Field	Type	Description
sessionId	string	Session ID
requestCounter	number	Request counter
balance	number	Current balance
currency	Currency	Currency info (see shared Currency type)
chipLevels	number[]	Available bet amounts
minBet	number	Minimum bet
maxBet	number	Maximum bet
defaultBet	number	Default bet amount
boostedMultiple	number	Boosted bet multiplier

Go3BetResult

Field	Type	Description
roundId	string	Round ID (use for collect)
balance	number	Balance after bet
totalBetAmount	number	Total bet
totalWinAmount	number	Total win
count	number	Items hit (0–3)
multiplier	number	Win multiplier
hasBonus	boolean	Whether a bonus was found
nextAction	string[]	Next actions (e.g. collect)

StepperSession

Field	Type	Description
sessionId	string	Session ID
requestCounter	number	Request counter
balance	number	Current balance
currency	Currency	Currency info
chipLevels	number[]	Available bet amounts
minBet	number	Minimum bet
maxBet	number	Maximum bet
defaultBet	number	Default bet amount

StepperBetResult

Field	Type	Description
roundId	string	Round ID (use for step/collect)
balance	number	Balance after action
totalBetAmount	number	Total bet
totalWinAmount	number	Total win (0 if crashed, payout if cashed out)
difficulty	string	Difficulty level (BEGINNER, EASY, MEDIUM, HARD, INSANE)
currentStep	number	Current step number (0 after placeBet, increments with each step)
currentPayout	number	Payout amount if the player cashes out now
steps	StepperStep[]	Full step ladder with outcomes (see below)
roundEnded	boolean	Whether the round has ended (crash or cash out)
nextAction	string[]	Next valid actions (["CONTINUE"] or ["CONTINUE", "CASH_OUT"])

StepperStep

Field	Type	Description
step	number	Step number (1-based)
payout	number	Payout at this step
outcome	string	"UNDECIDED", "SAFE", "CRASH", or "CASH_OUT"