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.
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.
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 before interpreting emptiness as no activity.
For GET /v1/address/balance, read lookup_status separately from the arrays. The handler defines these lookup outcomes:
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
Transfertime, 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 returnedid 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.
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.