---
url: https://game-engine-io.github.io/enginex-frontend-sdk/igaming/casino.md
---
# Casino

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`](/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](#tests)).

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

```ts
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.totalPages
```

`listGames` returns a [page](/concepts/pagination) (`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.

```ts
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).

::: info 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):

```ts
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 `language` or, without it, the request's `Accept-Language` —
  which the SDK fills with the client's `locale` (`createEnginexClient({ locale })` or
  `enginex.setLocale()`).
* **Back to the lobby:** without `returnUrl`, the gateway uses the request's `Origin`, which the browser
  always sends. In server calls (SSR, Node), pass `returnUrl` with an absolute URL.
* **Popup blockers:** browsers only allow `window.open` freely during the click itself, and the example
  calls it after awaiting `launchGame`, 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 set
  `tab.location.href = launch.gameUrl` for `new_tab`, or `tab.close()` for `iframe`/`redirect`. The
  tradeoff is a blank tab that opens, briefly, for every game.
* **Relative URL:** depending on the provider, `gameUrl` may 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.

::: danger 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

```ts
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](/concepts/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 {#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                            |

::: warning 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](/concepts/errors)), never `error.status`.
:::

## Testing {#tests}

```ts
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') } })`.
