Pagination and cursors

List endpoints return an items array and, when more rows exist, a nextCursor.

The one rule

Treat nextCursor as opaque. Pass the value back unchanged to fetch the next page — but URL-encode it when placing it in the query string, since cursors can contain reserved characters (for example :). Never parse, construct, or mutate a cursor: the internal format differs across endpoints and can change without notice. Stop when nextCursor is absent or null.

# first page
curl -H "X-Starkscan-Api-Key: $STARKSCAN_API_KEY" \
  "${STARKSCAN_BASE_URL:-https://api.starkscan.co}/v1/SN_MAIN/address/<address>/transactions?limit=25"

# next page: take nextCursor from the previous response and URL-encode it
# (it is opaque and may contain reserved characters such as : or +)
cursor="$(printf '%s' "$NEXT_CURSOR" | jq -sRr @uri)"
curl -H "X-Starkscan-Api-Key: $STARKSCAN_API_KEY" \
  "${STARKSCAN_BASE_URL:-https://api.starkscan.co}/v1/SN_MAIN/address/<address>/transactions?limit=25&cursor=$cursor"

limit

limit caps how many rows a single response returns. Keep it modest on hosted APIs and page with nextCursor rather than requesting very large pages.

Coverage on wallet-asset discovery

assets/discovery uses a version-pinned cursor so a full walk never silently mixes two candidate universes. Keep the same snapshotId and scope on every page and follow nextCursor until it is null. If the discovery generation or reviewed registry changes during the walk, discard the partial result and restart from the first page. The authenticated walk expires five minutes after its first page so a stale snapshot cannot accumulate unbounded tail work. Finish the walk within that window; after a 400 invalid_cursor, restart without a cursor.

Discovery coverage is not balance correctness. coverage.completeWithinScope describes only the selected evidence scope, while globallyComplete=false and mayMissNonstandardUnregisteredAssets=true preserve the wider limitation. Call query/wallet-state to verify a bounded candidate page at one immutable block hash; do not treat discovery order or evidence as a balance.

Wallet-state valuation is also page-scoped. A page returns valuation.scope="page", and its subtotal/counters cover only that page. valuation.singlePageComplete is true only when the discovery walk's first page is also terminal; caller-supplied scope="explicit" subsets always set it false. Raw completeForWallet is its deprecated compatibility alias, not a wallet-wide guarantee. Stop only when hasMore=false or nextCursor=null. For a complete selected-scope portfolio, prefer the TypeScript SDK's walletStateComplete() helper; it pins continuations to the first block hash and aggregates only after reaching nextCursor=null.

Within one snapshot, curated known tokens appear before unknown tokens. Ordering is deterministic, and token-provided names and symbols do not confer known-token rank.