Market Top Holders (Polymarket)
Top position holders in a single Polymarket market, ranked by current position size. Filter by outcome with side=yes|no. Each holder includes shares held and estimated current position value; per-wallet cost-basis PnL fields are not yet computed and are returned as null.
/v2/polymarket/market/{condition_id}/top-holdersQuery Parameters
Market condition ID — must match ^0x[0-9a-f]{64}$.
Optional. Filter by outcome side: 'yes' or 'no'. Omit for all holders.
Optional. Only return holders with at least this many shares.
Optional. When true, include total_count of matching holders. Default false.
Optional. Rows returned, ranked by size. 1–100, default 100.
Response Schema
Market condition ID (echoes the path).
Market title (null if not resolved).
Market slug for URL construction (null if not resolved).
Outcome side filter applied ('yes', 'no', or null for all).
Total holders matching the filters — only present when include_count=true.
Top holder rows, ranked by current position size (shares), descending.
Position in the list (1-indexed).
Holder wallet (Polymarket proxy wallet).
Outcome token ID held.
Shares currently held (normalized).
Estimated current value of the position (shares × current price). Null if a price is momentarily unavailable.
Outcome side of the position (Yes / No / outcome label).
Outcome index (0 for Yes/first outcome, 1 for No/second).
Average entry price. Not yet computed — returned as null (see _meta.unavailable_fields).
Realized PnL (USD). Not yet computed — returned as null.
Unrealized PnL (USD). Not yet computed — returned as null.
Total PnL (USD). Not yet computed — returned as null.
Number of trades. Not yet computed — returned as null.
Unix timestamp of first trade. Not yet computed — returned as null.
Unix timestamp of last trade. Not yet computed — returned as null.
Holder display pseudonym, if public.
Holder display name, if set.
Holder profile image URL, if set.
Whether the holder is a verified account.
Result window metadata.
Requested page size.
Number of entries returned.
Reserved for cursor pagination (currently null — results are a single ranked page).
True when more holders exist beyond the returned page.
Source, cache, and field-availability metadata.
Data source identifier.
Cache window in seconds.
Fields returned as null because they require per-wallet cost-basis accounting not yet computed by this endpoint.
Plain-language explanation of which fields are exact vs. not yet available.
Error Responses
All errors return the same envelope. The code field is stable and programmatically branchable; error and message are human-readable. errors[] is present only on validation failures with field-level detail. See the full error code reference →
Always `false` on error responses.
Short, human-readable title (e.g. 'Invalid API Key.').
Human-readable explanation for the error. Safe to surface in UIs.
Stable, hierarchical machine-readable code (e.g. 'validation.invalid_enum'). Use for programmatic handling.
Link to this code's entry in the Error Reference.
Optional. Present only on validation failures with field-level detail.
Name of the offending parameter.
Field-level machine code.
Human-readable explanation.
Authentication
API Key
To secure your requests, we strongly recommend passing your API key via the X-API-Key header. This prevents sensitive keys from being exposed in access logs or browser history.
X-API-Key: pmx_test_5e8f...Rate Limits
API rate limits are enforced based on the tier associated with your API key. Limits are tracked on two dimensions: requests per second and requests per month. Each completed request counts toward the global monthly quota. Separate endpoint-group monthly limits (matched markets, arbitrage, EV) only advance when the response body has success: true.
Usage is returned on responses via headers such as:
X-RateLimit-Limit-Second: 10X-RateLimit-Remaining-Second: 9X-RateLimit-Limit-Month: 1000X-RateLimit-Remaining-Month: 842Example (endpoint-group, when applicable)X-RateLimit-Limit-Arb-Month: 500X-RateLimit-Remaining-Arb-Month: 412If you exceed a rate limit, the API returns a 429 status with a Retry-After header indicating when you can resume.
Request
Live API Key
Parameters
Response
—Click EXECUTE to send a request →