Rollover de depósito
Un depósito puede tener rollover: parte del saldo real solo se puede retirar después de que el jugador apuesta un múltiplo del depósito. wallet.getDepositRollover() (GET /deposit-rollover) responde con los totales (summary), el historial de depósitos (deposits, del más nuevo al más antiguo, paginado por cursor) y el depósito que la billetera consume primero (oldestPending). Esta página arma la pantalla que lista el rollover depósito por depósito: una pestaña "en curso", una pestaña "historial", una barra de progreso por depósito y un botón "cargar más".
Solo para el monto retirable, wallet.getBalance() alcanza (withdrawableBalance, depositRolloverRemaining; ver Retiro).
Nunca hagas polling de esta lectura
La billetera atiende GET /deposit-rollover con un lock de fila en la billetera del jugador: mientras corre, las apuestas, los premios y los retiros de ese jugador esperan. Léela cuando se abre la pantalla y cuando el jugador lo pide ("cargar más", "reintentar"), y nada más:
- sin polling (
refetchInterval,setInterval); - sin refetch al enfocar la ventana ni al reconectar;
- sin reintento automático (
retry: false; el propio SDK nunca la repite); - sin recargar por un mensaje de realtime: un
balance_updateno es motivo para leer el rollover de nuevo.
Leer las páginas
Pide una página con pageSize (1 a 100, por defecto del gateway 25) y pasa el nextCursor recibido como cursor para la siguiente. Dos cosas pueden salir mal entre lecturas, y el SDK tiene un helper para cada una:
- un depósito nuevo desplaza la lista, y un depósito ya mostrado vuelve en la página siguiente:
mergeDepositRolloverPagesconserva su primera copia (y toda fila sindepositId, que no tiene con qué compararse); - el gateway devuelve un cursor ya usado:
nextUnseenCursordevuelveundefined, y la paginación se detiene en lugar de leer las mismas páginas para siempre.
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,
})
}Usa el summary de la primera página: los totales no dependen del cursor. Dale a las filas sin depositId una clave propia (por ejemplo, el índice) al renderizar una lista.
En curso e historial
isDepositRolloverOpen(status) indica si el rollover de un depósito todavía puede cambiar:
| Estado | Pestaña |
|---|---|
pending, credit_pending | en curso |
| cualquier estado que el SDK todavía no conoce | en curso: la billetera no dijo que esté cerrado |
not_required, completed, waived, exhausted, credit_failed, credit_reversed | historial |
import { isDepositRolloverOpen } from '@getenginex/sdk'
const open = deposits.filter((d) => isDepositRolloverOpen(d.status))
const history = deposits.filter((d) => !isDepositRolloverOpen(d.status))Las dos listas mantienen el orden del gateway (del más nuevo al más antiguo). La etiqueta del estado es de la app: escribe una etiqueta por defecto para un estado que no conoces (por ejemplo, "en revisión").
Progreso por depósito
depositRolloverCoveredPerMille(deposit) da cuánto del requisito está cubierto (apostado o dispensado), por mil, de 0 a 1000. Se calcula con BigInt y se redondea hacia abajo, así que la barra solo se llena cuando no falta nada. Devuelve null cuando no se exige nada (requiredAmount es 0): no dibujes barra. Apostar más de lo exigido da 1000, no una barra desbordada; un remainingAmount por encima del requisito da 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 },
})
}Los montos ya son números en unidades menores: un monto que el gateway envía malformado o más allá de la precisión de number rechaza la lectura entera con VALIDATION_ERROR (también en validation: 'warn'), nunca una página de ceros. Muestra el error con un botón "reintentar". createdAt y closedAt son strings ISO 8601 y pueden faltar: compruébalos antes de formatear.
Con TanStack Query
Una lista con "cargar más" es una infinite query. Deja explícita la disciplina de lectura en las opciones, porque los valores por defecto reintentan, recargan al enfocar y guardan las páginas en caché:
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 las páginas en cuanto la pantalla se desmonta. Una infinite query vieja recarga todas las páginas en caché cuando vuelve, así que un jugador que cargó cinco páginas costaría cinco lecturas con lock al volver.- La clave es de la app, fuera de
['enginex', 'user', userId, 'wallet']. Las mutations de depósito y retiro del SDK no tocan el rollover (ver abajo), pero otro código invalida ese prefijo entero: el resync de saldo deuseRealtimeSynctras una reconexión, las escrituras de iGaming y Predictions que mueven el saldo, o tu propio refresh conuseUserKey('wallet'). Debajo de él, cada uno recargaría todas las páginas cargadas con la pantalla abierta. CongcTime: 0, nada del jugador queda en caché después de cerrar la pantalla. - "Cargar más" es
fetchNextPage()mientrashasNextPage; "reintentar" esrefetch().
Solo para el resumen (una lectura, sin lista), q.wallet.getDepositRollover({ pageSize: 1 }) de @getenginex/sdk/query funciona con useQuery, con las mismas opciones. Su clave está bajo el prefijo wallet, así que las invalidaciones listadas arriba todavía lo alcanzan mientras está montado; dale también una clave de la app si la pantalla sigue abierta a través de reconexiones.
Después de un depósito o un retiro
Las mutations de depósito y retiro del SDK (m.deposits.createPix, m.withdrawals.request, confirmOtp y cancel) invalidan wallet.get, wallet.getBalance, wallet.listTransactions y sus propias listas, nowallet.getDepositRollover: un depósito o un retiro no relee el rollover por sí solo, ni con la pantalla de rollover abierta. Si la pantalla debe mostrar el cambio, ofrece un botón "actualizar" que llame a refetch().
Pruebas
El mock de /testing no tiene rollover pendiente: totales en cero y un historial cerrado (el depósito del extracto, más cada depósito confirmado con markDepositPaid, del más nuevo al más antiguo, como not_required), paginado por cursor como el gateway (limit fuera de 1 a 100 o un cursor desconocido responden INVALID_ARGUMENT). Para mostrar depósitos en curso, sobrescribe GET /api/v1/deposit-rollover en routes; la respuesta va en el formato del gateway (snake_case, montos en 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: '',
}),
},
})