Sign in
Large trades

Replay historical large trades

Returns historical large 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. POINT IN TIME: signal_score, trader.grade and the min_grade filter carry today's values on every row however old, so a backtest that selects by them selects wallets on what they did after the trade. The point-in-time fields are recorded_signal_score (from 2026-08-03T11:59Z; null before, and never backfilled, because the trader statistics it reads at insert were not kept for older rows) and trader.grade_at_trade with trader.grade_at_trade_status (from 2026-09-19T23:00Z; unknown before). CAPTURE RULES changed over the archive's life: rows before 2026-02-02 are sparse (at most a few hundred a month); from 2026-02-02 the floor was 3,000 USD (1.4% of rows through 2026-07-05 are smaller) and trades at any price were kept; from 2026-07-06 a trade is kept at 10,000 USD or more (1,000 USD in earnings markets) and only when priced below 0.97 (0.99 in earnings markets). Pass min_size=10000 for one size rule across the whole range; monthly row counts still follow the sports calendar. Until 2026-07-17 one match could be stored twice, once per wallet: from 2026-05-01 to 2026-07-17, 27.7% of rows at 10,000 USD or more share a transaction and market with another stored wallet, almost always a Yes buyer and a No buyer filled against each other. From 2026-07-18 a row is the taker's side only. Before 2026-05 the transaction hash is mostly absent, so the share cannot be measured there. 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, so a $10,000 print that lands in a market which has already traded tens of millions of shares is no longer kept; rows written before that date were not re-filtered. 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/large-trades/history

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. 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); rows written before that date were not re-filtered.

condition_idstring

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

traderstring

Trader wallet address, timestamp-suffixed wallet alias, username, or trd_-prefixed trader ID, 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 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 filter on trader.grade_at_trade instead. A means S or A, B means S, A or B.

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

X-Query-Validation'strict'

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.

If-None-Matchstring

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

Response

Historical large trade replay

object'list' required
has_moreboolean required
next_cursorstring
totalinteger

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

Changes

Changed in 6 of the 89 revisions of this API.818

  • 9d1ba37bd5e31See the full diff
    • ○

      added the required property to the response with the status

      response-required-property-added

  • 7e57bd9dc8b52See the full diff
    • ○

      added the new optional query request parameter min_market_volume_share

      new-optional-request-parameter

    • ○

      added the new optional query request parameter sort

      new-optional-request-parameter

  • ece7a25b7a4488See the full diff
    • ●

      added the new freshness_ceiling_unsatisfied enum value to the / response property for the response status

      response-property-enum-value-added

    • ●

      added the new freshness_ceiling_unsatisfied enum value to the / response property for the response status

      response-property-enum-value-added

    • ●

      added the new freshness_ceiling_unsatisfied enum value to the / response property for the response status

      response-property-enum-value-added

    • ●

      added the new freshness_ceiling_unsatisfied enum value to the / response property for the response status

      response-property-enum-value-added

    • ●

      added the new freshness_ceiling_unsatisfied enum value to the / response property for the response status

      response-property-enum-value-added

    • ●

      added the new freshness_ceiling_unsatisfied enum value to the / response property for the response status

      response-property-enum-value-added

    • ●

      added the new freshness_ceiling_unsatisfied enum value to the / response property for the response status

      response-property-enum-value-added

    • ●

      added the new freshness_ceiling_unsatisfied enum value to the / response property for the response status

      response-property-enum-value-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

  • a885dfbbeaff4See the full diff
    • ○

      response property data/items/recorded_signal_score deprecated

      response-property-deprecated

    • ○

      response property data/items/signal_score deprecated

      response-property-deprecated

    • ○

      added the required property // to the response with the status

      response-required-property-added

    • ○

      added the required property // to the response with the status

      response-required-property-added

  • 1901bfe7e90a2See the full diff
    • ○

      api tag Large trades added

      api-tag-added

    • ○

      api tag Whale Trades removed

      api-tag-removed

  • 8462acf80f8c1See the full diff
    • ○

      endpoint added

      endpoint-added

    This revision also has 3 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog