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

`@getenginex/sdk-igaming` brings the EngineX casino, bonus, missions, loyalty, referrals and
sportsbook FIRST flows, built on top of the core client (`@getenginex/sdk`). The operator installs
only the product they have: whoever does not use the casino loads no casino code at all.

| Namespace | What it does |
| --- | --- |
| [`casino`](/igaming/casino) | catalog (games, categories, providers), launch a game, sessions, history and biggest winners ranking |
| [`bonus`](/igaming/bonus) | bonus campaigns (showcase, offers, opt-in, redemption) and promo codes |
| [`missions`](/igaming/missions) | the operator's active missions (paginated) and the player's progress |
| [`loyalty`](/igaming/loyalty) | the player's points, tier and benefits; points redemption |
| [`referrals`](/igaming/referrals) | referral code and link, history (referee email masked) and code registration |
| [`sportsbook`](/igaming/sportsbook) | sportsbook FIRST session (URL with an operator token for the iframe) |

## Installation

```bash
npm i @getenginex/sdk @getenginex/sdk-igaming
# or
pnpm add @getenginex/sdk @getenginex/sdk-igaming
```

The core is a *peer dependency* of the iGaming package: the app installs the core once and all product
packages use that same copy. The requirements are the core's (see [Installation](/guide/installation)).

* **Core versions**: `@getenginex/sdk-igaming` declares the core as a peer `>=0.6.0 <1.0.0` (0.6.0
  brings the strict money handling and per-attempt idempotency that the packages use; 0.5.0 was the
  first with `registerProductClient`, which connects iGaming to the [`/query`](/frameworks/)
  factories; up to iGaming 0.3.x, `>=0.2.0`). This range guides the package manager; the runtime
  guarantee is the core's **transport contract** (the internal `TRANSPORT_CONTRACT_VERSION`, stored
  with each client): if the client comes from a copy of the core with an incompatible contract (e.g.
  two core versions installed), `createIgaming` throws `CONFIGURATION_ERROR` right away, instead of
  working halfway.
