Pagination

List APIs support two models.

Offset pagination

Use page and page_size for human-facing screens that need navigation and a total count. The default page is 1, default size is 20, and maximum size is 100.

?page=1&page_size=20

Cursor pagination

Use after_id and limit for backend synchronization. Results are ordered by ID ascending. Supplying after_id selects cursor mode and ignores offset parameters.

{ "items": [], "next_cursor": 145, "has_more": false }

Cursor mode is supported by deposits, withdrawals, and account ledger. Deposit cursors require an explicit type=EXTERNAL or type=INTERNAL because the two sources have different ID sequences.

Store all returned items before advancing the cursor. Keep independent cursors for each resource, account, and filter combination. has_more is advisory; when a full batch is returned, request once more to confirm an empty result.

Cursor checkpoint key and crashes

A checkpoint key includes environment, client, resource, account where applicable, deposit type, asset filter, and every filter that changes the result set.

• Crash before item commit: replay the same cursor.
• Crash after item commit but before cursor commit: replay safely through idempotent upserts.
• Empty response: retain the requested cursor.
• Exactly limit items: query again even when the stream appears finished.

Offset pages are not safe checkpoints because concurrent inserts can move records between pages.