Pagination - Gero Nexus Documentation

Many Gero Nexus API endpoints return lists of items that can be paginated. This guide explains how to work with paginated responses efficiently.

Pagination Parameters

Endpoints that return lists support the following query parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number (1-indexed)
`count`	integer	20	Items per page (max: 100)
`order`	string	`desc`	Sort order: `asc` or `desc`

Some endpoints use offset and limit instead of page and count. Check the specific endpoint documentation for details.

Request Examples

Basic Pagination

# Get page 1 with 20 items (default)
curl "https://nexus-dev.gerowallet.io/api/blocks" \
  -H "Authorization: Bearer your-token"

# Get page 3 with 50 items
curl "https://nexus-dev.gerowallet.io/api/blocks?page=3&count=50" \
  -H "Authorization: Bearer your-token"

With Sorting

# Get transactions in ascending order (oldest first)
curl "https://nexus-dev.gerowallet.io/api/addresses/addr1.../transactions?order=asc" \
  -H "Authorization: Bearer your-token"

Response Headers

Every paginated response includes headers with pagination metadata:

HTTP/1.1 200 OK
X-Total-Count: 15847
X-Page: 1
X-Page-Size: 20
X-Total-Pages: 793

Header	Description
`X-Total-Count`	Total number of items across all pages
`X-Page`	Current page number
`X-Page-Size`	Number of items per page
`X-Total-Pages`	Total number of pages

Pagination Examples

JavaScript/TypeScript

class PaginatedFetcher {
  constructor(baseUrl, accessToken) {
    this.baseUrl = baseUrl;
    this.accessToken = accessToken;
  }

  async fetchPage(endpoint, page = 1, count = 20) {
    const url = new URL(`${this.baseUrl}${endpoint}`);
    url.searchParams.set('page', page);
    url.searchParams.set('count', count);

    const response = await fetch(url, {
      headers: {
        'Authorization': `Bearer ${this.accessToken}`
      }
    });

    const data = await response.json();

    return {
      data,
      pagination: {
        page: parseInt(response.headers.get('X-Page')),
        pageSize: parseInt(response.headers.get('X-Page-Size')),
        totalCount: parseInt(response.headers.get('X-Total-Count')),
        totalPages: parseInt(response.headers.get('X-Total-Pages'))
      }
    };
  }

  async fetchAll(endpoint, count = 100) {
    const allItems = [];
    let page = 1;
    let hasMore = true;

    while (hasMore) {
      const { data, pagination } = await this.fetchPage(endpoint, page, count);
      allItems.push(...data);

      hasMore = page < pagination.totalPages;
      page++;

      // Respect rate limits
      if (hasMore) {
        await new Promise(r => setTimeout(r, 100));
      }
    }

    return allItems;
  }
}

// Usage
const fetcher = new PaginatedFetcher(
  'https://nexus-dev.gerowallet.io',
  accessToken
);

// Fetch single page
const { data, pagination } = await fetcher.fetchPage('/api/blocks', 1, 50);
console.log(`Page ${pagination.page} of ${pagination.totalPages}`);
console.log(`Showing ${data.length} of ${pagination.totalCount} blocks`);

// Fetch all items (use carefully for large datasets)
const allBlocks = await fetcher.fetchAll('/api/blocks');
console.log(`Fetched ${allBlocks.length} blocks total`);

Python

import requests
from typing import List, Dict, Any, Optional
from dataclasses import dataclass
import time

@dataclass
class PaginationInfo:
    page: int
    page_size: int
    total_count: int
    total_pages: int

@dataclass
class PaginatedResponse:
    data: List[Dict[str, Any]]
    pagination: PaginationInfo


class PaginatedFetcher:
    def __init__(self, base_url: str, access_token: str):
        self.base_url = base_url
        self.session = requests.Session()
        self.session.headers.update({
            'Authorization': f'Bearer {access_token}'
        })

    def fetch_page(self, endpoint: str, page: int = 1,
                   count: int = 20) -> PaginatedResponse:
        """Fetch a single page of results"""
        response = self.session.get(
            f'{self.base_url}{endpoint}',
            params={'page': page, 'count': count}
        )
        response.raise_for_status()

        pagination = PaginationInfo(
            page=int(response.headers.get('X-Page', 1)),
            page_size=int(response.headers.get('X-Page-Size', count)),
            total_count=int(response.headers.get('X-Total-Count', 0)),
            total_pages=int(response.headers.get('X-Total-Pages', 1))
        )

        return PaginatedResponse(
            data=response.json(),
            pagination=pagination
        )

    def fetch_all(self, endpoint: str, count: int = 100,
                  max_pages: Optional[int] = None) -> List[Dict[str, Any]]:
        """Fetch all pages of results"""
        all_items = []
        page = 1

        while True:
            result = self.fetch_page(endpoint, page, count)
            all_items.extend(result.data)

            if page >= result.pagination.total_pages:
                break
            if max_pages and page >= max_pages:
                break

            page += 1
            time.sleep(0.1)  # Respect rate limits

        return all_items


