Getting started
Choose the product
The SDK is split by product. Every app installs the core (@getenginex/sdk); each of the operator's products comes in a separate package that uses the core client (the same session, tenant and configuration):
| The app needs | Install | Track |
|---|---|---|
| sign-up, login and 2FA, password, profile, wallet, PIX deposit and withdrawal, PIX keys, KYC, responsible gaming, notifications | @getenginex/sdk | Core |
| everything above + casino (lobby, launch a game, history), bonuses (campaigns, promo codes), missions, loyalty and referrals | @getenginex/sdk + @getenginex/sdk-igaming | iGaming |
npm i @getenginex/sdk # core only
npm i @getenginex/sdk @getenginex/sdk-igaming # core + casino, bonuses and engagementThe core is a peer dependency of the product packages: always install it alongside, once. Whoever does not use the casino does not install (or load) casino code. The steps below apply to any product; iGaming only adds step 6.
1. Create the client
Create one client per app in the browser and export it:
// enginex.ts
import { createEnginexClient, localStorageTokenStore } from '@getenginex/sdk'
export const enginex = createEnginexClient({
locale: 'pt-BR',
tokenStore: localStorageTokenStore(),
onSessionExpired: () => location.assign('/login'),
})On the server (SSR, scripts, tests), create one client per request, passing the gateway URL and the operator's domain:
const enginex = createEnginexClient({
baseUrl: 'https://gateway.operador.com',
tenantHost: 'casino.operador.com',
})2. Read the operator configuration
const config = await enginex.config.get()
console.log(config.currency.code, config.paymentMethods.map((m) => m.code))3. Log in
import { isEnginexError } from '@getenginex/sdk'
try {
const result = await enginex.auth.login({ email, password })
if (result.status === '2fa_required') {
// see /flows/login
}
} catch (e) {
if (isEnginexError(e, 'INVALID_CREDENTIALS')) showError('Incorrect email or password')
else throw e
}4. React to the session
enginex.session.subscribe((session) => {
renderHeader(session.status === 'authenticated')
})5. Language and disposal
Change the language at any time with setLocale — the next requests already go out with the new Accept-Language:
enginex.setLocale('en-US')A client per request (SSR, scripts, tests) does not need dispose() — it is already discarded along with the rest of the request. A short-lived client outside that case (e.g. a test that creates several clients), however, should call dispose() when done, to release the session subscription on the tokenStore (the storage listener, if it is the last one, in the case of localStorageTokenStore). After dispose(), every method rejects with EnginexError CONFIGURATION_ERROR:
const enginex = createEnginexClient({ baseUrl, tenantHost })
try {
await enginex.config.get()
} finally {
enginex.dispose()
}6. Products (iGaming)
With @getenginex/sdk-igaming installed, create the casino and bonus namespaces on top of the same client:
// enginex.ts
import { createIgaming } from '@getenginex/sdk-igaming'
export const igaming = createIgaming(enginex)
const lobby = await igaming.casino.listGames({ category: 'slots', perPage: 24 })createIgaming does not create a session or make a request: the login done with enginex.auth.login applies to the casino, and enginex.dispose() also shuts down iGaming. See the iGaming track.
Next.js / SSR
React and Next.js adapters
With React or Next.js, the adapters do what this section shows by hand: @getenginex/sdk-react brings EnginexProvider, useSession (the useSyncExternalStore below) and query hooks on top of TanStack Query; @getenginex/sdk-next also brings the server's per-request client (getEnginexServer, with the tenant taken from the headers) and the prefetch for HydrationBoundary. See the Frameworks track. The rest of this section applies to those who use the core directly.
createEnginexClient never throws on creation, even without location, tenantHost or an absolute baseUrl — the configuration is only resolved (and memoized) on the first request. This makes it safe to import a singleton client in a top-level module that also runs during SSR: if it is never used on the server, nothing breaks; if it is used without the server configuration, the error (EnginexError CONFIGURATION_ERROR) only shows up on that first request, without calling fetch.
On the client (browser), a singleton in lib/enginex.ts, used from a 'use client' component:
// lib/enginex.ts
import { createEnginexClient, localStorageTokenStore } from '@getenginex/sdk'
export const enginex = createEnginexClient({
locale: 'pt-BR',
tokenStore: localStorageTokenStore(),
})// app/components/wallet.tsx
'use client'
import { useSyncExternalStore } from 'react'
import { enginex } from '@/lib/enginex'
// Stable snapshot for SSR: there is no localStorage on the server, so the real session is only
// known in the browser. Always using the same object here (instead of a literal `{ status: 'anonymous' }`
// on every call) avoids React's "getServerSnapshot should be cached" warning.
const ANON = { status: 'anonymous' } as const
export function Wallet() {
const session = useSyncExternalStore(enginex.session.subscribe, enginex.session.get, () => ANON)
return session.status === 'authenticated' ? <p>Authenticated</p> : null
}Note that you cannot use useState(() => enginex.session.get().status): with a tokenStore such as localStorageTokenStore(), the server renders 'anonymous' (there is no localStorage in SSR) and useState initializes the browser already as 'authenticated' for anyone who was logged in — the markup of the client's first render does not match the server's, and React discards the hydration (a "hydration mismatch" error). useSyncExternalStore solves this: on the client's first render it also uses getServerSnapshot (the ANON above), just like the server, and only switches to the real session after hydrating.
On the server (Server Components, Route Handlers), create one client per request, with explicit baseUrl and tenantHost — outside the browser there is no location to discover them:
// app/page.tsx (Server Component)
import { createEnginexClient } from '@getenginex/sdk'
export default async function Page() {
const enginex = createEnginexClient({
baseUrl: 'https://gateway.operador.com',
tenantHost: 'casino.operador.com',
})
const config = await enginex.config.get()
return <main>{config.currency.code}</main>
}Next steps
- Core: sign-up, login and 2FA, PIX deposit, withdrawal with OTP, PIX keys and identity verification (KYC).
- iGaming: casino and launching a game and bonuses and promo codes.
- React and Next.js: provider and hooks, App Router and the guide Migrating a Next player.
- Reference: the full API of all packages, generated from the code, in Reference.