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/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/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.

Completeness on holdings

For token-holdings, treat the result as complete only when exact=true, truncated=false, and completeness.reasonCode="complete". Otherwise keep paging or narrow the query.