PnL breakdown for all traders in a specific Polymarket prediction market via Nansen analytics.
What it does
This endpoint returns profit-and-loss data for every trader in a given Polymarket prediction market. For each trader it includes net buy cost, sell proceeds, redemption value, unrealized position value, and total PnL in USD. Positions are computed from on-chain ERC-1155 token transfers and OrderFilled events on Polygon, with SAFE proxy wallet resolution to identify actual users.
The endpoint is part of Nansen's broader Prediction Markets API suite, which also covers OHLCV candles, orderbooks, top holders, trades, event/market screeners, and per-address PnL. It accepts a POST request with a required `market_id` parameter (the Polymarket market ID) plus optional pagination and sort parameters. Sorting is available on `total_pnl_usd`. The response includes per-trader rows with fields like `address`, `owner_address`, `side_held`, `net_buy_cost_usd`, `net_sell_proceeds_usd`, `redemption_value_usd`, `unrealized_value_usd`, `total_pnl_usd`, and `market_resolved`.
Pricing: $0.05 per call via x402 protocol, or 50 credits (free tier) / 5 credits (pro tier) via API key. The endpoint returned HTTP 402 on probe, confirming it is live and requires payment. Rate limits are enforced per-second and per-minute, reported via response headers.
Capabilities
Use cases
- —Identify the biggest winners and losers in a specific Polymarket prediction market
- —Analyze PnL distribution across all traders in a market
- —Assess unrealized value in open prediction market positions
- —Build dashboards showing trader performance for Polymarket events
- —Feed prediction market PnL data into trading bots or research pipelines
Fit
Best for
- —Quantitative researchers analyzing prediction market trader behavior
- —Dashboard builders integrating Polymarket analytics
- —AI agents needing per-market trader PnL breakdowns
- —Funds evaluating prediction market alpha
Not for
- —Real-time sub-second trading signals (data is on-chain event-based, not streaming)
- —Non-Polymarket prediction platforms (only Polymarket markets are supported)
- —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/pnl-by-market \
-H 'Content-Type: application/json' \
-H 'apiKey: YOUR_API_KEY' \
-d '{"market_id": "654412", "pagination": {"page": 1, "per_page": 10}}'Example
Request
{
"order_by": [
{
"field": "total_pnl_usd",
"direction": "DESC"
}
],
"market_id": "654412",
"pagination": {
"page": 1,
"per_page": 10
}
}Response
{
"data": [
{
"address": "0x1234567890abcdef1234567890abcdef12345678",
"event_id": "12345",
"question": "Will BTC reach $100k by end of 2025?",
"market_id": "654412",
"side_held": "Yes",
"event_title": "Bitcoin Price Milestones",
"owner_address": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
"total_pnl_usd": 5000,
"market_resolved": true,
"net_buy_cost_usd": 5000,
"redemption_value_usd": 8000,
"unrealized_value_usd": 0,
"net_sell_proceeds_usd": 2000
}
],
"pagination": {
"page": 1,
"per_page": 10,
"is_last_page": false
}
}Endpoint
Quality
Full OpenAPI 3.1 schema with detailed request/response models, clear pricing ($0.05/call via x402), and a confirmed live 402 probe response. Docs are embedded in the OpenAPI spec rather than a separate docs site, and no example responses were captured from the probe itself, but the schema is comprehensive enough to construct accurate examples.
Warnings
- —No separate documentation site found (api.nansen.ai/docs returns 404); all docs are from the OpenAPI spec.
- —Example response is synthesized from the schema, not captured from a live call.
Citations
- —Endpoint costs $0.05 per call via x402 and 50 credits (free) / 5 credits (pro) via API keyhttps://api.nansen.ai
- —PnL by market endpoint returns trader-level buy cost, sell proceeds, redemption value, unrealized value, and total PnLhttps://api.nansen.ai
- —Trades are decoded from on-chain OrderFilled events on Polygon with SAFE proxy wallet resolutionhttps://api.nansen.ai
- —Endpoint returned HTTP 402 confirming it is live and requires paymenthttps://api.nansen.ai/api/v1/prediction-market/pnl-by-market