Pagination

Nearly every list endpoint pages with an opaque cursor. There is no offset and no page number: read has_more, send next_cursor back as cursor, and stop when has_more is false. Three list routes are the exception and never page. Search content, Webhooks, and Webhook events return one bounded page, with has_more always false, no cursor in the response, and no cursor parameter to send.

The list envelope

{
  "object": "list",
  "data": [],
  "has_more": true,
  "next_cursor": "2026-08-28T14:02:11+00:00_wt_1830042",
  "total": 4210,
  "meta": { "request_id": "req_abc123", "cached": false, "cost": 1 }
}

Field	Meaning
`data`	The rows, up to `limit` of them.
`has_more`	`true` when another page exists. Stop your loop when it is `false`, whatever `next_cursor` says.
`next_cursor`	The cursor that fetches the next page. Most routes leave it out of the response on the last page rather than sending `null`, so read it with a default.
`total`	How many rows match in all. Only the routes that run a count return it, and it is absent everywhere else. Explore markets returns it on the first page and leaves it out of later pages.

Page size

limit is a whole number. On every list route a value outside the bounds is clamped into them rather than rejected: limit=500 returns the maximum and limit=0 returns one row, with no error. The X-Effective-Query response header reports the limit the page used, so read it when you want to know what a clamped request became. A limit that is not a whole number answers 400 with error.reason invalid_query.

Route	Default	Maximum
Most list routes	`20`	`100`
Explore markets	`24`	`48`
Trending wallets	`20`	`50`
Event replay	`50`	`100`
Counterparty executions, Counterparty makers	`100`	`100`

For a route that is not in this table, read its endpoint page. The parameter list there states that route’s own limit default and maximum.

curl -H "Authorization: Bearer $OXINSIDER_API_KEY" \
  "https://api.0xinsider.com/api/v1/whale-trades?limit=100&cursor=2026-08-28T14%3A02%3A11%2B00%3A00_wt_1830042"

URL-encode the cursor when you send it back. Some routes return a cursor that contains a timestamp, and its + and : characters do not survive a query string unencoded.

Treat the cursor as an opaque string

Store it and send it back unchanged. Do not read it, parse it, build one, or branch on what is inside it. The format differs by route and can change in any release. A cursor only works on the route that returned it, and on that route’s aliases. Sending it anywhere else answers 400 with error.param set to cursor.

What ties a cursor to a request

Some cursors carry only the position of the last row, so they keep working for as long as you hold them. Others are tied to the filters you sent or to a ranking that 0xinsider rebuilds on a schedule, and those stop working when either changes.

Route	The cursor is tied to	When that changes
Whale trades, Whale trades history	The time and id of the last row on the page.	Nothing happens. The cursor keeps working.
Positions, Large positions	The last row’s place in the list.	Nothing happens.
Position timeline, Position timeline by trader	The time and id of the last event.	Nothing happens.
Search markets, Explore markets	The last row’s sort value and market id.	Nothing happens.
Webhook deliveries	The time and id of the last delivery.	Nothing happens.
Market holders	A page number in a holder list that every caller shares.	Nothing happens. The cursor still works after that list is rebuilt.
Suspicious trades with `mode=live`, the default	The suspicion score and id of the last flag.	Nothing happens.
Suspicious trades with `mode=stable`	One published scoring run, plus `limit`, `min_suspicion`, `severity`, and the exact score the page ended on.	`400` with `error.reason` `cursor_expired`.
Leaderboard	The published ranking, plus your `category` and `strategy` filters.	`400` with `error.reason` `cursor_expired`.
Trending wallets	The published board, plus `limit` and `window`. Send the same `limit` and `window` on every page.	`400` with `error.reason` `cursor_expired`.
Sharp money flows, Smart money flows	The first page’s `as_of`, your filters, and the ranking and totals behind the rows.	`400` with `error.reason` `cursor_expired`. Cursors issued before September 22, 2026 always answer this.
Pre-game sides	The ranking the first page was cut from, which is rebuilt about every 180 seconds.	`400` with `error.reason` `cursor_expired`.
Pre-game side observations	`snapshot_as_of` and `cohort`, signed by the server.	`400`. An edited cursor is refused, and a cursor can never move to another `cohort`.
Event replay	The filters in force when the cursor was issued: `trader`, `condition_id`, `min_grade`, and `min_size`. `expand` is not part of it.	`400` with `error.reason` `cursor_expired`. Start again with no cursor under the new filters.
Counterparty executions, Counterparty makers	The `snapshot_id` you took from the whale trade.	`400` with `error.reason` `cursor_expired` once that snapshot is gone. Read the trade again for a new `snapshot_id`.

