---
url: >-
  https://game-engine-io.github.io/enginex-frontend-sdk/flows/deposit-rollover.md
---
# 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](/flows/withdrawal#bonuses-and-deposit-rollover)).

::: danger 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_update` is not a reason to read the rollover again.
  :::

## Reading the pages {#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:
  `mergeDepositRolloverPages` keeps its first copy (and every row without a `depositId`, which has nothing to
  be matched by);
* the gateway hands back a cursor already used: `nextUnseenCursor` returns `undefined`, so paging stops instead
  of reading the same pages forever.

```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 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 {#open-and-settled}

`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 |

```ts
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 {#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`.

```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 },
  })
}
```

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 {#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:

```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` drops 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 of `useRealtimeSync` after a reconnection, the iGaming and Predictions writes that move the balance,
  or your own `useUserKey('wallet')` refresh. Under it, each of those would refetch every loaded page while the
  screen is open. With `gcTime: 0` nothing of the player is left in the cache after the screen closes.
* "Load more" is `fetchNextPage()` while `hasNextPage`; "try again" is `refetch()`.

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 {#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, **not**
`wallet.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 {#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):

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