Skip to main content

​
Overview

Paginator<T> is an async-iterable class returned by all collection methods on the Agent class (transactions, executions, logs, rewards). It provides three ways to consume paginated API results:
  1. Async iteration with for await...of — automatically pages through all results.
  2. .first(count) — fetch the first N items as an array.
  3. .page(num, opts) — fetch a specific page with metadata.
You never construct a Paginator directly. It is returned by agent methods like agent.transactions(), agent.executions(), agent.rewards(), and others. 
import { Giza, Chain } from '@gizatech/agent-sdk';

const giza = new Giza({ chain: Chain.BASE });
const agent = giza.agent('0xYourSmartAccountAddress');

// Each of these returns a Paginator instance
const txPaginator = agent.transactions();
const execPaginator = agent.executions();
const logPaginator = agent.logs();
const rewardPaginator = agent.rewards();

​
Usage Patterns

​
Pattern 1: Async Iteration

The paginator implements AsyncIterable<T>, so you can use for await...of to iterate over all items across all pages. The paginator automatically fetches subsequent pages as needed. 
for await (const tx of agent.transactions()) {
  console.log(tx.action, tx.amount);
}
Async iteration fetches all pages sequentially. For large datasets, consider using .first() or .page() to limit the amount of data retrieved.

​
Pattern 2: First N Items

Use .first(count) to get an array of the first N items. This fetches only the pages needed to fulfill the request. 
import { SortOrder } from '@gizatech/agent-sdk';

const recent = await agent.transactions({
  sort: SortOrder.DATE_DESC,
}).first(5);

for (const tx of recent) {
  console.log(`${tx.date}: ${tx.action} ${tx.amount} ${tx.token_type}`);
}
When called without an argument, .first() returns the first page of items using the configured page size. 
// Returns up to 20 items (default page size)
const firstPage = await agent.transactions().first();

​
Pattern 3: Specific Page

Use .page(num, opts) to fetch a specific page and get pagination metadata alongside the items. 
const page2 = await agent.transactions().page(2, { limit: 25 });

console.log(`Page ${page2.page} of ${Math.ceil(page2.total / page2.limit)}`);
console.log(`Total items: ${page2.total}`);
console.log(`Has more: ${page2.hasMore}`);

for (const tx of page2.items) {
  console.log(tx.transaction_hash);
}

​
Class Reference

​
Paginator<T>

class Paginator<T> implements AsyncIterable<T> {
  async *[Symbol.asyncIterator](): AsyncIterableIterator<T>;
  async page(num: number, opts?: { limit?: number }): Promise<PaginatedResponse<T>>;
  async first(count?: number): Promise<T[]>;
}

​
Symbol.asyncIterator

Enables for await...of iteration. Automatically fetches pages until all items have been yielded. Returns: AsyncIterableIterator<T>

​
page()

Fetch a specific page of results with pagination metadata.
​
num
number
required
The 1-based page number to fetch.
​
opts
{ limit?: number }
Optional override for the page size.
​
opts.limit
number
Number of items per page. Defaults to the limit configured when the paginator was created (typically 20).
Returns: Promise<PaginatedResponse<T>>

​
first()

Fetch the first N items as an array.
​
count
number
Number of items to return. When omitted, returns the first page using the configured page size.
Returns: Promise<T[]>

​
PaginatedResponse<T>

The response object returned by .page(). 
interface PaginatedResponse<T> {
  items: T[];
  total: number;
  page: number;
  limit: number;
  hasMore: boolean;
}
FieldTypeDescription
itemsT[]The items on this page
totalnumberTotal number of items across all pages
pagenumberCurrent page number (1-based)
limitnumberItems per page
hasMorebooleanWhether there are more pages after this one

​
PageFetcher<T>

The internal type for the function that fetches a page of results. This is used internally by the SDK and is not needed for normal usage. 
type PageFetcher<T> = (
  page: number,
  limit: number,
) => Promise<PaginatedResponse<T>>;

​
Methods That Return Paginators

The following Agent methods return Paginator instances:
MethodItem TypeReference
agent.transactions()TransactionTransactions
agent.executions()ExecutionWithTransactionsDTOTransactions
agent.executionLogs(id)LogDTOTransactions
agent.logs()LogDTOTransactions
agent.rewards()RewardDTORewards
agent.rewardHistory()RewardDTORewards
All accept an optional PaginationOptions parameter: 
interface PaginationOptions {
  limit?: number;
  sort?: string;
}

​
Building a Paginated UI

This example shows how to use .page() to build a paginated list with navigation. 
import { Giza, Chain, SortOrder } from '@gizatech/agent-sdk';

const giza = new Giza({ chain: Chain.BASE });
const agent = giza.agent('0xYourSmartAccountAddress');

const PAGE_SIZE = 10;
let currentPage = 1;

async function loadPage(pageNum: number) {
  const result = await agent.transactions({
    sort: SortOrder.DATE_DESC,
  }).page(pageNum, { limit: PAGE_SIZE });

  const totalPages = Math.ceil(result.total / result.limit);

  return {
    items: result.items,
    page: result.page,
    totalPages,
    total: result.total,
    hasNext: result.hasMore,
    hasPrev: result.page > 1,
  };
}

// Load first page
const page1 = await loadPage(1);
console.log(`Showing page ${page1.page} of ${page1.totalPages}`);
console.log(`${page1.total} total transactions`);

// Load next page
if (page1.hasNext) {
  const page2 = await loadPage(2);
  console.log(`Showing page ${page2.page} of ${page2.totalPages}`);
}