Pagination

Many Gero Nexus endpoints return lists of items in pages. This guide explains the pagination parameters and how to iterate through all results.

Pagination Parameters

List endpoints accept two query parameters:

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (1-based)
`pageSize`	integer	`100`	Items per page (1–100)

A few endpoints use a different default pageSize (for example, address transaction history defaults to 20). The maximum is always 100. Check the endpoint’s page in the API Reference for its exact defaults and any endpoint-specific filters (some endpoints add their own parameters, e.g. DReps accept a sort).

Request Examples

# Page 1 with 100 items (defaults)
curl "https://nexus.gerowallet.io/api/blocks" \
  -H "X-Api-Key: nxs_your_api_key_here"

# Page 3 with 50 items
curl "https://nexus.gerowallet.io/api/blocks?page=3&pageSize=50" \
  -H "X-Api-Key: nxs_your_api_key_here"

Detecting the Last Page

Paginated endpoints come in two response shapes — check the endpoint’s API Reference page for which it uses. Neither sends pagination-metadata response headers. Bare array (e.g. /api/blocks, /api/addresses/{address}/utxos). No metadata in the body — keep requesting pages until you receive fewer items than your pageSize (or an empty array). That page is the last one.

HTTP/1.1 200 OK
Content-Type: application/json

[ { ... }, { ... }, ... ]

Wrapper object (e.g. /api/addresses/{address}/transactions/history). Items are nested under a key, alongside a pagination block — stop when pagination.hasNext is false.

HTTP/1.1 200 OK
Content-Type: application/json

{ "transactions": [ ... ], "pagination": { "page": 1, "pageSize": 20, "totalItems": 25, "totalPages": 2, "hasNext": true, "hasPrevious": false } }

Iterating Through All Pages

The helpers below are for bare-array endpoints (they stop on a short page). For a wrapper endpoint, loop while pagination.hasNext is true — see the wrapper example below.

Bare-array endpoints — JavaScript/TypeScript

async function fetchAll(endpoint, pageSize = 100) {
  const items = [];
  let page = 1;

  while (true) {
    const url = new URL(`https://nexus.gerowallet.io${endpoint}`);
    url.searchParams.set('page', page);
    url.searchParams.set('pageSize', pageSize);

    const response = await fetch(url, {
      headers: { 'X-Api-Key': process.env.NEXUS_API_KEY }
    });
    if (!response.ok) throw new Error(`HTTP ${response.status}`);

    const batch = await response.json();
    items.push(...batch);

    // Short (or empty) page → we've reached the end.
    if (batch.length < pageSize) break;

    page++;
    await new Promise((r) => setTimeout(r, 100)); // be gentle on rate limits
  }

  return items;
}

const allBlocks = await fetchAll('/api/blocks');
console.log(`Fetched ${allBlocks.length} blocks`);

Bare-array endpoints — Python

import os
import time
import requests

BASE = 'https://nexus.gerowallet.io'
HEADERS = {'X-Api-Key': os.environ['NEXUS_API_KEY']}


def fetch_all(endpoint, page_size=100):
    items = []
    page = 1

    while True:
        response = requests.get(
            f'{BASE}{endpoint}',
            params={'page': page, 'pageSize': page_size},
            headers=HEADERS,
        )
        response.raise_for_status()

        batch = response.json()
        items.extend(batch)

        # Short (or empty) page → end of results.
        if len(batch) < page_size:
            break

        page += 1
        time.sleep(0.1)  # be gentle on rate limits

    return items


all_blocks = fetch_all('/api/blocks')
print(f'Fetched {len(all_blocks)} blocks')

Wrapper endpoints

For a { items, pagination } endpoint, loop while pagination.hasNext:

async function fetchAllWrapped(endpoint, itemsKey, pageSize = 100) {
  const items = [];
  let page = 1;

  while (true) {
    const url = new URL(`https://nexus.gerowallet.io${endpoint}`);
    url.searchParams.set('page', page);
    url.searchParams.set('pageSize', pageSize);

    const res = await fetch(url, { headers: { 'X-Api-Key': process.env.NEXUS_API_KEY } });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);

    const body = await res.json();
    items.push(...body[itemsKey]);

    if (!body.pagination || !body.pagination.hasNext) break;
    page++;
  }

  return items;
}

// e.g. transaction history:
// await fetchAllWrapped('/api/addresses/<addr>/transactions/history', 'transactions');

Best Practices

Choose an appropriate page size

Use smaller pages (20–50) for interactive UIs that need a fast first response
Use the maximum (100) for batch processing to minimize round trips

Respect rate limits

Add a small delay between page requests so a deep backfill doesn’t trip the per-second limit. See Rate Limits.

Cache when possible

Cache slow-changing paginated data (block, tx, and asset metadata) to cut request volume against your monthly quota.

Endpoints Supporting Pagination

A representative (non-exhaustive) set of page/pageSize endpoints and their response shape:

Endpoint	Default `pageSize`	Response shape
`/api/blocks`	100	bare array
`/api/addresses/{address}/utxos`	100	bare array
`/api/addresses/{address}/transactions/history`	20	`{ transactions, pagination }` wrapper

Not every list endpoint paginates this way. Some return the full set in one response (e.g. /api/pools), and some use a different cursor instead of page/pageSize (e.g. /api/account/{stakeAddress}/txs takes a required from block-height parameter). Always check the endpoint’s API Reference page for its exact parameters and response shape.

Next Steps

Rate Limits

Understand rate limiting and quotas

Error Handling

Learn how to handle API errors

Authentication

Learn about API authentication

API Reference

Explore all available endpoints

Getting Started

Core Concepts

Add-ons & Streaming

API Reference

Request Examples

Detecting the Last Page

Iterating Through All Pages

Bare-array endpoints — JavaScript/TypeScript

Bare-array endpoints — Python

Wrapper endpoints

Best Practices

Next Steps

Rate Limits

Error Handling

Authentication

API Reference

​Pagination Parameters

​Request Examples

​Detecting the Last Page

​Iterating Through All Pages

​Bare-array endpoints — JavaScript/TypeScript

​Bare-array endpoints — Python

​Wrapper endpoints

​Best Practices

​Endpoints Supporting Pagination

​Next Steps

Rate Limits

Error Handling

Authentication

API Reference

Pagination Parameters

Request Examples

Detecting the Last Page

Iterating Through All Pages

Bare-array endpoints — JavaScript/TypeScript

Bare-array endpoints — Python

Wrapper endpoints

Best Practices

Endpoints Supporting Pagination

Next Steps