Detailed per-token position data for all holders in a Polymarket prediction market.
What it does
This endpoint returns granular position details for every holder in a specific Polymarket prediction market. For each holder, it provides token balances, buy cost, sell proceeds, average entry price, current price, unrealized value, redemption value, and per-token PnL. Positions are computed from on-chain ERC-1155 token transfers on Polygon, with SAFE proxy wallet resolution to identify actual users.
The endpoint is part of Nansen's Prediction Markets API suite. It accepts a POST request with a required `market_id` parameter and optional pagination. The response includes per-holder, per-outcome position breakdowns with fields like `balance`, `avg_entry_price`, `current_price`, `unrealized_value_usd`, `token_pnl_usd`, and market metadata such as `event_id`, `event_title`, and `market_resolved` status.
Pricing is $0.05 per call via the x402 protocol, or 50 credits (free tier) / 5 credits (pro tier) when using a Nansen API key. The API uses standard pagination (up to 1000 records per page) and returns rate-limit headers. Authentication is via an `apiKey` header or x402 payment.
Capabilities
Use cases
- —Analyze exact positions and entry prices of all holders in a Polymarket market
- —Compare average entry price vs current price for each outcome token
- —Identify holders with the largest unrealized gains or losses
- —Track redemption values for resolved prediction markets
- —Build dashboards showing per-address position breakdowns for Polymarket events
Fit
Best for
- —Quantitative analysts tracking Polymarket position distributions
- —Trading bots needing per-holder position data for prediction markets
- —Researchers studying prediction market participant behavior
- —Portfolio trackers aggregating Polymarket positions
Not for
- —Real-time sub-second trading signals (data is on-chain derived, not streaming)
- —Non-Polymarket prediction platforms (only supports Polymarket on Polygon)
- —Users needing free unlimited access (each call costs $0.05 or credits)
Quick start
curl -X POST https://api.nansen.ai/api/v1/prediction-market/position-detail \
-H 'Content-Type: application/json' \
-H 'apiKey: YOUR_API_KEY' \
-d '{"market_id": "654412", "pagination": {"page": 1, "per_page": 10}}'Example
Request
{
"market_id": "654412",
"pagination": {
"page": 1,
"per_page": 10
}
}Response
{
"data": [
{
"address": "0x1234567890abcdef1234567890abcdef12345678",
"balance": 15000,
"outcome": "Yes",
"event_id": "12345",
"token_id": "71321045679252212",
"market_id": "654412",
"buy_tokens": 15000,
"event_title": "Example Event",
"sell_tokens": 0,
"buy_cost_usd": 7500,
"current_price": 0.65,
"outcome_index": 1,
"owner_address": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
"token_pnl_usd": 2250,
"avg_entry_price": 0.5,
"market_resolved": false,
"sell_proceeds_usd": 0,
"redemption_value_usd": 0,
"unrealized_value_usd": 9750
}
],
"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 payment challenge confirmed live (402 on HEAD), and explicit pricing ($0.05/call). Minor deduction because no direct example response was captured from the live endpoint and component schemas are referenced but not fully resolved inline.
Warnings
- —No crawled documentation pages were accessible beyond the API root health check; all /docs, /api, /pricing paths returned 404.
- —Response schema fields are inferred from the OpenAPI $ref to PositionDetailResponse/PositionDetailItem — actual live response not captured.
Citations
- —Endpoint returns per-token position data including balances, entry prices, current prices, and per-token PnL for Polymarket holdershttps://api.nansen.ai
- —Positions are computed from on-chain ERC-1155 token transfers on Polygon with SAFE proxy wallet resolutionhttps://api.nansen.ai
- —Pricing is $0.05 per call via x402 protocol, or 50 credits (free) / 5 credits (pro)https://api.nansen.ai
- —Endpoint returned HTTP 402 on HEAD probe confirming it is live and supports payment challengehttps://api.nansen.ai/api/v1/prediction-market/position-detail