Get top position holders for Polymarket prediction markets with entry prices, PnL, and whale positioning.
What it does
This endpoint returns the largest position holders for a specific Polymarket prediction market. Positions are computed from on-chain ERC-1155 token transfers on Polygon, with SAFE proxy wallet resolution to identify actual users. The response includes each holder's address, position size, average entry price, current price, unrealized PnL in USD, and which side (Yes/No) they hold.
The endpoint is part of Nansen's broader Prediction Markets API suite, which covers Polymarket analytics including OHLCV candles, orderbooks, trades, PnL leaderboards, and market/event screeners. It accepts a POST request with a JSON body containing a `market_id` (the Polymarket market identifier), optional pagination, and optional sort order (by position_size, unrealized_pnl_usd, or avg_entry_price). The endpoint costs 50 credits on the free tier or 5 credits on the pro tier per call, and also supports x402 pay-per-request at $0.05 per call. Rate limits are enforced per-second and per-minute, reported via response headers.
Capabilities
Use cases
- —Identify the biggest holders in a Polymarket prediction market to gauge whale sentiment
- —Analyze average entry prices and unrealized PnL of top holders to assess conviction levels
- —Monitor whether whales are positioned Yes or No on a specific market outcome
- —Build dashboards showing position concentration and distribution for prediction markets
- —Feed prediction market holder data into trading bots or research pipelines
Fit
Best for
- —Polymarket prediction market analysis
- —Whale and smart money position tracking on prediction markets
- —Quantitative research on prediction market holder behavior
Not for
- —Real-time sub-second trading signals (data is on-chain derived, not real-time orderbook)
- —Non-Polymarket prediction platforms (only Polymarket on Polygon is supported)
- —General token holder analysis (use Nansen's TGM holders endpoint instead)
Quick start
curl -X POST https://api.nansen.ai/api/v1/prediction-market/top-holders \
-H 'Content-Type: application/json' \
-H 'apiKey: YOUR_API_KEY' \
-d '{"market_id": "654412", "pagination": {"page": 1, "per_page": 10}, "order_by": [{"field": "position_size", "direction": "DESC"}]}'Example
Request
{
"order_by": [
{
"field": "position_size",
"direction": "DESC"
}
],
"market_id": "654412",
"pagination": {
"page": 1,
"per_page": 10
}
}Response
{
"data": [
{
"side": "Yes",
"address": "0x1234567890abcdef1234567890abcdef12345678",
"market_id": "654412",
"current_price": 0.52,
"outcome_index": 1,
"owner_address": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
"position_size": 15000,
"avg_entry_price": 0.45,
"unrealized_pnl_usd": 1050
}
],
"pagination": {
"page": 1,
"per_page": 10,
"is_last_page": false
}
}Endpoint
Quality
Full OpenAPI 3.1 schema with detailed request/response models, clear endpoint description, x402 pricing ($0.05/call), and credit costs documented. The 402 MPP challenge confirms the endpoint is live. Minor deduction because no actual response sample was captured from the probe (only schema-level examples) and crawled docs pages returned 404s.
Warnings
- —No dedicated documentation site was reachable (docs pages returned 404/route-not-found); all information derived from OpenAPI spec.
- —Response schema references TopHolder and TopHoldersResponse but full field-level examples are inferred from schema defaults, not live responses.
Citations
- —Endpoint costs 50 credits (free) or 5 credits (pro) per call, with x402 pay-per-request at $0.05https://api.nansen.ai
- —Positions are computed from on-chain ERC-1155 token transfers on Polygon with SAFE proxy wallet resolutionhttps://api.nansen.ai
- —Sortable by position_size, unrealized_pnl_usd, or avg_entry_pricehttps://api.nansen.ai
- —Endpoint returns 402 on HEAD request confirming it is live via MPP protocolhttps://api.nansen.ai/api/v1/prediction-market/top-holders