{"uid":"cap_iMQ7tGcxbjuQ7hkiltqBj","slug":"nansen-top-holders-fde2870b","name":"Nansen Polymarket Top Holders","description":"Get the largest position holders for a Polymarket prediction market. Positions are\ncomputed from on-chain ERC-1155 token transfers on Polygon, with SAFE proxy wallet\nresolution to identify actual users.\n\n**What it helps to answer:**\n\n1. **Who are the biggest holders in this prediction market?**\n2. **What are the position sizes and entry prices of top holders?**\n3. **What is the unrealized PnL of major positions?**\n4. **Are whales positioned Yes or No?**","url":"https://api.nansen.ai/api/v1/prediction-market/top-holders?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","title":"TopHoldersRequest","required":["market_id"],"properties":{"sort":{"anyOf":[{"type":"array","items":{"type":"object","title":"TopHolderSortOrder","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","deprecated":true,"description":"Deprecated: use 'order_by' instead."},"order_by":{"anyOf":[{"type":"array","items":{"type":"object","title":"TopHolderSortOrder","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":["blockchain","smart-money","wallet","tokens","defi","analytics","profiler","dex","pnl","onchain","prediction-market","data"],"displayCostAmount":"0.05","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","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":"mpp","network":"tempo","amountUsd":"0.05","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"mpp","network":"tempo","amountUsd":"0.05","per":"call","confidence":"exact"},{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.05","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_LYi5QWzzv4AZifwLgGuBy","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0.05","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null},{"uid":"pm_idM-kJI6PJ9sj6PGVr1gF","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.05","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null}],"brandName":"Nansen","brandSlug":"nansen","brandBaseUrl":"https://nansen.ai","brandDocsUrl":"https://docs.nansen.ai","whatItDoes":"Returns the largest position holders for a Polymarket prediction market, including position sizes, average entry prices, and unrealized PnL, computed from on-chain ERC-1155 token transfers on Polygon.","exampleAgentPrompt":"Show me the top 20 holders for Polymarket market ID 654412, sorted by position size descending — I want to see who the biggest whales are, which side they're on, their average entry price, and their unrealized PnL.","exampleUseCases":[{"title":"Identify smart money positioning before market moves","prompt":"Pull the top 10 holders for that Trump election market and show me which side the biggest whales are betting on right now — I need their entry prices and current PnL to see if smart money is already locked in or still accumulating."},{"title":"Track largest position holders by profitability","prompt":"Find me the top holders in the Fed rate decision market sorted by unrealized PnL — I want to see who's winning big and what their average entry prices were, so I can understand where the smart money thesis is."},{"title":"Monitor whale accumulation patterns in emerging markets","prompt":"Show me the biggest 15 position holders for that new climate policy market, including their token amounts and entry prices — I'm trying to figure out if whales are quietly building positions before the market gains attention."}],"resultDescription":"A paginated list of top holders for the specified Polymarket market, each record including the holder's wallet address, resolved SAFE proxy owner address, which side (Yes/No) they hold, their token position size, average entry price, current market price, unrealized PnL in USD, and outcome index. Pagination metadata indicates current page and whether it's the last page.","failureModes":["Invalid or non-existent market_id returns empty data array","Missing required market_id field returns a validation error","Invalid sort field or direction enum values return a 422 validation error","Requesting a page beyond the last page returns an empty data array","Authentication failure (invalid API key) returns 401 or 403 error","Rate limiting may return 429 Too Many Requests"],"whenToPreferThis":"Use this endpoint when you need to identify the largest position holders in a specific Polymarket prediction market and want on-chain verified data with SAFE wallet resolution. Prefer this over generic blockchain explorers when you need aggregated position-level analytics (entry price, unrealized PnL, side) rather than raw transfers. Best when you want to track smart money positioning on Polymarket specifically.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-12T12:44:19.362Z","isFirstParty":false,"canonicalSlug":"nansen-top-holders-fde2870b"}