* **`zod`**: it is a regular dependency of both the core and iGaming (not a *peer*), deduplicated into
  a single copy when the ranges match. With an out-of-range `zod` in the app (e.g. `zod@3`), two
  copies may remain: the SDK works, but the bundle gets heavier; install a single `zod` 4 at the top of
  the project (see [Installation](/guide/installation#single-zod-copy)).

## Create the iGaming client

Create the core client as in [Getting started](/guide/getting-started) and pass it to
`createIgaming`:

```ts
// enginex.ts
import { createEnginexClient, localStorageTokenStore } from '@getenginex/sdk'
import { createIgaming } from '@getenginex/sdk-igaming'

export const enginex = createEnginexClient({
  locale: 'pt-BR',
  tokenStore: localStorageTokenStore(),
})

export const igaming = createIgaming(enginex)
```

`createIgaming` does not create its own session, tenant or transport and makes no request. Every
iGaming method goes through the app's client:

* the same session and token refresh (a login made with `enginex.auth.login` is valid for the casino);
* the same tenant (`X-Original-Host`), `locale`, `timeout`, [`hooks`](/concepts/extensibility) and
  [validation](/concepts/validation);
* the same [errors](/concepts/errors) (`isEnginexError(error, code)`);
* `enginex.dispose()` shuts iGaming down too: after it, every method rejects with
  `CONFIGURATION_ERROR`.

Create one iGaming client per core client: in the browser, one per app; on the server, one per request,
together with the client. A value that is not a client created by `createEnginexClient` (for example,
a `{ ...enginex }` copy) is rejected with `CONFIGURATION_ERROR`.

## Queries

`@getenginex/sdk-igaming/query` brings the iGaming factories for TanStack Query v5, with the conventions of
the [queries layer](/frameworks/#queries-layer): `createIgamingQueries(igaming)` returns one query factory
per read method and `createIgamingMutations(igaming)` one mutation per write method, with the same names and
inputs as the namespaces. They are plain objects: the package does not depend on TanStack.

```ts
import { createIgamingMutations, createIgamingQueries } from '@getenginex/sdk-igaming/query'

const ig = createIgamingQueries(igaming)
ig.casino.listGames({ page: 1 }) // { queryKey: ['enginex', 'public', 'casino', 'listGames', { page: 1 }], queryFn }
ig.loyalty.get() // { queryKey: ['enginex', 'user', userId, 'loyalty', 'get'], queryFn }

const im = createIgamingMutations(igaming)
im.loyalty.redeem() // { mutationKey: ['enginex', 'loyalty', 'redeem'], mutationFn, invalidates }
```

| Kind | Factories |
| --- | --- |
| public reads (key `['enginex', 'public', ...]`, no login) | `casino.listGames/listCategories/listProviders/getGame`, `bonus.listPublicOffers` |
| player reads (key `['enginex', 'user', userId, ...]`) | `casino.listSessions/getHistory/getBiggestWinners`, `bonus.listOffers/getOffer/listParticipations/getParticipation`, `missions.list/listMine`, `loyalty.get`, `referrals.get/listHistory` |
| mutations | `casino.launchGame`, `bonus.optIn/claim/redeemPromoCode/resolvePromoCode`, `loyalty.redeem`, `referrals.register`, `sportsbook.createSession` |

* `bonus.optIn/claim/redeemPromoCode` and `loyalty.redeem` invalidate their namespace and the core's
  `wallet` (the balance); `referrals.register` invalidates `referrals`; `casino.launchGame` invalidates
  `casino.listSessions`.
* The idempotent ones (`bonus.optIn/claim/redeemPromoCode`, `loyalty.redeem`) accept
  `{ idempotencyKey }` on the factory (see [Idempotency](/concepts/idempotency)).
* The ones that carry credentials (promo code, game URL, sportsbook session) have `gcTime: 0`.
* Pass the object returned by `createIgaming` itself: a `{ ...igaming }` copy throws `CONFIGURATION_ERROR`.

In **React** (and Next.js), `useEnginexQueries` and `useEnginexMutations` take the product factory and the
iGaming client, and memoize the result:

```tsx
import { createIgamingMutations, createIgamingQueries } from '@getenginex/sdk-igaming/query'
import { useEnginexMutation, useEnginexMutations, useEnginexQueries, useEnginexQuery } from '@getenginex/sdk-react'
import { igaming } from './enginex'

function LoyaltyCard() {
  const ig = useEnginexQueries(createIgamingQueries, igaming)
  const im = useEnginexMutations(createIgamingMutations, igaming)
  const loyalty = useEnginexQuery(ig.loyalty.get())
  const redeem = useEnginexMutation(im.loyalty.redeem())
  return (
    <button disabled={redeem.isPending} onClick={() => redeem.mutate({ points: 500, redemptionType: 'bonus' })}>
      Redeem 500 of {loyalty.data?.currentPoints ?? 0} points
    </button>
  )
}
```

In **Vue**, the same pair comes from `@getenginex/sdk-vue`; `useEnginexQuery` takes a getter:

```vue
<script setup lang="ts">
import { createIgamingQueries } from '@getenginex/sdk-igaming/query'
import { useEnginexQueries, useEnginexQuery } from '@getenginex/sdk-vue'
import { igaming } from './enginex'

const ig = useEnginexQueries(createIgamingQueries, igaming)
const games = useEnginexQuery(() => ig.casino.listGames({ page: 1 }), { select: (page) => page.items })
</script>

<template>
  <GameCard v-for="game in games.data.value ?? []" :key="game.id" :game="game" />
</template>
```

On the Next.js server, `prefetchEnginex(createIgamingQueries(igaming), (ig) => [ig.casino.listGames()])`
prefetches the catalog with the same keys (see [Next.js](/frameworks/next)). Svelte, Solid and plain
TanStack use the factories directly ([No adapter](/frameworks/no-adapter)).

## Testing {#tests}

`@getenginex/sdk-igaming/testing` adds the iGaming mock routes to the core's `createMockFetch` (see
[Testing and mocks](/guide/testing)). The core routes keep working and yours (`routes`) win over the
iGaming ones:

```ts
import { createEnginexClient } from '@getenginex/sdk'
import { createMockFetch } 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({ withdrawalOtp: true })),
})
const igaming = createIgaming(enginex)
```

To build the routes object by hand, use `createIgamingRoutes()`, which returns new routes (with their
own state) on every call: `createMockFetch({ routes: { ...createIgamingRoutes(), ...myRoutes } })`.
