0X0xinsider
Large trades

List whale trades

Changed on

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

Request

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

  • 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