Paginating Wallet History Without Missing Records
Build wallet-history pagination around stable ordering, explicit boundaries and deduplication so repeated requests do not lose or duplicate activity.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
Wallet history is usually too large for one response. Pagination must preserve a stable traversal while new transactions arrive. Page numbers alone do not explain which records were included or whether the underlying result changed.
Use an ordered boundary
Choose a deterministic order using chain position and an event-level tie-breaker. A cursor should identify a traversal boundary, not merely encode an offset. If the API permits it, pin the upper block of a historical scan. New head activity can then be fetched separately without moving the historical pages beneath the reader.
Worked example: a shifting first page
A newest-first list returns records 100 through 91. Three new records arrive before the client requests offset ten. The second page now overlaps earlier results and may displace expected records. A pinned range and a cursor after record 91 avoid this moving offset problem; a durable event identity still protects against repeated delivery.
Validate completion explicitly
Test multiple events in one transaction, empty intermediate pages and a cursor reused after a failure. Persist the cursor only after the page is durably processed. Stop according to the documented continuation contract rather than assuming a short page always means the end. Record the scanned range so an apparently empty history cannot conceal an unfinished scan.
A practical acceptance test
Insert new head records between two page requests and repeat the final page once. Assert that a pinned historical scan retains every original event exactly once. Then interrupt processing before the page commit. On restart, the cursor must resume from durable progress rather than from the most recently fetched but uncommitted response.
Questions about the topic
Frequently asked questions
Is a transaction hash enough to deduplicate transfers?
No. A transaction can contain multiple relevant transfer events.
Can page size determine completeness?
Only if the API explicitly guarantees that rule; prefer its documented continuation indicator.
Standards & technical documentation
