Pagination

Navigate large result sets with cursor-based pagination using the SDK or REST API.

Response Format

All list endpoints return a consistent paginated response:

{
  "data": [...],
  "cursor": "eyJpZCI6IndhbF8wMUoifQ==",
  "hasMore": true
}

Field	Type	Description
`data`	`T[]`	Array of results for this page
`cursor`	`string \| null`	Opaque cursor for the next page; `null` when on the last page
`hasMore`	`boolean`	`true` if more results exist beyond this page

Cursors are opaque — do not attempt to parse or construct them. Pass the cursor value exactly as returned.

Manual Pagination

Pass the cursor from one response as the cursor parameter of the next request:

import Wallgent from '@wallgent/sdk'

const wg = new Wallgent({ apiKey: process.env.WALLGENT_API_KEY })

// First page
let page = await wg.wallets.list({ limit: 20 })
console.log(page.data)

// Subsequent pages
while (page.hasMore && page.cursor) {
  page = await wg.wallets.list({ limit: 20, cursor: page.cursor })
  console.log(page.data)
}

Use manual pagination when building UI components that need explicit control over page state (e.g., a "Load more" button or numbered page navigation).

`autoPaginate()`

autoPaginate is an async generator that fetches pages one at a time and yields individual items. It never loads all results into memory at once, making it safe for arbitrarily large datasets.

import Wallgent from '@wallgent/sdk'
import { autoPaginate } from '@wallgent/sdk'

const wg = new Wallgent({ apiKey: process.env.WALLGENT_API_KEY })

for await (const wallet of autoPaginate((cursor) =>
  wg.wallets.list({ cursor, limit: 100 })
)) {
  // Process one wallet at a time
  console.log(wallet.id, wallet.balance)
}

The generator handles fetching the next page automatically as items are consumed. You can break early without fetching pages you do not need.

// Stop after finding the first frozen wallet
for await (const wallet of autoPaginate((cursor) => wg.wallets.list({ cursor }))) {
  if (wallet.status === 'FROZEN') {
    console.log('Found frozen wallet:', wallet.id)
    break
  }
}

`collectAll()`

collectAll is a convenience wrapper around autoPaginate that fetches all pages and returns every result in a single array.

import { collectAll } from '@wallgent/sdk'

const allWallets = await collectAll((cursor) =>
  wg.wallets.list({ cursor, limit: 100 })
)

console.log(`Total wallets: ${allWallets.length}`)

Use collectAll for small-to-medium result sets where you need the full list available at once (e.g., generating a report, building a dropdown). Avoid it for unbounded datasets — it loads everything into memory.

When to Use Each Approach

Approach	Best For
Manual pagination	UI components, "load more" buttons, numbered pages
`autoPaginate()`	Processing large datasets, streaming pipelines, early exit
`collectAll()`	Small-to-medium lists, reports, one-time data exports

Page Size

Pass a limit parameter to control how many results are returned per page. Default is 20; maximum is 100.

// Larger pages mean fewer round-trips but more memory per page
const page = await wg.wallets.list({ limit: 100 })

For autoPaginate and collectAll, use a larger limit (e.g., 100) to reduce the number of API requests and stay within your rate limit budget.

REST API

The same cursor pattern applies when calling the REST API directly:

GET /v1/wallets?limit=20

{
  "data": [...],
  "cursor": "eyJpZCI6IndhbF8wMUoifQ==",
  "hasMore": true
}

GET /v1/wallets?limit=20&cursor=eyJpZCI6IndhbF8wMUoifQ==

URL-encode the cursor value if it contains special characters.

Error Handling

Handle RATE_LIMIT_EXCEEDED when paginating large datasets.

Authentication

Rate limits per plan that affect pagination throughput.