Skip to main content
GET
cURL
Use this after a worker restart, a webhook outage, or a Stream resync. The stream pushes the same events live, while this route stores them and hands them back a page at a time. Every event stands for one large Polymarket trade that 0xinsider recorded.

​
Parameters

trader, condition_id, min_grade, and min_size are recorded inside the cursor. Sending that cursor back under a different set of filters, including no filters at all, answers 400 with error.reason cursor_expired: start again without a cursor under the new filters. A cursor from an unfiltered request is bound to no filters, so adding a filter part of the way through is refused the same way. expand changes what each event carries, never which events you get, so you can turn it on or off at any point.

​
How to page through events

  1. Call it once with no cursor. You get the newest limit events in commit order, and has_more is false.
  2. Store next_cursor somewhere that survives a restart. After a page that is not full it moves past every row the server examined, so even an empty page moves you forward.
  3. Send it back as cursor on the next call. You get only the events after it.
  4. Repeat while has_more is true, storing next_cursor after you process each page. A crash then repeats a page instead of skipping one.
  5. Deduplicate on data[].id, never on sequence. A lower sequence can follow a higher one, which is the trade an id-ordered reader used to lose.
Events come back in the order their writes became visible, and then by sequence. A page never reaches past the oldest write that was still open when the page was read. So a trade whose id is lower than one you already hold, but whose write finished later, arrives on a later page instead of being skipped.

​
Key response fields

​
Example

Only A-or-better wallets, with the whole trade on every event, in one request per page:

​
What it does not return

  • Any other event type. Alert, following, radar, position patch, and browser-only events have no durable public record yet.
  • The trade itself, unless you ask for it. expand=trade carries it, and without it payload.whale_alert_id is the id to pass to Large trade.
  • Exactly-once delivery. A page read again after a crash repeats its events, so deduplicate on data[].id.
  • Events before your cursor. The window starts strictly after it, so go further back by storing an older cursor, not by editing one.

Authorizations

​
Authorization
string
header
required

Legacy default or named integration API key, or OAuth 2.1 access token, in the Authorization header as Bearer oxi_sk_live_... or Bearer oxi_at_.... Default keys retain full access; integration keys are limited to their approved read, webhooks, export and usage scopes and expire within 90 days. All credentials share the owner's account limits. Data calls require an active Pro subscription and return live data. A 401 carries WWW-Authenticate: Bearer resource_metadata="https://api.0xinsider.com/.well-known/oauth-protected-resource" (RFC 6750 section 3, RFC 9728).

Headers

​
X-Query-Validation
enum<string>

Opt into strict query-name validation. The default is compatible: unknown names are ignored and reported in X-Query-Ignored. With strict, an unknown name returns 400 bad_request with error.reason unknown_query_parameter before the handler runs, including when its percent escape is incomplete.

Available options:
strict

Query Parameters

​
cursor
string

Opaque event replay cursor returned as next_cursor by a prior response. The cursor maps to the global (whale_alerts.inserted_xid, whale_alerts.id) commit-order position, is valid across backend replicas, and is bound to the filter set the walk ran with (trader, condition_id, min_grade, min_size): presenting it under different filters answers 400 bad_request with error.reason cursor_expired, and the walk restarts without a cursor. Cursors issued before 2026-09-22 (id-only) stay accepted and are bound to no filters. Omit to fetch the latest durable public suffix.

​
limit
integer
default:50

Maximum durable public whale-trade events to return. Out-of-range values are clamped to 1..100.

Required range: 1 <= x <= 100
​
trader
string

Only this wallet's trades: a wallet address, trd_-prefixed trader id or username resolved against the traders table. Bound to the cursor: a cursor issued under other filters answers 400 with error.reason cursor_expired. An unknown trader matches nothing and the walk still advances.

​
condition_id
string

Only trades on this market: the raw provider condition_id or its mkt_-prefixed id. Bound to the cursor.

​
min_grade
enum<string>

Only trades by wallets at this grade or better (S best), read from the wallet's newest ranking at request time; a wallet with no grade never passes. Bound to the cursor.

Available options:
S,
A,
B,
C,
D,
F
​
min_size
number

Only trades of at least this size in USD (compared in cents). Bound to the cursor.

Required range: x >= 0
​
expand[]
enum<string>[]

Backward-compatible alias for expand. Repeatable: trade.

Available options:
trade
​
expand
enum<string>[]

Repeatable. trade adds the public trade read to every event (the object GET /api/v1/whale-trades/{id} returns for it), from one query per page, so a page of 100 events needs no per-event detail request. Not bound to the cursor: switch it on or off mid-walk.

Available options:
trade

Response

Public event replay window

​
object
string
required
Allowed value: "event_replay"
​
data
object[]
required
​
has_more
boolean
required
​
next_cursor
string
required
​
meta
object
required