Pagination

Every list endpoint returns one page at a time. You ask for a page size with limit and move forward with an opaque cursor.

Parameters

A few lists use a different default limit:

Response

Rows are shortened here; see the quickstart for a full collection row.

{
  "data": [
    { "slug": "popkins", "name": "Popkins", "rank": 1, "floorMist": "68040000000" },
    { "slug": "mystic-yetis", "name": "Mystic Yetis", "rank": 2, "floorMist": "26748930000" }
  ],
  "nextCursor": "eyJzbHVnIjoibXlzdGljLXlldGlzIiwicmFuayI6Mn0",
  "total": 968,
  "next": "eyJzbHVnIjoibXlzdGljLXlldGlzIiwicmFuayI6Mn0",
  "units": { "amount": "MIST", "decimals": 9, "symbol": "SUI" }
}

Some endpoints add their own fields next to these. GET /collections/{slug}/holders adds header, GET /accounts/{address}/items adds classes, and analytics lists add asOf.

Rules for cursors

• Treat the cursor as an opaque string. Do not build, edit or decode it. A cursor that does not parse returns 400 bad_request with "Invalid cursor".
• Send the same query parameters (sort, dir, filters) with every page. A cursor belongs to the query that produced it.
• Stop when next is null. A page can hold fewer than limit rows before the end.
• Cursors are not stored server side and do not expire, but data moves between requests. Listings sell, prices change and new events arrive.

Sorted pages

Lists that sort take sort (an allowed value per endpoint) and dir=asc|desc. An unknown sort or dir returns 400 bad_request, except on GET /collections and GET /collections/{slug}/traders, which fall back to their default order.

• Unknown values (null) always sort last, in both directions.
• Amounts sort as integers, names and addresses alphabetically, dates by time.
• In its default order, a list pages from the last row it returned (its sort key and id).
• In any other order, a list pages by position. If rows are added or removed between requests, a row can appear twice or be skipped.
• Either way, data can change while you page. Deduplicate by id when you collect every page.

Lists that do not page

Some endpoints return a complete list as { data } with no next, for example GET /collections/{slug}/traits, GET /collections/{slug}/offer-book and GET /collections/{slug}/sales. The notification history, GET /notify/recent, pages with before instead of a cursor: pass its next (the same value as nextBefore) as before. See Real-time notifications.

Fetch every page

This loop collects every listed item in a collection, cheapest all-in price first, 200 per request:

# Needs jq. Prints one item id per line.
url="https://rare.market/api/v1/collections/popkins/items"
cursor=""
while :; do
  page=$(curl -sS -G "$url" \
    --data-urlencode "status=listed" \
    --data-urlencode "sort=price_asc" \
    --data-urlencode "limit=200" \
    ${cursor:+--data-urlencode "cursor=$cursor"})
  echo "$page" | jq -r '.data[].id'
  cursor=$(echo "$page" | jq -r '.next // empty')
  [ -z "$cursor" ] && break
done

Each request counts toward your rate limit. For large collections, add a short pause between pages or use the retry helper from that page.