This version (v0.7) has not been published to npm yet.
Skip to content

Responsible gaming ​

Loading the interactive demo…

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

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.

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 (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 ​

CodeWhen
CONFIGURATION_ERRORsetLimits 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_ERRORin '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.

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).
  • 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.