Skip to main content
GET
cURL
Use this endpoint for historical analysis, backtests, and recovering trade data after an outage. Rows use the Large trades format and default to newest first. The endpoint reads stored trades, so its coverage can have gaps. For a recent feed without a time range, use Large trades.

​
Parameters

has_more and next_cursor describe the filtered result, so a full page always holds limit matching trades.

​
Key response fields

​
Backtest without look-ahead

trader.grade, review_score, and the min_grade filter read the wallet as it is today. A rule like “follow S-grade wallets” tested on them selects wallets that were graded S after they won, so it looks better than it could have traded. Filter with min_grade_at_trade, and select on trader.grade_at_trade and recorded_review_score, instead. Grades are recorded from September 19, 2026 and recorded scores from August 3, 2026; before those dates the fields say unknown and null, never a guess. Nothing earlier can be rebuilt: the grade and the statistics the score reads were not kept per moment.

​
Capture rules by period

The size floor changed over the archive’s life, so month-to-month counts are not comparable at the default min_size. Pass min_size=10000 for one size rule across the whole range. Counts still follow the sports calendar. Until July 17, 2026, one match could be stored twice: once for each wallet. From May 1 to July 17, 27.7% of rows at $10,000 and up share a transaction and a market with another stored wallet, almost always a Yes buyer and a No buyer filled against each other. From July 18, 2026 a row is the taker’s side only. Before May the transaction hash is mostly absent, so the share cannot be measured there.

​
Example

​
What it does not return

  • A live feed. These rows are a replay of what 0xinsider stored, and meta.completeness.status is best_effort for that reason.
  • A trade under min_size, which defaults to 5000. Any value down to 0 is accepted, but it cannot reach fills below the size at which a trade is recorded at all.
  • An error for an unknown trader or condition_id. You get an empty list and a 200, so check the length of data rather than the status code.
  • The wallets on the other side of a trade. Open one row with Large trade.
  • A grade or a recorded score for a moment nobody recorded. Before September 19, 2026 the grade at trade time is unknown, so min_grade_at_trade matches none of those trades; before August 3, 2026 recorded_review_score is null.
  • A trade priced at 0.97 or above stored since July 6, 2026, outside earnings markets.

​
Caching

Save the response’s ETag and send it in If-None-Match on your next request. If the list has not changed, the server returns 304 Not Modified with no body. data_quality is part of the representation and its stored clocks are included in the ETag; meta.cached and meta.cache_age_s describe the transport cache.

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
​
If-None-Match
string

Conditional GET validator from a previous ETag. Matching values return 304 Not Modified with an empty body.

Query Parameters

​
limit
integer
default:20

Maximum number of historical large trades to return. Out-of-range values are clamped to 1..100.

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

Pagination cursor from previous response's next_cursor. Prefix: wth_. URL-encode when replaying as a query parameter.

​
min_size
number
default:5000

Minimum trade size in USD. The capture floor was 3,000 USD before 2026-07-06 and 10,000 USD from then (1,000 USD in earnings markets), so 10000 gives one size rule across the whole archive. From 2026-09-23 a fill must also be at least 0.1% of its market's recorded traded volume (Polymarket's own share count), where a positive volume is recorded for the market; a market without one keeps the fill, and rows written before that date were not re-filtered.

​
condition_id
string

Exact raw provider condition_id. Unknown markets return an empty list.

​
trader
string

Trader wallet address, timestamp-suffixed wallet alias, username, or trd_-prefixed trader ID, resolved against the traders table. Unknown traders return an empty list.

​
category
string

Filter by market category (case-insensitive). A canonical bucket name (e.g. Basketball) matches every provider member that folds into it (NBA, WNBA, NCAAB); a raw provider value also resolves to its bucket. Sports and esports only (#27430): a category outside them returns 400 bad_request with param category and names the accepted buckets. The word sports, in any casing, matches every sport but Esports, the provider's catch-all Sports category (cycling, lacrosse) included: use esports for Esports alone, or omit category for both (#32657).

​
min_grade
enum<string>

Minimum trader grade as of today (trader.grade), not at trade time. On a historical window it selects wallets by a grade they may have earned after the trade; for a point-in-time rule send min_grade_at_trade instead, which filters on trader.grade_at_trade. A means S or A, B means S, A or B.

Available options:
S,
A,
B,
C,
D,
F
​
min_grade_at_trade
enum<string>

Minimum grade the trader held when the trade filled (trader.grade_at_trade). Only rows whose trader.grade_at_trade_status is graded can match, so a trade before 2026-09-19T23:00Z, or one made while the wallet's grade was changing, never does. The same basis as min_grade_at_trade on GET /api/v1/large-trades, GET /api/v1/stream and webhook trade_filters, so a history read and a stream with the same floor agree. Applies to both sorts and beside condition_id, event_slug, trader and from/to. Sending it with min_grade is 400. A means S or A, B means S, A or B.

Available options:
S,
A,
B,
C,
D,
F
​
suspicious_only
boolean
default:false

When true, return only rows with persisted suspicion_score >= 60. The filter is applied before SQL-backed limit + 1 pagination.

​
platform
enum<string>

Filter by whale_alerts.platform. all is equivalent to omitted.

Available options:
polymarket,
all
​
from
string<date-time>

Inclusive RFC3339 lower bound on whale_alerts.traded_at.

​
to
string<date-time>

Exclusive RFC3339 upper bound on whale_alerts.traded_at. Must be after from when both are present.

​
min_market_volume_share
number

Keep only trades whose market_volume_share is known and at least this. A fraction, not a percent: 0.01 is one percent of the market's traded volume. A trade whose share is unavailable is never returned by a non-zero value, because an unavailable share cannot be said to clear a floor.

Required range: 0 <= x <= 1
​
sort
enum<string>
default:recent

Order of the returned page. recent is newest first and is the default. market_volume_share ranks by each trade's share of its market's traded volume, biggest first, with a trade whose share is unavailable last. That ranking reads from, or the last 30 days when from is omitted, for the same reason. A cursor is bound to the order it was minted in, so a continuation cannot cross from one order into the other.

Available options:
recent,
market_volume_share
​
event_slug
string

Only the large trades in one game: every market of the game behind this event slug, the moneyline, spreads, totals and props, as GET /api/v1/games/{event_slug}/trades reads them. Matched case-insensitively. Newest first only (sort=market_volume_share answers 400), and cannot be combined with condition_id (400). An unknown slug answers 404 not_found with error.param event_slug.

Response

Historical large trade replay

​
object
string
required
Allowed value: "list"
​
data
object[]
required
​
data_quality
object
required

Writer-backed age and coverage for this page; it is part of the representation and the ETag, while transport cache facts remain in meta.

​
has_more
boolean
required
​
meta
object
required
​
next_cursor
string
​
total
integer

Total matching rows when the read model exposes a count; the key is absent when it does not.