Rollover de depósito
Um depósito pode ter rollover: parte do saldo real só pode ser sacada depois que o jogador aposta um múltiplo do depósito. wallet.getDepositRollover() (GET /deposit-rollover) responde com os totais (summary), o histórico de depósitos (deposits, do mais novo ao mais antigo, paginado por cursor) e o depósito que a carteira consome primeiro (oldestPending). Esta página monta a tela que lista o rollover depósito a depósito: uma aba "em andamento", uma aba "histórico", uma barra de progresso por depósito e um botão "carregar mais".
Só para o valor sacável, wallet.getBalance() basta (withdrawableBalance, depositRolloverRemaining; veja Saque).
Nunca faça polling desta leitura
A carteira atende GET /deposit-rollover com um lock de linha na carteira do jogador: enquanto ela roda, as apostas, os prêmios e os saques desse jogador esperam. Leia quando a tela abre e quando o jogador pede ("carregar mais", "tentar de novo"), e só:
- sem polling (
refetchInterval,setInterval); - sem refetch ao focar a janela nem ao reconectar;
- sem retry automático (
retry: false; o próprio SDK nunca a repete); - sem recarregar por mensagem de realtime: um
balance_updatenão é motivo para ler o rollover de novo.
Lendo as páginas
Peça uma página com pageSize (1 a 100, padrão do gateway 25) e passe o nextCursor recebido como cursor para a próxima. Duas coisas podem dar errado entre as leituras, e o SDK tem um helper para cada uma:
- um depósito novo desloca a lista, e um depósito já mostrado volta na página seguinte:
mergeDepositRolloverPagesmantém a primeira cópia (e toda linha semdepositId, que não tem pelo que ser comparada); - o gateway devolve um cursor já usado:
nextUnseenCursorretornaundefined, e a paginação para em vez de ler as mesmas páginas para sempre.
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 o summary da primeira página: os totais não dependem do cursor. Dê às linhas sem depositId uma chave sua (por exemplo, o índice) ao renderizar uma lista.
Em andamento e histórico
isDepositRolloverOpen(status) diz se o rollover de um depósito ainda pode mudar:
| Status | Aba |
|---|---|
pending, credit_pending | em andamento |
| qualquer status que o SDK ainda não conhece | em andamento: a carteira não disse que está encerrado |
not_required, completed, waived, exhausted, credit_failed, credit_reversed | histórico |
import { isDepositRolloverOpen } from '@getenginex/sdk'
const open = deposits.filter((d) => isDepositRolloverOpen(d.status))
const history = deposits.filter((d) => !isDepositRolloverOpen(d.status))As duas listas mantêm a ordem do gateway (do mais novo ao mais antigo). O rótulo do status é do app: escreva um rótulo padrão para um status que você não conhece (por exemplo, "em análise").
Progresso por depósito
depositRolloverCoveredPerMille(deposit) dá quanto do requisito está coberto (apostado ou dispensado), por mil, de 0 a 1000. É calculado com BigInt e arredondado para baixo, então a barra só fica cheia quando não falta nada. Retorna null quando nada é exigido (requiredAmount é 0): não desenhe barra. Apostar mais do que o exigido dá 1000, não uma barra estourada; um remainingAmount acima do requisito dá 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 },
})
}Os valores já são números em unidades menores: um valor que o gateway manda malformado ou além da precisão de number rejeita a leitura inteira com VALIDATION_ERROR (também em validation: 'warn'), nunca uma página de zeros. Mostre o erro com um botão "tentar de novo". createdAt e closedAt são strings ISO 8601 e podem faltar: confira antes de formatar.
Com TanStack Query
Uma lista com "carregar mais" é uma infinite query. Deixe a disciplina de leitura explícita nas opções, porque os padrões repetem a leitura, recarregam ao focar e guardam as páginas em cache:
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: 0descarta as páginas assim que a tela desmonta. Uma infinite query velha recarrega todas as páginas em cache quando volta, então um jogador que carregou cinco páginas custaria cinco leituras com lock na volta.- A chave é do app, fora de
['enginex', 'user', userId, 'wallet']. As mutations de depósito e saque do SDK não mexem no rollover (veja abaixo), mas outros códigos invalidam esse prefixo inteiro: o resync de saldo douseRealtimeSyncdepois de uma reconexão, as escritas de iGaming e Predictions que movem o saldo, ou o seu próprio refresh comuseUserKey('wallet'). Debaixo dele, cada um recarregaria todas as páginas carregadas com a tela aberta. ComgcTime: 0, nada do jogador fica no cache depois que a tela fecha. - "Carregar mais" é
fetchNextPage()enquantohasNextPage; "tentar de novo" érefetch().
Só para o resumo (uma leitura, sem lista), q.wallet.getDepositRollover({ pageSize: 1 }) de @getenginex/sdk/query funciona com useQuery, com as mesmas opções. A chave dele fica sob o prefixo wallet, então as invalidações listadas acima ainda o alcançam enquanto está montado; dê a ele uma chave do app também se a tela fica aberta através de reconexões.
Depois de um depósito ou saque
As mutations de depósito e saque do SDK (m.deposits.createPix, m.withdrawals.request, confirmOtp e cancel) invalidam wallet.get, wallet.getBalance, wallet.listTransactions e as próprias listas, nãowallet.getDepositRollover: um depósito ou saque não relê o rollover sozinho, nem com a tela de rollover aberta. Se a tela deve mostrar a mudança, ofereça um botão "atualizar" que chama refetch().
Testes
O mock de /testing não tem rollover pendente: totais zerados e um histórico encerrado (o depósito do extrato, mais cada depósito confirmado com markDepositPaid, do mais novo ao mais antigo, como not_required), paginado por cursor como o gateway (limit fora de 1 a 100 ou um cursor desconhecido respondem INVALID_ARGUMENT). Para mostrar depósitos em andamento, sobrescreva GET /api/v1/deposit-rollover em routes; a resposta vai no formato do gateway (snake_case, valores em unidades menores como texto):
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: '',
}),
},
})