Large trades

Replay historical whale trades

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

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

Changed in 22 of the 89 revisions of this API.8250162

Sep 23, 20269d1ba37bd5e31See the full diff
- ○
  added the required property to the response with the status
  response-required-property-added
Sep 23, 20267e57bd9dc8b52See 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
Sep 23, 2026ece7a25b7a4488See 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
Sep 23, 2026a885dfbbeaff4See 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
Sep 23, 20268462acf80f8c133See the full diff
- ●
  the optional response header X-Effective-Query removed for the status 200
  optional-response-header-removed
- ●
  the optional response header X-Effective-Query removed for the status 304
  optional-response-header-removed
- ●
  the optional response header X-Query-Ignored removed for the status 200
  optional-response-header-removed
- ●
  the optional response header X-Query-Ignored removed for the status 304
  optional-response-header-removed
- ●
  deleted the header request parameter X-Query-Validation
  request-parameter-removed
- ●
  added the new export_expired enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new export_expired enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new export_expired enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new export_expired enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new export_expired enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new export_expired enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new export_expired enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new export_expired enum value to the / response property for the response status
  response-property-enum-value-added
- ○
  api tag Large trades added
  api-tag-added
- ○
  api tag Whale Trades removed
  api-tag-removed
- ○
  endpoint deprecated
  endpoint-deprecated
This revision also has 3 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Sep 22, 202619386d595e054See the full diff
- ○
  the response property // became required for the status
  response-property-became-required
- ○
  the response property // became required for the status
  response-property-became-required
- ○
  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
Sep 22, 20261c5e270b412481See the full diff
- ●
  added the new unknown_query_parameter enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unknown_query_parameter enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unknown_query_parameter enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unknown_query_parameter enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unknown_query_parameter enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unknown_query_parameter enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unknown_query_parameter enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unknown_query_parameter enum value to the / response property for the response status
  response-property-enum-value-added
- ○
  added the new optional header request parameter X-Query-Validation
  new-optional-request-parameter
Sep 22, 20269958c95371de16See the full diff
- ●
  added the new webhook_secret_rotation_not_prepared enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_not_prepared enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_not_prepared enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_not_prepared enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_not_prepared enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_not_prepared enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_not_prepared enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_not_prepared enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_overlap_active enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_overlap_active enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_overlap_active enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_overlap_active enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_overlap_active enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_overlap_active enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_overlap_active enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_overlap_active enum value to the / response property for the response status
  response-property-enum-value-added
Sep 22, 20264bade829e22816See the full diff
- ●
  added the new ip_rate_limited enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_rate_limited enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_rate_limited enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_rate_limited enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_rate_limited enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_rate_limited enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_rate_limited enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_rate_limited enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_throttled enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_throttled enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_throttled enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_throttled enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_throttled enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_throttled enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_throttled enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_throttled enum value to the / response property for the response status
  response-property-enum-value-added
Sep 22, 20267b5489c2cd3e491See the full diff
- ●
  added the new invalid_body enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_body enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_body enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_body enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_body enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_body enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_body enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_path enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_path enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_path enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_path enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_path enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_path enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_path enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_query enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_query enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_query enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_query enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_query enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_query enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_query enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new method_not_allowed enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new method_not_allowed enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new method_not_allowed enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new method_not_allowed enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new method_not_allowed enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new method_not_allowed enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new method_not_allowed enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new payload_too_large enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new payload_too_large enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new payload_too_large enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new payload_too_large enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new payload_too_large enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new payload_too_large enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new payload_too_large enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new request_timeout enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new request_timeout enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new request_timeout enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new request_timeout enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new request_timeout enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new request_timeout enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new request_timeout enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unsupported_media_type enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unsupported_media_type enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unsupported_media_type enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unsupported_media_type enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unsupported_media_type enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unsupported_media_type enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unsupported_media_type enum value to the / response property for the response status
  response-property-enum-value-added
- ○
  added the media type application/json for the response with the status
  response-media-type-added

Full history (22 revisions)