Cursor pagination: next_cursor means another page exists; no next_cursor means the end.

Pagination

One approach only: keyset cursors. There is no offset anywhere in the API.

GET /v1/remittances?limit=50&cursor=eyJ0IjoiMjAy…

{
  "data": [ … ],
  "next_cursor": "eyJ0IjoiMjAy…",
  "has_more": true
}

Three Rules

1. Use has_more to identify the end, not data.length < limit. The latter can make you miss a page when the last page is exactly full.

2. next_cursor is opaque; do not parse it. It currently encodes a base64 (排序值, id) tuple, but that is an implementation detail. Decoding it to construct your own cursor will silently misalign pagination when we change the sort key.

3. Undecodable cursors restart from the beginning without an error. An expired or malformed cursor returns the first page, not 400—a deployment midway through pagination should not interrupt your batch. The side effect: a cursor you construct incorrectly looks like “why did it start over?” rather than an error.

Why There Is No offset

When paginating orders by created_at DESC, new records are inserted at the front. On the second request, offset=100 no longer points to the same row, causing missing and duplicate rows, neither of which raises an error; you only discover that exported accounts do not reconcile by a few entries.

Static Lists

Some endpoints, such as GET /v1/qrpay/schemes, return a bounded constant set. They still use the same envelope:

{ "data": [ … ], "next_cursor": null, "has_more": false }

Your generic paginator therefore needs no special case.