Casino
Loading the interactive demo…
The demo above uses createIgaming(enginex) on a client with createMockFetch and the routes of @getenginex/sdk-igaming/testing: no call goes out to the network. The lobby is public (categories, providers, filters and listGames pages); Play and Demo require login. The gameUrl returned by launchGame carries the game session token: the demo does not navigate and shows the URL with the token masked, on screen and in the Under the hood panel. The scenarios show SELF_EXCLUDED in real mode (demo mode still opens) and PROVIDER_ERROR in the catalog.
The casino namespace of @getenginex/sdk-igaming covers the lobby (catalog, categories and providers), launching games and the player's history. The catalog is public: it works without login and does not send the session, even with the player logged in. Launching a game, sessions, history and the biggest winners ranking require login (enginex.auth.login). In tests, withIgamingRoutes already answers all these routes (see Testing).
import { createEnginexClient } from '@getenginex/sdk'
import { createIgaming } from '@getenginex/sdk-igaming'
export const enginex = createEnginexClient({ locale: 'pt-BR' })
export const igaming = createIgaming(enginex)Lobby: games, categories and providers
const [categories, providers] = await Promise.all([
igaming.casino.listCategories(), // [{ slug: 'slots', name: 'Slots', icon, gameCount, priority }]
igaming.casino.listProviders(), // [{ id: 'Pragmatic Play', name: 'Pragmatic Play', gameCount }]
])
const page = await igaming.casino.listGames({
category: 'slots', // slug from listCategories
provider: 'Pragmatic Play', // id from listProviders (opaque: pass it as received)
search: 'olympus', // game name, up to 100 characters
sort: 'popular', // 'popular' | 'new' | 'az'
page: 1,
perPage: 24, // 1 to 100; default 20
})
page.items // Game[]: id, name, thumbnail, isNew, isPopular, isLive, demoAvailable, rtp...
page.totalPageslistGames returns a page (items, page, perPage, totalPages, totalItems). To validate favorites or recents saved in the app, pass the ids in ids (up to 100): games that left the catalog simply do not come back.
const favorites = await igaming.casino.listGames({ ids: savedIds, perPage: 100 })A specific game: igaming.casino.getGame({ gameId }) (GAME_NOT_FOUND if it does not exist).
Casino availability
Maintenance, provider switch, temporary unavailability and an operator without a casino are not errors: the gateway answers 200 and reports the reason in an availability field next to the game list, which this SDK version does not expose yet. In those cases the list may come back empty, with no error — show a generic empty state. UNAVAILABLE/PROVIDER_ERROR (503) only arrive when the call to the casino service itself fails.
Launch a game
launchGame creates the game session (ending the previous one) and returns the URL and how its provider requires it to be opened, in launchTarget: iframe (embedded in the page), redirect (navigate the current tab) or new_tab. Some providers refuse to run inside an iframe, so always branch on it. launchTarget is an open union: treat a value the SDK does not know yet like new_tab. The launch also returns providerCode and, when the provider reports one, expiresAt (open the game before it):
import { isEnginexError } from '@getenginex/sdk'
try {
const launch = await igaming.casino.launchGame({
gameId: game.id,
mode: 'real', // or 'demo', if game.demoAvailable
isMobile: window.matchMedia('(max-width: 768px)').matches,
})
// Open the game the way its provider requires
if (launch.launchTarget === 'iframe') iframe.src = launch.gameUrl
else if (launch.launchTarget === 'redirect') window.location.assign(launch.gameUrl)
else {
// 'new_tab', or a target the SDK does not know yet. Opened after an await, the tab may be blocked as
// a popup (window.open returns null): fall back to the current tab.
const tab = window.open(launch.gameUrl, '_blank')
if (tab) tab.opener = null
else window.location.assign(launch.gameUrl)
}
} catch (e) {
if (isEnginexError(e, 'SELF_EXCLUDED') || isEnginexError(e, 'COOLING_OFF')) showResponsibleGamingNotice()
else if (isEnginexError(e, 'GAME_NOT_FOUND')) showGameUnavailable()
else throw e
}- Language: the gateway uses the input's
languageor, without it, the request'sAccept-Language— which the SDK fills with the client'slocale(createEnginexClient({ locale })orenginex.setLocale()). - Back to the lobby: without
returnUrl, the gateway uses the request'sOrigin, which the browser always sends. In server calls (SSR, Node), passreturnUrlwith an absolute URL. - Popup blockers: browsers only allow
window.openfreely during the click itself, and the example calls it after awaitinglaunchGame, so some browsers (Safari in particular) block the new tab; the example then falls back to the current tab. To always get a real tab, open it in the click handler before the launch (const tab = window.open('about:blank', '_blank')), then settab.location.href = launch.gameUrlfornew_tab, ortab.close()foriframe/redirect. The tradeoff is a blank tab that opens, briefly, for every game. - Relative URL: depending on the provider,
gameUrlmay come relative to the gateway; in that case, resolve it against the gateway origin (new URL(gameUrl, gatewayOrigin)). - Not idempotent: each call opens a new session (and ends the previous one). On a network error, calling again is safe.
- Demo also requires login: the route is protected; for visitors, show the catalog and ask for login when they open the game.
The game URL is a secret
gameUrl carries the player's game session token: whoever has the URL plays with their balance. The SDK delivers it only in the return value of launchGame — no hook (onRequest, onResponse, onError) or onValidationIssue receives the URL, and the response is always validated in strict mode (a malformed response becomes VALIDATION_ERROR, without the values). Do not log the URL, send it to analytics or Sentry, or put it in storage; use it only to open the game.
Sessions, history and winners
const sessions = await igaming.casino.listSessions({ perPage: 10 })
sessions.items[0] // { id, gameId, gameName, provider, startTime, totalBet, totalWin, status: 'active' | 'ended' }
const history = await igaming.casino.getHistory({ page: 1, perPage: 20 })
history.items[0] // { roundId, type: 'bet' | 'win' | 'refund' | 'jackpot' | 'free_spin' | 'reversal', amount, currency, ... }
const winners = await igaming.casino.getBiggestWinners({ limit: 10, days: 7 })
winners[0] // { player: 'Jo***', amount, currency, gameName, wonAt }Amounts are always minor units (cents in BRL; see Money). In the history and the ranking the gateway sends the amount as text (a 64-bit integer); the SDK converts it to number and rejects a value that does not fit with precision with VALIDATION_ERROR. The sessions' totalBet/ totalWin are in the operator's currency. status/type arrive in lowercase, without the protobuf prefix; a new value is passed along in the same format — handle the default case.
The ranking shows only the name masked by the gateway (Jo***): the player's id and full name never reach the app.
Errors
| Code | When |
|---|---|
GAME_NOT_FOUND (404) | getGame/launchGame with an id that does not exist in the catalog |
FAILED_PRECONDITION (422) | launchGame of an inactive game |
SELF_EXCLUDED (422), COOLING_OFF (500), ACCOUNT_BLOCKED (500) | launchGame (real mode) for a player with a responsible gaming restriction |
INVALID_ARGUMENT (400) | listGames with search over 100 characters or more than 100 ids |
UNAVAILABLE (503) | the call to the casino service failed, or restrictions could not be checked |
PROVIDER_ERROR (503), CASINO_UNAVAILABLE (500) | codes defined in enginex-commons for provider/casino failure: treat as unavailable |
UNAUTHENTICATED (401) | methods that require login, with no session |
Identify by code, not by status
COOLING_OFF, ACCOUNT_BLOCKED and CASINO_UNAVAILABLE do not have a status of their own in the gateway yet and arrive with HTTP 500; only PROVIDER_ERROR is mapped to 503. The code is correct: always use isEnginexError(error, code) (see Errors), never error.status.
Testing
import { createEnginexClient } from '@getenginex/sdk'
import { createMockFetch, fail } from '@getenginex/sdk/testing'
import { createIgaming } from '@getenginex/sdk-igaming'
import { withIgamingRoutes } from '@getenginex/sdk-igaming/testing'
const enginex = createEnginexClient({
baseUrl: 'https://gateway.test', // in Node: absolute baseUrl + tenantHost (optional in the browser)
tenantHost: 'casino.test',
fetch: createMockFetch(withIgamingRoutes()),
})
const igaming = createIgaming(enginex)
await igaming.casino.listGames({ category: 'live' }) // fixed catalog: 7 games, 3 categories, 3 providers
await enginex.auth.login({ email: 'ana@exemplo.com', password: 'Senha@123' })
const { gameUrl } = await igaming.casino.launchGame({ gameId: 'mock-game-1' })
// https://games.mock.local/play/mock-game-1?token=mock-launch-token-1&lang=...The mock keeps state per instance: launching a game creates an active session and ends the previous one, and an unknown id returns GAME_NOT_FOUND. To simulate errors, override the route: withIgamingRoutes({ routes: { 'POST /api/v1/games/:gameId/launch': () => fail(422, 'SELF_EXCLUDED') } }).