Skip to main content
On-chain queries read lists that can be huge. The API sets caps to answer in time and at a predictable cost, and it always declares what was left out. There are two different mechanisms: paginated lists and capped reads.

Paginated lists

Endpoints that return a long list of already computed results are paginated with offset and limit. For example, POST /v1/counterparties, which returns all counterparties of an address, sorted by USD value:
Ask for the next page with offset = next_offset until has_more is false. limit accepts up to 100.
Each page is a query and is charged. If the source cannot read the address, the response is 503 source_unavailable, never «0 counterparties».

Capped reads

To build a trace, the API reads each address’s history from the data sources. That read has a row cap per list. When an address has more activity than fits, part of its history is not read, and the response declares it in degraded_sources and on the affected node (coverage_gaps): Each cutoff’s message says which blocks of which list are missing. Whatever was left out is not «no movements».
The read focuses on the trace: on a cut-off node, it first reads from the block where the traced funds arrived forward (or from where they left, backward). That way the cap is spent on what matters for following the money, not on the address’s newest activity.

«Read more»

To keep reading a node that ended with transfers.truncated, request it again in POST /v1/trace as address, with its since and with read_more:
integer
default:"0"
Extra read steps for the seed node: each step adds another row cap per list. It goes from 0 to 9; a larger value is capped.
boolean
default:"true"
With false it does not expand forward and only reads backward (back_hops): useful to re-read a parent.
Whatever was already read for that node in the last 15 minutes is not requested from the source again: each step only costs its new reads. If the cutoff remains, raise read_more (2, 3…). In the web app it is the node’s Leer más (read more) button.

Other declared caps

Some responses cap their inner lists so they do not grow without limit. When they cut, they say so with a field of their own:
  • a total counter and the trimmed list (for example, discarded_total with candidates_truncated: true);
  • *_truncated: true when a list was cut (refs_truncated, contracts_truncated);
  • a summary of what was dropped, such as unpriced in counterparties: how many rows of tokens without a published price were left out, and from which contracts.
Each endpoint’s reference says what cap it has and how it declares it.