Deposit rollover
A deposit may carry a rollover: part of the real balance can only be withdrawn after the player wagers a multiple of the deposit. wallet.getDepositRollover() (GET /deposit-rollover) answers with the totals (summary), the deposit history (deposits, newest first, cursor-paginated) and the deposit the wallet consumes first (oldestPending). This page builds the screen that lists the rollover deposit by deposit: an "in progress" tab, a "history" tab, a progress bar per deposit and a "load more" button.
For the withdrawable amount alone, wallet.getBalance() is enough (withdrawableBalance, depositRolloverRemaining; see Withdrawal).
Never poll this read
The wallet serves GET /deposit-rollover under a row lock on the player's wallet: while it runs, the bets, prizes and withdrawals of that player wait for it. Read it when the screen opens and when the player asks ("load more", "try again"), and nothing else:
- no polling (
refetchInterval,setInterval); - no refetch on window focus or on reconnect;
- no automatic retry (
retry: false; the SDK itself never retries it); - no reload on a realtime message: a
balance_updateis not a reason to read the rollover again.
Reading the pages
Ask for a page with pageSize (1 to 100, gateway default 25) and pass the nextCursor you got as cursor for the next one. Two things can go wrong between reads, and the SDK has a helper for each:
- a new deposit shifts the list, so a deposit already shown comes back on the next page:
mergeDepositRolloverPageskeeps its first copy (and every row without adepositId, which has nothing to be matched by); - the gateway hands back a cursor already used:
nextUnseenCursorreturnsundefined, so paging stops instead of reading the same pages forever.
import { mergeDepositRolloverPages, nextUnseenCursor, type DepositRollover } from '@getenginex/sdk'
const pages: DepositRollover[] = []
const usedCursors: (string | undefined)[] = []
let cursor: string | undefined
// Call on open, then only when the player taps "load more".
async function loadPage() {
usedCursors.push(cursor)
const page = await enginex.wallet.getDepositRollover({ pageSize: 20, cursor })
pages.push(page)
cursor = nextUnseenCursor(page.nextCursor, usedCursors)
render({
summary: pages[0]!.summary,
deposits: mergeDepositRolloverPages(pages),
canLoadMore: cursor !== undefined,
})
}Use the first page's summary: the totals do not depend on the cursor. Give the rows without a depositId a key of your own (e.g. their index) when rendering a list.
In progress and history
isDepositRolloverOpen(status) tells whether a deposit's rollover can still change:
| Status | Tab |
|---|---|
pending, credit_pending | in progress |
| any status the SDK does not know yet | in progress: the wallet has not said it is settled |
not_required, completed, waived, exhausted, credit_failed, credit_reversed | history |
import { isDepositRolloverOpen } from '@getenginex/sdk'
const open = deposits.filter((d) => isDepositRolloverOpen(d.status))
const history = deposits.filter((d) => !isDepositRolloverOpen(d.status))Both lists keep the gateway's order (newest first). The status label is the app's: write a default label for a status you do not know (e.g. "under review").
Progress per deposit
depositRolloverCoveredPerMille(deposit) gives how much of the requirement is covered (wagered or waived), per mille, from 0 to 1000. It is computed with BigInt and floored, so the bar is only full when nothing remains. It returns null when nothing is required (requiredAmount is 0): do not draw a bar. More wagered than required gives 1000, not an overflowing bar; a remainingAmount above the requirement gives 0.
import { depositRolloverCoveredPerMille, formatMoney } from '@getenginex/sdk'
const { currency } = await enginex.config.get()
for (const deposit of open) {
const share = depositRolloverCoveredPerMille(deposit)
renderDeposit({
credited: formatMoney(deposit.creditedAmount, currency, 'pt-BR'),
remaining: formatMoney(deposit.remainingAmount, currency, 'pt-BR'),
bar: share === null ? undefined : { value: share, max: 1000 },
})
}The amounts are already numbers in minor units: an amount the gateway sends malformed or beyond number precision rejects the whole read with VALIDATION_ERROR (also in validation: 'warn'), never a page of zeros. Show the error with a "try again" button. createdAt and closedAt are ISO 8601 strings and may be missing: check them before formatting.
With TanStack Query
A "load more" list is an infinite query. Spell out the read discipline in the options, since the defaults retry, refetch on focus and keep the pages cached:
import { useInfiniteQuery } from '@tanstack/react-query'
import { mergeDepositRolloverPages, nextUnseenCursor, type DepositRollover } from '@getenginex/sdk'
import { useEnginex, useSession } from '@getenginex/sdk-react'
const PAGE_SIZE = 20
function useDepositRolloverList() {
const enginex = useEnginex()
const session = useSession()
const query = useInfiniteQuery({
queryKey: ['deposit-rollover-list', session.userId, PAGE_SIZE],
queryFn: ({ pageParam, signal }) =>
enginex.wallet.getDepositRollover({ pageSize: PAGE_SIZE, cursor: pageParam }, { signal }),
initialPageParam: undefined as string | undefined,
getNextPageParam: (last: DepositRollover, _pages, _param, pageParams) =>
nextUnseenCursor(last.nextCursor, pageParams),
enabled: session.status === 'authenticated',
// Served under a row lock on the player's wallet: read on open and on request only.
staleTime: 0,
gcTime: 0,
refetchInterval: false,
refetchOnWindowFocus: false,
refetchOnReconnect: false,
retry: false,
})
return { ...query, deposits: mergeDepositRolloverPages(query.data?.pages ?? []) }
}gcTime: 0drops the pages as soon as the screen unmounts. A stale infinite query refetches every cached page when it comes back, so a player who loaded five pages would cost five locked reads on return.- The key is the app's, outside
['enginex', 'user', userId, 'wallet']. The SDK's deposit and withdrawal mutations leave the rollover alone (see below), but other code invalidates that whole prefix: the balance resync ofuseRealtimeSyncafter a reconnection, the iGaming and Predictions writes that move the balance, or your ownuseUserKey('wallet')refresh. Under it, each of those would refetch every loaded page while the screen is open. WithgcTime: 0nothing of the player is left in the cache after the screen closes. - "Load more" is
fetchNextPage()whilehasNextPage; "try again" isrefetch().
For the summary alone (one read, no list), q.wallet.getDepositRollover({ pageSize: 1 }) from @getenginex/sdk/query works with useQuery, with the same options. Its key is under the wallet prefix, so the invalidations listed above still reach it while it is mounted; give it an app key too if the screen stays open across reconnections.
After a deposit or a withdrawal
The SDK's deposit and withdrawal mutations (m.deposits.createPix, m.withdrawals.request, confirmOtp and cancel) invalidate wallet.get, wallet.getBalance, wallet.listTransactions and their own lists, notwallet.getDepositRollover: a deposit or a withdrawal does not re-read the rollover on its own, even with the rollover screen open. If the screen should show the change, offer a "refresh" button that calls refetch().
Testing
The /testing mock has no pending rollover: zeroed totals and a settled history (the statement's deposit, plus each deposit confirmed with markDepositPaid, newest first, as not_required), cursor-paginated like the gateway (limit outside 1 to 100 or an unknown cursor answer INVALID_ARGUMENT). To show deposits in progress, override GET /api/v1/deposit-rollover in routes; the response is in the gateway's format (snake_case, amounts in minor units as text):
import { createMockFetch, ok } from '@getenginex/sdk/testing'
const fetch = createMockFetch({
routes: {
'GET /api/v1/deposit-rollover': () =>
ok({
summary: {
currency: 'BRL',
required_amount: '10000',
wagered_amount: '7500',
waived_amount: '0',
remaining_amount: '2500',
pending_deposits: 1,
unresolved_deposit: false,
},
deposits: [
{
deposit_id: 'd-1',
credited_amount: '5000',
multiplier: '2',
required_amount: '10000',
wagered_amount: '7500',
waived_amount: '0',
remaining_amount: '2500',
status: 'pending',
created_at: '2026-11-10T15:00:00Z',
},
],
oldest_pending: [],
next_cursor: '',
}),
},
})