---
url: >-
  https://game-engine-io.github.io/enginex-frontend-sdk/flows/responsible-gaming.md
---
# Responsible gaming

The demo above runs the real SDK on top of `createMockFetch`: no call goes out to the network. In the
**Limits** scenario, `setLimits` records the request and `getLimits` keeps the old value until the
gateway applies it (the 24 h rule belongs to the gateway; the "Simulate the passing of 24 h" button is
mock-only). In **Self-exclusion**, `selfExclude` is only called after an explicit confirmation (the
permanent one asks for a second step) and, after it, the mock's deposit attempt is rejected with
`SELF_EXCLUDED`. In **KYC**, uploading a document changes the status to `pending`; the **Under the
hood** panel shows only the file's type and size. The same demo covers
[Identity verification (KYC)](/flows/kyc).

The `responsibleGambling` namespace reads and sets the player's limits (deposit, loss and session
time), records self-exclusion and returns the data for the reality check. All methods require login.
Monetary values are **minor units** (integers, e.g. cents); see [Money](/concepts/money).

## Read the limits

```ts
const limits = await enginex.responsibleGambling.getLimits()
// {
//   deposit: {
//     daily: { limit: 50000, used: 12000 },
//     weekly: { limit: null, used: 30000 },
//     monthly: { limit: 400000, used: 30000 },
//   },
//   loss: { daily: null },
//   sessionTimeLimitMinutes: null,
//   selfExclusion: { until: null, permanent: false },
// }
```

On the wire, "no limit" is `0` and "no self-exclusion" is the date `1970-01-01T00:00:00Z`; the SDK
delivers `null` in both cases. `used` is how much of the period has already been deposited.

```ts
const { daily } = limits.deposit
const remaining = daily.limit === null ? null : Math.max(0, daily.limit - daily.used)
```

## Set limits

```ts
const { updatedAt } = await enginex.responsibleGambling.setLimits({
  dailyDeposit: 50_000, // R$ 500,00
  weeklyDeposit: null, // remove the weekly limit
  sessionTimeMinutes: 120,
})
```

* An **absent** field is not sent: the current limit stays as it is.
* `null` **removes** the limit (the SDK sends `0`). This is inferred from the gateway's format (`0` comes
  back as "no limit" on read), but the compliance service is not available to confirm it.
* The fields are `dailyDeposit`, `weeklyDeposit`, `monthlyDeposit`, `dailyLoss` (minor units) and
  `sessionTimeMinutes` (minutes). A value that is not an integer ≥ 0 (nor `null`), an input with no
  field, or one that is not an object rejects with `CONFIGURATION_ERROR` **before** any request.

### The 24-hour rule

