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
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.
const { daily } = limits.deposit
const remaining = daily.limit === null ? null : Math.max(0, daily.limit - daily.used)Set limits
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.
nullremoves the limit (the SDK sends0). This is inferred from the gateway's format (0comes 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) andsessionTimeMinutes(minutes). A value that is not an integer ≥ 0 (nornull), an input with no field, or one that is not an object rejects withCONFIGURATION_ERRORbefore 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
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
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.
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.
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).
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 === 20000What 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
reasonin 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(sends0) is inferred, not confirmed by the service. - History. There is no list of previous limits or past self-exclusions.