> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockgence.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Paginación y cortes

> Cómo paginar las listas, qué significa una lectura cortada y cómo pedir más con «leer más».

Las consultas on-chain leen listados que pueden ser enormes. La API pone topes para responder a tiempo y con un costo
predecible, y **declara** siempre lo que quedó afuera. Hay dos mecanismos distintos: listas paginadas y lecturas con
tope.

## Listas paginadas

Los endpoints que devuelven una lista larga de resultados ya calculados se paginan con `offset` y `limit`. Por ejemplo,
`POST /v1/counterparties`, que trae **todas** las contrapartes de una dirección, ordenadas por valor en USD:

```bash Pedido theme={null}
curl -X POST https://app.blockgence.com/v1/counterparties \
  -H "Authorization: Bearer $BKG_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address": "0x098b716b8aaf21512996dc57eb0615e2383e2f96", "direction": "both", "limit": 20}'
```

```json Respuesta theme={null}
{
  "address": "0x098b…2f96",
  "chain": "ethereum",
  "direction": "both",
  "total": 186,
  "offset": 0,
  "returned": 20,
  "has_more": true,
  "next_offset": 20,
  "counterparties": [
    {
      "address": "0x1a2a…",
      "label": "Axie Infinity: Ronin Bridge",
      "category": "bridge",
      "direction": "in",
      "value_usd": 342000000.0,
      "value": 173600.0,
      "tx_count": 2,
      "asset": "ETH",
      "first_ts": 1648041417,
      "last_ts": 1648041420
    }
  ]
}
```

Pedí la página siguiente con `offset = next_offset` hasta que `has_more` sea `false`. `limit` acepta hasta 100.

> [!NOTE]
>
> Cada página es una consulta y se cobra. Si la fuente no puede leer la dirección, la respuesta es
> `503 source_unavailable`, nunca «0 contrapartes».

## Lecturas con tope

Para armar un rastreo, la API lee el historial de cada dirección desde las fuentes de datos. Esa lectura tiene un
**tope de filas por listado**. Cuando una dirección tiene más actividad de la que entra, una parte del historial no se
lee, y la respuesta lo declara en `degraded_sources` y en el nodo afectado (`coverage_gaps`):

| `stage` | Qué quedó sin leer |
| - | - |
| `transfers.truncated` | Un tramo de bloques **dentro** del rastro. Las entradas y salidas de esa dirección en ese tramo no están en el resultado. |
| `transfers.truncated_outside` | Un tramo **fuera** del rastro: antes de la llegada de los fondos rastreados o después de su salida. No cambia los flujos que se siguen. |
| `transfers.completion_failed` | Falló la lectura extra que iba a completar el tramo del rastro. El motivo va en `reason`. |
| `messages.truncated` | El escaneo de mensajes on-chain no llegó al tramo más viejo. |

El mensaje de cada corte dice qué bloques de qué listado faltan. Lo que quedó afuera **no** es «sin movimientos».

> [!NOTE]
>
> La lectura se enfoca en el rastro: en un nodo cortado, primero se lee desde el bloque donde llegaron los fondos
> rastreados hacia adelante (o desde su salida hacia atrás). Así el tope se gasta en lo que importa para seguir la
> plata, no en la actividad más nueva de la dirección.

## «Leer más»

Para seguir leyendo un nodo que quedó con `transfers.truncated`, pedilo de nuevo en `POST /v1/trace` como `address`,
con su `since` y con `read_more`:

**read\_more** `integer` (default: 0)

Pasos extra de lectura para el nodo semilla: cada paso suma otro tope de filas por listado. Va de 0 a 9; un valor
mayor se acota.

**forward** `boolean` (default: true)

Con `false` no expande hacia adelante y lee solo hacia atrás (`back_hops`): sirve para releer un padre.

```bash theme={null}
curl -X POST https://app.blockgence.com/v1/trace \
  -H "Authorization: Bearer $BKG_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address": "0x098b716b8aaf21512996dc57eb0615e2383e2f96", "chain": "ethereum", "since": 1648041417, "read_more": 1}'
```

Lo que ya se leyó de ese nodo en los últimos 15 minutos no se vuelve a pedir a la fuente: cada paso cuesta solo sus
lecturas nuevas. Si el corte sigue, subí `read_more` (2, 3…).

En la aplicación web es el botón **Leer más** del nodo.

## Otros topes declarados

Algunas respuestas acotan sus listas internas para no crecer sin límite. Cuando cortan, lo dicen con un campo propio:

* un contador del total y la lista recortada (por ejemplo, `discarded_total` con `candidates_truncated: true`);
* `*_truncated: true` cuando una lista se cortó (`refs_truncated`, `contracts_truncated`);
* un resumen de lo descartado, como `unpriced` en las contrapartes: cuántas filas de tokens sin precio publicado se
  dejaron afuera, y de qué contratos.

La referencia de cada endpoint dice qué tope tiene y cómo lo declara.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.