0X0xinsider
Markets

List a market's graded holders

Changed on

The graded holder roster of one market, the list a Pick of the Day shows for its market, for any Polymarket market: every S/A/B wallet with open shares on either outcome, from a complete provider holder scan, each with its shares, Polymarket's own currentValue for the leg, its grade, its win record in the market's category, and its badges. Both outcomes are listed; a wallet holding both is listed once on its net side. Ordered by current_value_usd DESC, then shares DESC, then address. The roster is computed at most once a minute per market and shared by every caller; a page is cut from that roster, so paging is cheap and total is exact. The route never widens past the graded cohort: scan.wallet_count reports every wallet the walk saw, graded or not. An incomplete, unstable or failed scan is a 503 with Retry-After, never a shorter list. A complete scan in which no S, A or B wallet holds either outcome is a 200 with an empty holders list and zero totals; retrying cannot change it. The cohort is S, A and B by the wallet's current grade (traders.latest_grade); a C, D, F or ungraded wallet is never listed here and appears only inside scan.wallet_count. A count here will not match GET /api/v1/positions for the same market, and the cohort is only one of three reasons: /positions reads the wallet_positions mirror rather than this live provider scan, and without a wallet its min_size defaults to 100 USD, so it drops the smaller legs this route keeps. Read a difference as all three, never as a grade count. This is current state and takes no as-of parameter: the roster is at most 60 s old over a provider walk at most 180 s old, and scan.fetched_at is the only timestamp on it. For a point-in-time roster, snapshot this route yourself on your own schedule; the one frozen roster the API serves is display_holders on GET /api/v1/pick-of-the-day, for that pick's market and backed side at publication.

get/api/v1/market/{condition_id}/holders

Request

Path parameters

condition_idstring required

Market condition ID. Accepts the raw provider-backed condition_id returned by /api/v1/markets/search or the mkt_-prefixed market.id emitted by V1 responses.

Query parameters

outcome'yes' | 'no' | 'all'

Keep holders netting one side. all (default) lists both.

min_grade'S' | 'A' | 'B'

Narrow within the graded cohort: S keeps S, A keeps S and A, B (default) keeps S, A and B. C, D and F are rejected with 400: the route lists the S/A/B cohort only. The cohort is the wallet's current grade (traders.latest_grade), so no value here reaches a C, D, F or ungraded holder; those are counted only in scan.wallet_count. min_grade=D on GET /api/v1/positions does return C and D, which is one of the three reasons the two routes' counts differ for the same market.

limitinteger

Maximum holders per page.

cursorstring

Opaque pagination cursor from the previous response's next_cursor. It encodes a page of one shared roster, so it stays valid across the roster's refresh, but a page read after a refresh can repeat or skip a holder.

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

One page of the market's graded holder roster.

object'list' required
has_moreboolean required
next_cursorstring

Absent on the last page.

totalinteger

Holders matching the request's outcome and min_grade filters across every page.

Changes

  • ece7a25b7a44Revision changes
    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

  • 8462acf80f8cRevision changes
    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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