Pular para o conteúdo

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_update nã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: mergeDepositRolloverPages mantém a primeira cópia (e toda linha sem depositId, que não tem pelo que ser comparada);
  • o gateway devolve um cursor já usado: nextUnseenCursor retorna undefined, e a paginação para em vez de ler as mesmas páginas para sempre.
ts
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:

StatusAba
pending, credit_pendingem andamento
qualquer status que o SDK ainda não conheceem andamento: a carteira não disse que está encerrado
not_required, completed, waived, exhausted, credit_failed, credit_reversedhistórico
ts
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.

ts
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:

tsx
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: 0 descarta 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 do useRealtimeSync depois de uma reconexão, as escritas de iGaming e Predictions que movem o saldo, ou o seu próprio refresh com useUserKey('wallet'). Debaixo dele, cada um recarregaria todas as páginas carregadas com a tela aberta. Com gcTime: 0, nada do jogador fica no cache depois que a tela fecha.
  • "Carregar mais" é fetchNextPage() enquanto hasNextPage; "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):

ts
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: '',
      }),
  },
})