Handle a 400

A request with a cursor answers 400 with error.code bad_request in two cases. Branch on error.reason to tell them apart.

`error.reason`	What happened	What to do
`cursor_expired`, with `error.param` `cursor`	The data behind your pages changed, as the table above describes. The cursor itself is not malformed.	Throw away the rows you collected and request the first page again.
Absent	The cursor, or another parameter, is malformed.	Read `error.param` and `error.message` to find which one.

cursor_expired carries no Retry-After header and no error.retry_at. Waiting changes nothing, so do not sleep and retry the same cursor; only a fresh first page helps.

Read every page

const headers = { Authorization: `Bearer ${process.env.OXINSIDER_API_KEY}` };

async function listAll(path, params = {}) {
  for (let attempt = 0; attempt < 3; attempt++) {
    const items = [];
    let cursor;
    let expired = false;
    do {
      const qs = new URLSearchParams({ limit: "100", ...params });
      if (cursor) qs.set("cursor", cursor);
      const res = await fetch(`https://api.0xinsider.com/api/v1${path}?${qs}`, { headers });
      const body = await res.json();
      if (res.status === 400 && body.error?.reason === "cursor_expired") {
        expired = true;
        break;
      }
      if (!res.ok) throw new Error(body.error?.message ?? res.statusText);
      items.push(...body.data);
      cursor = body.has_more ? body.next_cursor : undefined;
    } while (cursor);
    if (!expired) return items;
  }
  throw new Error("cursor expired three times");
}

const trades = await listAll("/whale-trades", { min_grade: "A" });

import os, requests

BASE = "https://api.0xinsider.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['OXINSIDER_API_KEY']}"}

def list_all(path, **params):
    for _ in range(3):
        items, cursor, expired = [], None, False
        while True:
            p = {"limit": 100, **params}
            if cursor:
                p["cursor"] = cursor
            res = requests.get(f"{BASE}{path}", params=p, headers=H)
            body = res.json()
            if res.status_code == 400 and body.get("error", {}).get("reason") == "cursor_expired":
                expired = True
                break
            res.raise_for_status()
            items.extend(body["data"])
            if not body["has_more"]:
                return items
            cursor = body["next_cursor"]
        if not expired:
            return items
    raise RuntimeError("cursor expired three times")

trades = list_all("/whale-trades", min_grade="A")

Both versions start over from the first page when a cursor expires, and give up after three attempts. Send the same filters on every page of one run, because changing a filter part way through either expires the cursor or reads a different set of rows.

What this does not tell you

A row count on most routes. total is only there on the routes that run a count.
A stable second page once a ranking is rebuilt. That is the cursor_expired case above.
How to jump straight to page 10. There is no offset, so you have to read every page before it.

Getting started

Integrations

Guides

Concepts

The list envelope

Page size

Treat the cursor as an opaque string

What ties a cursor to a request

Handle a 400

Read every page

What this does not tell you

​The list envelope

​Page size

​Treat the cursor as an opaque string

​What ties a cursor to a request

​Handle a 400

​Read every page

​What this does not tell you

The list envelope

Page size

Treat the cursor as an opaque string

What ties a cursor to a request

Handle a 400

Read every page

What this does not tell you