Пагинация и фильтры

Списки в V3 Custody используют keyset-пагинацию по курсору: вы листаете, передавая курсор предыдущей страницы. В отличие от offset, keyset устойчив к вставкам — строки не пропускаются и не дублируются между страницами.

Keyset-пагинация

Список возвращает элементы и курсор следующей страницы:

{
  "items": [ ... ],
  "nextCursor": "eyJpZCI6..."
}

• cursor — передайте сюда nextCursor предыдущей страницы, чтобы получить следующую.
• limit — размер страницы.
• Когда nextCursor пуст или отсутствует — страницы кончились.

Сортировка

По умолчанию списки идут «сначала свежие»: убывание по временно́му ключу с id как tiebreaker. Например, журнал — по postedAt, id; лента операций — по createdAt, id; контрагенты — по createdAt. Курсор идёт в этом же порядке.

Общие фильтры

Набор зависит от эндпоинта, но встречаются одни и те же:

• from / to — временно́е окно (по createdAt или postedAt).
• direction — in / out (лента операций).
• token — ограничить токеном (балансы, адреса, журнал).
• status — статус (заявки, операции).
• search — подстрока (адреса, контрагенты).
• access=shared — только доступное вам (адреса).
• mine / pendingMine — мои / ждут моего голоса (заявки).
• userId — admin: чью активность показать.

Пример: пройти все страницы

# одна страница; для следующей подставьте nextCursor в ?cursor=
curl "[BASE_URL]/api/v1/vaults/acme-otc/history?direction=in&limit=100" \
  -H "Authorization: Bearer $V3_TOKEN"

let cursor;
const all = [];
do {
  const url = new URL("[BASE_URL]/api/v1/vaults/acme-otc/history");
  url.searchParams.set("direction", "in");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);

  const page = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.V3_TOKEN}` },
  }).then((r) => r.json());

  all.push(...page.items);
  cursor = page.nextCursor;
} while (cursor);

cursor, items = None, []
while True:
    params = {"direction": "in", "limit": 100}
    if cursor:
        params["cursor"] = cursor
    page = requests.get(
        "[BASE_URL]/api/v1/vaults/acme-otc/history",
        params=params,
        headers={"Authorization": f"Bearer {os.environ['V3_TOKEN']}"},
    ).json()
    items += page["items"]
    cursor = page.get("nextCursor")
    if not cursor:
        break

Что дальше