0X0xinsider
Large trades

Replay historical whale trades

Changed on

Returns historical whale trades from local whale_alerts rows, not request-time provider fetches. Filter by condition_id, trader, category, minimum grade, persisted suspicion, platform, and RFC3339 from/to windows. All filters are pushed into SQL before LIMIT, every request uses SQL-backed limit + 1 pagination, and results are ordered newest first by traded_at desc, id desc. Metadata exposes local_replay source and best_effort completeness. Deprecated alias of GET /api/v1/large-trades/history, kept live and never removed (#16304); every response carries Deprecation: @1790047200 (RFC 9745, 2026-09-22T03:20:00Z) and a Link to the successor (rel="successor-version") and to the versioning policy (rel="deprecation"). No Sunset header is sent because no removal is planned. The response adds a top-level data_quality object beside data, grouping alert, trade, trader, ranking, market, and volume fields by their database writer. whale_alerts.inserted_xid is reported as unknown because it is a transaction identifier rather than a timestamp. Its stored clocks are part of the ETag; meta continues to hold transport cache facts.

get/api/v1/whale-trades/history

Request

Query parameters

limitinteger

Maximum number of historical large trades to return.

cursorstring

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

min_sizenumber

Minimum trade size in USD.

condition_idstring

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

traderstring

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

categorystring

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.

min_grade'S' | 'A' | 'B' | 'C' | 'D' | 'F'

Minimum trader grade.

suspicious_onlyboolean

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

platform'polymarket' | 'all'

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

fromstring date-time

Inclusive RFC3339 lower bound on whale_alerts.traded_at.

tostring date-time

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

min_market_volume_sharenumber

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.

sort'recent' | 'market_volume_share'

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.

Headers

If-None-Matchstring

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

Response

Historical whale trade replay

object'list' required
has_moreboolean required
next_cursorstring
totalinteger

Total matching rows when the read model exposes a count; absent (or null) when it does not.

Changes

  • 9d1ba37bd5e3Revision changes
    • info

      added the required property to the response with the status

  • 7e57bd9dc8b5Revision changes
    • info

      added the new optional query request parameter min_market_volume_share

    • info

      added the new optional query request parameter sort