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

# Working with responses

> Interpret Data API pagination, quantities, lookup outcomes, timestamps, and transfer records for each operation.

Use this reference when consuming Data API responses. Choose operations in [Which endpoint should I use?](https://docs.range.org/data-api/data-introduction.md#which-endpoint-should-i-use), check [coverage](https://docs.range.org/data-api/product-info/coverage.md), and use [Errors and rate limits](https://docs.range.org/resources/errors-and-rate-limits.md) for HTTP failures and retries. Platform objects have separate conventions.

## Pagination by operation

Pagination parameters and response envelopes differ. Keep the filters and page size unchanged when following a returned cursor; treat the cursor as opaque.

| Operation | Request controls | Response and limits |
| - | - | - |
| `GET /v2/transfers` | `cursor`, `size` | `items`, `meta.next_cursor`; default `size` 25. |
| `GET /v2/cross-chain/transfers/by-hash/{tx_hash}` | `cursor` only | `items`, `meta.next_cursor`; fixed page size of 100. |
| `GET /v2/transactions` | `cursor`, `size` | `items`, `meta.next_cursor`; `size` 1-100, default 25. Requires `network`. |
| `GET /v2/entities` | `cursor`, `size` | `items`, `meta.next_cursor`; `size` 1-100, default 10. |
| `GET /v2/connections/transfers` | `cursor`, `size` | `items`, `meta.next_cursor`; `size` 1-100, default 10. |
| `GET /v2/tokens/top-holders` | `cursor`, `size` | `items`, `meta`; `size` 1-1000, default 100. |
| `GET /v2/tokens/mints-burns` | `cursor`, `limit` | `events`, top-level `next_cursor`; `limit` 1-1000, default 50. |
| `GET /v1/address/transactions`, `GET /v1/address/payments`, `GET /v1/network/payments` | `offset`, `limit` | `transactions` or `payments`, plus `total`; defaults are 0 and 50. No maximum is declared. |
| `POST /v1/network/{network}/payments`, page mode | `page`, `pageSize`, JSON body `{}` | `payments`, `count`; `page` is the number of records to skip, starting at 0. Pass both controls explicitly. No maximum is declared. |
| The same network payments operation, scroll mode | `useScroll=true`, `scrollBatchSize`, body `{}` initially | Read `payments`, `scrollId`, and `hasMore`. Send the returned `scrollId` in the next JSON body. Set batch size explicitly; no maximum is declared. |

For `meta` envelopes, follow `meta.next_cursor` until it is null. For mint/burn events, follow the top-level cursor until it is absent. For offset lists, advance `offset` by the returned array length and stop on an empty array. A `limit` on a ranking operation, such as `GET /v1/network/whale-moves`, limits the ranking; it does not establish a next-page mechanism. Likewise, `GET /v2/connections/byAddress` has `size` but no cursor parameter.

Top holders accepts `cursor=A` for the first page and `cursor=Z` for the last page. Its metadata includes `first_page_cursor`, `last_page_cursor`, and `page_number`. `total_count` can be null until the last-page lookup. Do not interpret a missing count as zero or build cursors from holder ranks.

## Quantities and USD values

Read the operation's amount fields before applying a scale. Preserve integer strings with arbitrary-precision integer or decimal arithmetic.

| Operation | Interpretation |
| - | - |
| `GET /v1/address/balance` | Each line's `base_amount` is an exact base-unit integer string. When `decimals` is known, dividing it by `10 ** decimals` gives token units. `amount_string` already carries that scaled quantity. The field contract defines `amount_string` as base units when `decimals` is null, meaning the scale is unknown. Prefer it over the legacy numeric `amount`. |
| `GET /v2/tokens/total-supply` | `total_supply_raw` is a base-unit integer string; `total_supply` has `decimals` applied. Do not scale `total_supply` again. |
| `GET /v2/transfers` | `sender.token.amount` and `receiver.token.amount` are token quantities, with `symbol` identifying the denomination. Their optional `usd` fields represent USD value. Do not apply a balance endpoint's scale to these amounts. |
| `GET /v2/tokens/mints-burns` | `amount_raw` preserves the integer quantity. The response does not supply `decimals`; do not infer a scale from the field name `amount`. |

Balance lines also offer `price_string` and `usd_string` alongside numeric `price` and `usd` when those values are available. These preserve decimal precision; they are not additional base-unit quantities. Keep missing or null valuations distinct from numeric zero. Transfer USD values can be zero, including on records with a positive token amount; do not use that value to decide whether tokens moved.

## Empty results and lookup outcomes

A successful HTTP response does not establish completeness. `items: []` on a transfer query and `payments: []` with `total: 0` on an address query are valid empty results for those requests. Check [operation and network coverage](https://docs.range.org/data-api/product-info/coverage.md) before interpreting emptiness as no activity.

For `GET /v1/address/balance`, read `lookup_status` separately from the arrays. The handler defines these lookup outcomes:

| Status | Meaning |
| - | - |
| `ok` | The lookup resolved. Returned amounts can be zero, and either balance array can be empty. |
| `partial` | The lookup is incomplete. Use the resolved balances without treating them as a complete set. |
| `unavailable` | The handler could not establish a usable balance result. Empty arrays do not represent a measured zero balance. |
| `unsupported` | No readable balance source was available. Consult the coverage matrix. |

The response contract keeps `balances.native_tokens` and `balances.tokens` as arrays. It defines `reason` as null on `ok` and `unsupported`, and as a machine-readable `code` with display text on `partial` or `unavailable`. Treat an incomplete lookup separately from an HTTP error.

## Times and address casing

Transfer `time`, transaction `time`, and legacy address-transaction `timestamp` are ISO 8601 strings. The mint/burn event's numeric `timestamp` is Unix seconds: multiply by 1000 before constructing a JavaScript `Date`. Top-holder `snapshot_date` is a calendar date, not an event timestamp.

Time filters also vary: transfers and v2 transactions use `start_time`/`end_time`; legacy address lists use `startTime`/`endTime`. Supply ISO 8601 values with a timezone rather than assuming numeric milliseconds work for every operation.

Preserve address casing from the response. EVM examples use lowercase addresses, while Solana addresses retain mixed case. Keep `network` with the address when storing a participant; never lowercase every address as a universal normalization step.

## The transfer record

A transfer is one movement record with sender and receiver legs. On an intrachain record both legs share a network and can share a transaction hash. An interchain record joins legs on different networks. A transaction can contain multiple movements, so counting transfers and counting transactions answers different questions.

Use the returned `id` with `GET /v2/transfers/{id}` and URL-encode it as a path segment. Keep it separate from `sender_tx_hash` and `receiver_tx_hash`; those identify the legs' transactions. Preserve the ID instead of constructing it from a hash. Participant addresses and transaction hashes can be empty strings, including when a destination leg is not yet available.

| `status` | Interpretation |
| - | - |
| `SUCCEEDED` | The movement is recorded as successful. |
| `PENDING` | Completion is pending; do not assume a destination transaction exists. |
| `ERROR_ON_DESTINATION` | The destination reports an error. |
| `TIMEOUT` | The transfer timed out. |
| `UNPAIRED` | The transfer is reported as unpaired. |
| `REFUNDED` | The transfer is reported as refunded. |

These transfer states differ from the transaction response's boolean `success`. Read the transfer status and both leg identifiers together; a sender transaction alone does not prove cross-chain completion.


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