{"uid":"cap_1bfFXGo0mmvXTC5iyhGJQ","slug":"api-nansen-ai-7bc68a17","name":"Nansen Prediction Market Top Holders","description":"Get Prediction Market Top Holders","url":"https://api.nansen.ai/api/v1/prediction-market/top-holders","method":"GET","headers":{},"bodySchema":{"type":"object","title":"TopHoldersRequest","required":["market_id"],"properties":{"sort":{"anyOf":[{"type":"array","items":{"type":"object","title":"SortOrder[TopHolderSortField]","required":["field","direction"],"properties":{"field":{"enum":["position_size","unrealized_pnl_usd","avg_entry_price"],"type":"string","title":"TopHolderSortField","description":"Sortable fields for top holders endpoint."},"direction":{"enum":["ASC","DESC"],"type":"string","title":"SortDirection","description":"Enum for sort directions."}}}}],"title":"Sort","description":"Deprecated: use 'order_by' instead."},"order_by":{"anyOf":[{"type":"array","items":{"type":"object","title":"SortOrder[TopHolderSortField]","required":["field","direction"],"properties":{"field":{"enum":["position_size","unrealized_pnl_usd","avg_entry_price"],"type":"string","title":"TopHolderSortField","description":"Sortable fields for top holders endpoint."},"direction":{"enum":["ASC","DESC"],"type":"string","title":"SortDirection","description":"Enum for sort directions."}}}}],"title":"Order By","examples":[[{"field":"position_size","direction":"DESC"}]],"description":"Sort order"},"market_id":{"type":"string","title":"Market Id","examples":["654412"],"maxLength":100,"minLength":1,"description":"Polymarket market ID"},"pagination":{"type":"object","title":"PaginationRequest","properties":{"page":{"type":"integer","title":"Page","default":1,"minimum":1,"description":"Page number (1-based)"},"per_page":{"type":"integer","title":"Per Page","default":10,"maximum":1000,"minimum":1,"description":"Number of records per page (max 1000)"}},"description":"Pagination parameters for API requests."}},"description":"Request for top holders endpoint.","additionalProperties":false},"responseSchema":{"type":"object","title":"TopHoldersResponse","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","title":"TopHolder","required":["market_id"],"properties":{"side":{"anyOf":[{"type":"string"}],"title":"Side","examples":["Yes"],"description":"Side held (Yes/No)"},"address":{"anyOf":[{"type":"string"}],"title":"Address","examples":["0x1234567890abcdef1234567890abcdef12345678"],"description":"Holder address (hex)"},"market_id":{"type":"string","title":"Market Id","examples":["654412"],"description":"Market ID"},"current_price":{"anyOf":[{"type":"number"}],"title":"Current Price","examples":[0.52],"description":"Current price"},"outcome_index":{"anyOf":[{"type":"integer"}],"title":"Outcome Index","examples":[1],"description":"Outcome index"},"owner_address":{"anyOf":[{"type":"string"}],"title":"Owner Address","examples":["0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"],"description":"SAFE proxy owner address (hex)"},"position_size":{"anyOf":[{"type":"number"}],"title":"Position Size","examples":[15000],"description":"Token position size"},"avg_entry_price":{"anyOf":[{"type":"number"}],"title":"Avg Entry Price","examples":[0.45],"description":"Average entry price"},"unrealized_pnl_usd":{"anyOf":[{"type":"number"}],"title":"Unrealized Pnl Usd","examples":[1050],"description":"Unrealized PnL in USD"}},"description":"Top holder data from ch_api_pm_top_holders."},"title":"Data","description":"List of top holder records"},"pagination":{"type":"object","title":"PaginationInfo","properties":{"page":{"type":"integer","title":"Page","default":1,"minimum":1,"description":"Current page number"},"per_page":{"type":"integer","title":"Per Page","default":10,"maximum":1000,"minimum":1,"description":"Number of records per page"},"is_last_page":{"type":"boolean","title":"Is Last Page","default":true,"description":"Whether this is the last page"}},"description":"Pagination information for API responses."}},"description":"Response for top holders endpoint."},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.05","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"settled","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.05/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.05","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.05","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_Pluzv-CvhfXcUPeiTGF3a","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.05","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns the largest position holders for a Polymarket prediction market, computed from on-chain data with Nansen wallet labels and smart money analytics.","exampleAgentPrompt":"Who are the top holders in the Polymarket prediction market for the 2024 US election — show me the biggest positions with any Nansen wallet labels or smart money flags.","exampleUseCases":null,"resultDescription":"A ranked list of the largest position holders in the specified Polymarket prediction market, including wallet addresses, position sizes computed from on-chain data, and Nansen entity labels identifying smart money, institutions, or notable wallets where available.","failureModes":["Invalid or unknown market ID returns an error or empty result","Market not indexed by Nansen returns no data","Malformed POST body causes 400 bad request","Rate limit or authentication failure returns 401/429","Very new markets may have incomplete on-chain data"],"whenToPreferThis":"Use this endpoint when you need to identify the dominant position holders in a specific Polymarket prediction market with enriched wallet intelligence (Nansen labels, smart money flags). Prefer this over generic on-chain queries when wallet entity labeling and ranking by position size is needed in one call.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T00:43:02.470Z","isFirstParty":false}