The gateway responds `limits will be applied in 24 hours`: the new limit is **not effective right away**.
What comes back is `updatedAt` (when the change was recorded), not the new limits, and `getLimits` may
keep showing the old values for up to 24 h. Tell the player ("your new limit takes effect within 24
hours") and do not assume the next read reflects the change. This is gateway behavior; the SDK does not
control or verify the deadline, and the gateway does not say whether the rule also applies to someone
who **lowers** a limit (not verified).

## Self-exclusion

```ts
import type { SelfExclusionDuration } from '@getenginex/sdk'

// `confirmDialog` is your own confirmation screen.
async function selfExcludeAccount(duration: SelfExclusionDuration) {
  const ok = await confirmDialog({
    title: 'Confirm self-exclusion',
    text: 'Your account will be blocked from playing and depositing, and you will not be able to undo this yourself.',
  })
  if (!ok) return
  const { excludedUntil, permanent } = await enginex.responsibleGambling.selfExclude({ duration })
  showExcluded(permanent ? 'forever' : `until ${excludedUntil}`)
}
```

`duration` accepts `24h`, `7d` (cooling-off, a short pause), `30d`, `6m`, `1y` (temporary) and
`permanent`. **It is a serious action and, in practice, irreversible by the player**: never call it
without an explicit confirmation (and, preferably, a second step for `permanent`). To prevent an
accidental click, a missing `duration`, one outside the list or of another type rejects with
`CONFIGURATION_ERROR` and **no request goes out**.

The result is `{ excludedUntil, permanent }`. With `permanent`, `excludedUntil` is `null` (the gateway
sends the epoch date) and `permanent` is `true`; the gateway does not return `permanent` in the
response: the SDK derives it from the requested duration. The later read in
`getLimits().selfExclusion` has the same fields.

After self-exclusion, **launching a game** (casino) fails with the codes from
[Compliance errors](/concepts/compliance-errors) (`SELF_EXCLUDED`, `COOLING_OFF`, `ACCOUNT_BLOCKED`),
and that is the only case verified in the casino service's code. These codes **may also appear** on
deposit, withdrawal and bet (not verified): always decide with `isEnginexError(error, code)`, some
arrive as HTTP 500.

## Reality check

```ts
const check = await enginex.responsibleGambling.getRealityCheck()
// { sessionTimeLimitMinutes: 120, dailyDepositUsed: 12000, dailyLossLimit: null }
```

The gateway **does not track session time**: this route returns the limits as an approximation (the
gateway's own code says so). The app is the one that counts the time since login and decides when to
show the notice; use `sessionTimeLimitMinutes` as the interval and `dailyDepositUsed` / `dailyLossLimit`
as context for the notice.

```ts
const { sessionTimeLimitMinutes } = await enginex.responsibleGambling.getRealityCheck()
if (sessionTimeLimitMinutes !== null) {
  setTimeout(showRealityCheck, sessionTimeLimitMinutes * 60_000)
}
```

## Errors

| Code                       | When                                                                                         |
| -------------------------- | -------------------------------------------------------------------------------------------- |
| `CONFIGURATION_ERROR`      | `setLimits` with an invalid value or no field; `selfExclude` with an invalid `duration` (no request) |
| `UNAUTHENTICATED` (401)    | no session                                                                                   |
| `INVALID_ARGUMENT` (400)   | the gateway rejected the body or the duration (should not happen with the SDK's validation)  |
| `VALIDATION_ERROR`         | in `'strict'`, a date in the response that is not a date                                     |
| `RESOURCE_EXHAUSTED` (429) | rate limit; see `e.retryAfter`                                                               |

Compliance service codes (`SELF_EXCLUDED`, `COOLING_OFF`, `ACCOUNT_BLOCKED`...) arrive with the
`code` preserved, some as HTTP 500. Full list and what to show in
[Compliance errors](/concepts/compliance-errors).

## Testing

`createMockFetch()` answers the four routes with in-memory state: `PUT /limits` stores the values and
returns them on the next read **right away** (the real gateway only applies them after 24 h), and `POST
/self-exclusion` validates the duration like the gateway (400 `invalid duration`).

```ts
import { createEnginexClient } from '@getenginex/sdk'
import { createMockFetch } from '@getenginex/sdk/testing'

const enginex = createEnginexClient({
  baseUrl: 'https://gateway.test', // in Node: absolute baseUrl + tenantHost (optional in the browser)
  tenantHost: 'casino.test',
  fetch: createMockFetch(),
})
await enginex.auth.login({ email: 'ana@exemplo.com', password: 'Senha@123' })
await enginex.responsibleGambling.setLimits({ dailyDeposit: 20_000 })
await enginex.responsibleGambling.getLimits() // deposit.daily.limit === 20000
```

## What the gateway does not offer yet

* **Immediate application.** Limits only take effect after 24 h; there is no way to force it or to query
  the "pending" limit.
* **Real session time.** The reality check returns limits, not time played; the app measures it.
* **Undoing self-exclusion.** There is no route for the player to end a self-exclusion (not even the
  temporary ones); what the operator can do outside the SDK is not exposed.
* **Self-exclusion reason.** The gateway handler reads a `reason` in the body but does not pass it to the
  service; the SDK does not expose it.
* **Weekly or monthly loss limit, bet limit and withdrawal limit.** There is only a daily loss limit;
  withdrawal and bet limits belong to the operator (see the codes in
  [Compliance errors](/concepts/compliance-errors)).
* **Removing a limit as a contract.** `null` (sends `0`) is inferred, not confirmed by the service.
* **History.** There is no list of previous limits or past self-exclusions.
