Paginación

Casi todas las colecciones devuelven la misma envoltura: data (los elementos) y pagination (los metadatos de navegación). La excepción es GET /v2/balances, que devuelve un arreglo plano: tienes una posición por activo, así que no hay nada que paginar. Lo que cambia es qué contiene pagination, porque v2 usa dos estrategias.

Estrategia	Dónde	Metadatos
Offset (por defecto)	Todo salvo fills	page, limit, totalItems, totalPages
Cursor	GET /v2/fills y GET /v2/orders/{id}/fills	count, nextCursor

Offset — el caso general

{
  "data": [
    { "id": "wd_123", "status": "COMPLETED" },
    { "id": "wd_124", "status": "PENDING" }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "totalItems": 132,
    "totalPages": 6
  }
}

Parámetro	Descripción
page	Número de página. Empieza en 1. Por defecto 1.
limit	Elementos por página. Por defecto 25, máximo 100.

Cursor — los fills

Los dos endpoints de fills paginan por cursor, no por offset:

{
  "data": [
    { "id": "1096473", "orderId": "clord_01H…", "baseAmount": "0.01" }
  ],
  "pagination": {
    "count": 25,
    "nextCursor": "MjAyNi0wNy0yNiAxNzo0MjowMS4wMDMzMDl8OWY4Zi00YQ"
  }
}

Parámetro	Descripción
limit	Elementos por página. Por defecto 25, máximo 100.
cursor	El pagination.nextCursor de la página anterior. Omítelo en la primera.

Recorrido correcto: pide una página, procesa data, y si nextCursor no es null vuelve a pedir pasándolo como cursor. Repite hasta que sea null.

No infieras el final por una página corta

count puede ser menor que el limit que pediste aunque todavía queden resultados. La única señal de fin es nextCursor: null. Un cliente que corta al ver una página corta se pierde datos.

Por qué los fills son la excepción

Un fill es un registro de ejecución: solo se añade, nunca se reordena. Con OFFSET n la base de datos vuelve a recorrer y descartar n filas en cada página, y —lo que importa más en una API de dinero— la ventana se mueve bajo tus pies: un fill nuevo durante el recorrido empuja una fila de la página 2 a la página 3, y un cliente que está paginando su propio historial se la salta en silencio. Un cursor keyset es estable frente a inserciones concurrentes y cuesta lo mismo en la página 1 que en la 500.

Es también lo que hace el mercado para este recurso concreto: /fills de Coinbase pagina por cursor y myTrades de Binance avanza por fromId. Lo que se cede son los totales, y para un registro que solo crece "cuántos fills he tenido en total" no compensa un COUNT completo en cada página.

El cursor es opaco

nextCursor es un token opaco: devuélvelo tal cual. Su codificación no es parte del contrato y puede cambiar. No lo parsees, no lo construyas y no lo guardes como si fuera un identificador estable.

Filtros

En v2, los filtros se expresan como parámetros de query en lugar de rutas especiales. Por ejemplo, para ver los fills de una orden usa GET /v2/fills?orderId=… en vez de una ruta dedicada.

Consulta la Referencia de la API para ver los filtros disponibles en cada colección.