Polymarket PnL by wallet address — per-market realized, unrealized, and total profit/loss via Nansen
What it does
This endpoint returns profit-and-loss data across all Polymarket prediction markets for a specific wallet address. For each market the address has traded, the response includes net buy cost, net sell proceeds, redemption value, unrealized value, total PnL in USD, and whether the market has resolved. Results are sortable by total_pnl_usd and paginated.
The endpoint is part of Nansen's broader Prediction Markets API suite, which covers Polymarket OHLCV candles, orderbooks, top holders, trades, market/event screeners, and per-market PnL. Data is derived from on-chain OrderFilled events and ERC-1155 token transfers on Polygon, with SAFE proxy wallet resolution. The API uses a credit-based system (10 credits on free tier, 1 on pro) and also supports pay-per-request at $0.01 via the x402 protocol. Rate limits are exposed via standard headers (per-second and per-minute windows). Authentication is via an `apiKey` header.
The full Nansen API (v1) spans smart money analytics, wallet profiling, token screening, Token God Mode flows, perpetual trading data on Hyperliquid, DeFi portfolio holdings, and an AI research agent — over 40 endpoints in total, most priced between $0.01 and $0.05 per call via x402.
Capabilities
Use cases
- —Evaluate a Polymarket trader's historical performance across all markets they've participated in
- —Identify which prediction markets a specific wallet has won or lost money on
- —Build leaderboards or dashboards of Polymarket trader profitability
- —Detect unrealized positions that a wallet still holds in open prediction markets
- —Audit a wallet's prediction market activity for research or compliance
Fit
Best for
- —Quantitative researchers analyzing Polymarket trader behavior
- —Bot agents that need per-wallet prediction market PnL data
- —Dashboard builders integrating Polymarket analytics
- —Traders evaluating counterparty track records on Polymarket
Not for
- —Real-time sub-second Polymarket price feeds (use orderbook/OHLCV endpoints instead)
- —Non-Polymarket prediction market platforms
- —General DeFi portfolio tracking unrelated to prediction markets
Quick start
curl -X POST https://api.nansen.ai/api/v1/prediction-market/pnl-by-address \
-H 'Content-Type: application/json' \
-H 'apiKey: YOUR_API_KEY' \
-d '{"address": "0x1234567890abcdef1234567890abcdef12345678", "pagination": {"page": 1, "per_page": 10}}'Example
Request
{
"address": "0x1234567890abcdef1234567890abcdef12345678",
"order_by": [
{
"field": "total_pnl_usd",
"direction": "DESC"
}
],
"pagination": {
"page": 1,
"per_page": 10
}
}Response
{
"data": [
{
"address": "0x1234567890abcdef1234567890abcdef12345678",
"event_id": "evt_001",
"question": "Will BTC reach $100k by end of 2025?",
"market_id": "654412",
"side_held": "Yes",
"event_title": "Bitcoin Price Milestones",
"total_pnl_usd": 150,
"market_resolved": false,
"net_buy_cost_usd": 500,
"redemption_value_usd": 0,
"unrealized_value_usd": 450,
"net_sell_proceeds_usd": 200
}
],
"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 info ($0.01/call), credit costs, and live 402 probe response. Response schema references are complete. Minor gap: no direct crawl of external docs page (docs path returned 404), but the OpenAPI spec itself is comprehensive.
Warnings
- —No external documentation page found (api.nansen.ai/docs returns 404); rely on OpenAPI spec only
- —Exact response field types for PnlByAddressItem are nullable (anyOf with null) — callers should handle null values
- —The MPP probe returned 402 but no parsed WWW-Authenticate challenge; payment is via x402 protocol per OpenAPI x-payment-info
Citations
- —Endpoint costs 10 credits (free) or 1 credit (pro) per call, or $0.01 via x402https://api.nansen.ai
- —PnL by address shows per-market PnL including buy costs, sell proceeds, and redemption values for a specific wallethttps://api.nansen.ai
- —Data is derived from on-chain OrderFilled events on Polygon with SAFE proxy wallet resolutionhttps://api.nansen.ai
- —API root returns {"message":"ok"} confirming the origin is livehttps://api.nansen.ai