Sign in
Large trades

List whale trades

Returns recent large trades with signal scoring and persisted suspicion facts. Filter by size, category, trader grade, or persisted suspicion. Filters are applied before pagination, and every request uses SQL-backed limit + 1 pagination so has_more and next_cursor reflect the filtered result set. Cursor-paginated, newest first. Market categories come from provider-backed market_canonical identity. Deprecated alias of GET /api/v1/large-trades, 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

Query parameters

limitinteger

Maximum number of recent large trades to return.

cursorstring

Pagination cursor from previous response's next_cursor.

min_sizenumber

Minimum trade size in USD.

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). 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.

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 the last 30 days, because the share is computed for each request and an unbounded ranking cannot be served inside the documented latency budget. 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

List of whale trades

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 24 of the 89 revisions of this API.8247182

  • 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

  • 8462acf80f8c83See the full diff
    • ●

      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

  • 19386d595e054See 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

  • 1c5e270b412481See 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

  • 9958c95371de16See 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

  • 4bade829e22816See 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

  • 7b5489c2cd3e491See 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