Supra Core API — Public Client Documentation

Chapter 15 — Pagination, Filters, and Limits

1. Purpose

This chapter centralizes the public behavior of:

• limit;
• offset;
• exact filters;
• block and time ranges;
• sorting;
• deterministic ordering;
• empty pages.

Endpoint chapters remain authoritative for their exact parameters.

---

2. Which Endpoints Paginate

/api/v1/health and /api/v1/market/pair are object lookups and do not use list pagination. /api/v1/chart/token is range-bounded by the server to at most 2,500 chronological points rather than using limit/offset.

---

3. limit

limit is the maximum number of rows requested for one page.

• It must be a valid positive integer.
• Values above the endpoint maximum are clamped.
• A smaller response is valid.
• It is not a request-rate allowance.

Example:

limit=<limit>

---

4. offset

offset is the number of rows skipped from the endpoint's current deterministic ordering.

• The first page uses offset=0.
• The next page normally adds the current limit.
• Values above the maximum are clamped.
• An offset beyond current results returns an empty array.

The API does not currently support page_token.

---

5. Safe Pagination Loop

Language-neutral logic:

offset = 0

repeat:
    response = GET <endpoint>?limit=<limit>&offset=offset
    validate status, JSON, and ok
    process response.data

    if response.data is empty:
        stop

    if response.data count is less than limit:
        stop

    offset = offset + limit

Also stop on:

• authentication failure;
• rate limit after the retry budget;
• unrecoverable parameter error;
• configured page or row safety cap.

---

6. Changing Data and Stable Ordering

Event lists can change while a client paginates. New rows can appear before later pages are requested.

Clients should:

• preserve the endpoint's ordering;
• use exact block or time bounds for repeatable historical windows;
• deduplicate using documented row context;
• avoid assuming offset pagination is an immutable snapshot.

Do not deduplicate swap or liquidity rows by transaction hash alone.

---

7. Exact Filters

Unless an endpoint chapter states otherwise, filters are exact:

• metadata and addresses must match the expected identifier;
• symbol filters use the documented case behavior;
• source, protocol, scope, DEX, event-family, and event-type values should come from public rows or documentation;
• a wallet address is not interchangeable with a token, pool, or farm address.

Combining filters narrows the result.

---

8. Block Ranges

Swap, liquidity, and burn endpoints support:

• from_block: inclusive minimum;
• to_block: inclusive maximum.

Valid relationship:

from_block <= to_block

Invalid or reversed ranges return 400.

---

9. Candle Time Ranges

The candle endpoint supports Unix timestamp filters:

• from;
• to.

They apply to candle bucket start time. Use integer Unix seconds and ensure from <= to.

Do not send date strings where Unix integers are required.

---

10. Sorting

market/current supports documented allowlisted sort values.

Other list endpoints use their documented fixed ordering. Swaps and liquidity use block height then row id descending; burn uses block height, source event index, then row id descending; canonical candles use bucket start then row id descending. Clients cannot send arbitrary SQL-like sort expressions.

The chart endpoint is already chronological. Canonical candle rows are newest-first and can require client-side reordering for chart libraries.

---

11. Empty and Short Pages

Both are valid:

• data=[];
• a page shorter than limit.

They commonly indicate the current end of matching results. They do not automatically indicate an outage.

---

12. Rate-Limit-Safe Pagination

• Keep page requests sequential or conservatively concurrent.
• Cache completed historical pages.
• Avoid full-history tight loops.
• Back off on 429.
• Add jitter to retries.
• Resume from a known bounded position when appropriate.

---

13. Scope and Data Exposure

Clients can rely on the documented filters, limit, offset, ordering, and tie-break behavior. Query implementation and enforcement details are outside the API contract.

---

14. Chapter Summary

Paginate list endpoints with bounded limit and offset, use exact filters, apply valid block or time ranges, preserve documented ordering, and stop safely on empty or short pages. The current API does not use page_token.