The page runs from newer to older
getSignaturesForAddress returns signatures in descending order. Its before cursor moves to records older than a signature. until bounds a scan toward a known signature. Cursors are signatures, not slot numbers, timestamps or row offsets.
A minimal collector
cursor = None
while True:
page = get_signatures(address, before=cursor, limit=1000)
if not page: break
persist_idempotently(page)
cursor = page[-1]["signature"]
save_checkpoint(cursor)This pseudocode places the checkpoint after durable storage. If a process crashes before that point, the next run may repeat a page; a uniqueness constraint makes the overlap harmless. Advancing the cursor first can permanently skip rows.
Define a stopping condition
- For a backfill, choose the target date or historical checkpoint before starting.
- For incremental collection, keep the newest verified signature and scan back until you reach it.
- Persist each signature's slot and error field so later transaction fetches can be reconciled.
- If the old checkpoint cannot be reached within retained history, flag a gap rather than reporting a complete import.
Account for moving history
New transactions arrive while you page backwards. An address can also have many records in one slot, so stopping by slot alone can omit signatures. Rate-limit transaction-detail fetches separately from lightweight signature pages. Reaching an empty page means this endpoint has no more matching results for the query; it does not prove that the address has no earlier history in another source.