# Nansen Polymarket Top Holders > Nansen Polymarket Top Holders is a paid API for AI agents from Nansen at api.nansen.ai, paid per call via MPP or x402, $0.05/call, status unknown (last checked 2026-10-12). 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. ## Facts - Endpoint: POST https://api.nansen.ai/api/v1/prediction-market/top-holders?utm_source=zero.xyz - Price: $0.05/call - Payment: MPP, x402 - Status: unknown - Last checked: 2026-10-12 - Activations on Zero: 0 - Provider: Nansen - Docs: https://docs.nansen.ai - Website: https://nansen.ai - Tags: blockchain, smart-money, wallet, tokens, defi, analytics, profiler, dex, pnl, onchain, prediction-market, data - Canonical page: https://www.zero.xyz/c/nansen-top-holders-fde2870b - Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_iMQ7tGcxbjuQ7hkiltqBj Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently. ## How to call it through Zero Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`): ```sh zero fetch --capability nansen-top-holders-fde2870b -d '' ``` Example prompt: 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. ## When to prefer this 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. ## Known failure modes - 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 ## How this service works Get the largest position holders for a Polymarket prediction market. Positions are computed from on-chain ERC-1155 token transfers on Polygon, with SAFE proxy wallet resolution to identify actual users. **What it helps to answer:** 1. **Who are the biggest holders in this prediction market?** 2. **What are the position sizes and entry prices of top holders?** 3. **What is the unrealized PnL of major positions?** 4. **Are whales positioned Yes or No?** ## Output 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. ## Request schema (JSON Schema) ```json { "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 … (truncated) ``` ## Response schema (JSON Schema) ```json { "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" … (truncated) ``` ## More - Live health (JSON, refreshed every minute): https://www.zero.xyz/c/nansen-top-holders-fde2870b/health.json - [Zero catalog index](https://www.zero.xyz/llms.txt) - [Other services from api.nansen.ai](https://www.zero.xyz/host/api.nansen.ai/llms.txt)