# Usage
fetcher = PaginatedFetcher(
    'https://nexus-dev.gerowallet.io',
    access_token
)

# Fetch single page
result = fetcher.fetch_page('/api/blocks', page=1, count=50)
print(f"Page {result.pagination.page} of {result.pagination.total_pages}")
print(f"Showing {len(result.data)} of {result.pagination.total_count} blocks")

# Fetch all items (use carefully)
all_blocks = fetcher.fetch_all('/api/blocks', max_pages=10)
print(f"Fetched {len(all_blocks)} blocks")

Cursor-Based Pagination

Some endpoints use cursor-based pagination for better performance with large datasets:

# First request
curl "https://nexus-dev.gerowallet.io/api/addresses/addr1.../utxos?limit=100" \
  -H "Authorization: Bearer your-token"

# Response includes cursor
# { "data": [...], "cursor": "eyJsYXN0X2lkIjoiYWJjMTIzIn0=" }

# Next request with cursor
curl "https://nexus-dev.gerowallet.io/api/addresses/addr1.../utxos?limit=100&cursor=eyJsYXN0X2lkIjoiYWJjMTIzIn0=" \
  -H "Authorization: Bearer your-token"

Cursor Pagination Parameters

Parameter	Type	Description
`limit`	integer	Number of items to return (max: 100)
`cursor`	string	Cursor from previous response

Cursor Pagination Example

async function* fetchWithCursor(endpoint, limit = 100) {
  let cursor = null;

  while (true) {
    const url = new URL(`https://nexus-dev.gerowallet.io${endpoint}`);
    url.searchParams.set('limit', limit);
    if (cursor) {
      url.searchParams.set('cursor', cursor);
    }

    const response = await fetch(url, {
      headers: { 'Authorization': `Bearer ${accessToken}` }
    });

    const { data, cursor: nextCursor } = await response.json();

    for (const item of data) {
      yield item;
    }

    if (!nextCursor || data.length < limit) {
      break;
    }

    cursor = nextCursor;
    await new Promise(r => setTimeout(r, 100)); // Rate limit
  }
}

// Usage with async iteration
for await (const utxo of fetchWithCursor('/api/addresses/addr1.../utxos')) {
  console.log(utxo);
}

Best Practices

Choose Appropriate Page Size

Use smaller page sizes (20-50) for interactive UIs
Use larger page sizes (100) for batch processing
Consider response time vs. number of requests

// Interactive UI - quick response
const { data } = await fetchPage('/api/transactions', 1, 20);

// Background processing - fewer requests
const allTxs = await fetchAll('/api/transactions', 100);

Handle Empty Pages

Always check if the page contains data before processing:

const { data, pagination } = await fetchPage(endpoint, page);

if (data.length === 0) {
  console.log('No more data');
  return;
}

Respect Rate Limits

Add delays between paginated requests to avoid rate limiting:

for (let page = 1; page <= totalPages; page++) {
  const data = await fetchPage(endpoint, page);
  process(data);

  if (page < totalPages) {
    await delay(100); // 100ms between requests
  }
}

Use Cursor Pagination for Large Datasets

For datasets with millions of items, prefer cursor-based pagination:

More efficient database queries
Consistent results even with concurrent updates
No duplicate or missing items between pages

Cache When Possible

Cache paginated results when the data doesn’t change frequently:

const cacheKey = `${endpoint}:page=${page}:count=${count}`;
const cached = cache.get(cacheKey);

if (cached && !isExpired(cached)) {
  return cached.data;
}

Endpoints Supporting Pagination

The following endpoints support pagination:

Endpoint	Pagination Type
`/api/blocks`	Page-based
`/api/addresses/{address}/transactions`	Page-based
`/api/addresses/{address}/utxos`	Cursor-based
`/api/account/{stakeAddress}/txs`	Page-based
`/api/account/{stakeAddress}/rewards`	Page-based
`/api/pools`	Page-based

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

Documentation Index

​Pagination Parameters

​Request Examples

​Basic Pagination

​With Sorting

​Response Headers

​Pagination Examples

​JavaScript/TypeScript

​Python

​Cursor-Based Pagination

​Cursor Pagination Parameters

​Cursor Pagination Example

​Best Practices

​Endpoints Supporting Pagination

​Next Steps

Rate Limits

Error Handling

Authentication

API Reference

Pagination Parameters

Request Examples

Basic Pagination

With Sorting

Response Headers

Pagination Examples

JavaScript/TypeScript

Python

Cursor-Based Pagination

Cursor Pagination Parameters

Cursor Pagination Example

Best Practices

Endpoints Supporting Pagination

Next Steps