# Nansen Prediction Market PnL by Market

> Nansen Prediction Market PnL by Market is a paid API for AI agents from Nansen at api.nansen.ai, paid per call via MPP, $0.05/call, status unknown (last checked 2026-10-10).

Returns profit and loss breakdown for every trader in a specified Polymarket prediction market, including buy costs, sell proceeds, redemptions, and unrealized positions.

## Facts

- Endpoint: POST https://api.nansen.ai/api/v1/prediction-market/pnl-by-market?utm_source=zero.xyz
- Price: $0.05/call
- Payment: MPP
- Status: unknown
- Last checked: 2026-10-10
- 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-pnl-by-market-2dd804cf
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_vMePkXK5clWqNwl5cYlc2

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-pnl-by-market-2dd804cf -d '<json body>'
```

Example prompt: Show me the top 20 traders by total PnL in Polymarket market ID 654412, sorted from highest to lowest profit, so I can see who the biggest winners and losers are.

## When to prefer this

Use this endpoint when you need a full per-trader PnL breakdown for a specific Polymarket market — particularly when identifying top winners/losers, analyzing unrealized exposure, or building a trader leaderboard. Prefer this over general wallet PnL endpoints when the scope is a single prediction market and you need cross-trader comparison rather than a single wallet's history.

## Known failure modes

- Missing required market_id returns a 422 validation error
- Invalid or non-existent market_id returns an empty data array
- Pagination out of bounds returns empty results
- Per_page exceeding 1000 returns a validation error
- Payment not included or insufficient returns a 402 Payment Required response
- Malformed sort order object returns a 422 validation error

## How this service works

Get profit and loss breakdown for all traders in a specific prediction market.
Includes buy cost, sell proceeds, redemption values, and unrealized positions.

**What it helps to answer:**

1. **Who are the biggest winners and losers in this market?**
2. **What is the PnL distribution across traders?**
3. **How much unrealized value exists in open positions?**

## Output

A paginated list of trader-level PnL records for the specified market, each containing the trader wallet address, SAFE proxy owner address, total PnL in USD, net buy cost, net sell proceeds, redemption value, unrealized value, the side held (Yes/No/Both), the market question, event title, and whether the market is resolved.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "title": "PnlByMarketRequest",
 "required": [
  "market_id"
 ],
 "properties": {
  "order_by": {
   "anyOf": [
    {
     "type": "array",
     "items": {
      "type": "object",
      "title": "PnlByMarketSortOrder",
      "required": [
       "field",
       "direction"
      ],
      "properties": {
       "field": {
        "enum": [
         "total_pnl_usd"
        ],
        "type": "string",
        "title": "PnlByMarketSortField",
        "description": "Sortable fields for PnL by market endpoint."
       },
       "direction": {
        "enum": [
         "ASC",
         "DESC"
        ],
        "type": "string",
        "title": "SortDirection",
        "description": "Enum for sort directions."
       }
      }
     }
    }
   ],
   "title": "Order By",
   "examples": [
    [
     {
      "field": "total_pnl_usd",
      "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."
  }
 },
 "description": "Request for PnL by market endpoint.",
 "additionalProperties": false
}
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "title": "PnlByMarketResponse",
 "required": [
  "data"
 ],
 "properties": {
  "data": {
   "type": "array",
   "items": {
    "type": "object",
    "title": "PnlByMarketItem",
    "required": [
     "market_id"
    ],
    "properties": {
     "address": {
      "anyOf": [
       {
        "type": "string"
       }
      ],
      "title": "Address",
      "description": "Trader address (hex)"
     },
     "event_id": {
      "anyOf": [
       {
        "type": "string"
       }
      ],
      "title": "Event Id",
      "description": "Parent event ID"
     },
     "question": {
      "anyOf": [
       {
        "type": "string"
       }
      ],
      "title": "Question",
      "description": "Market question"
     },
     "market_id": {
      "type": "string",
      "title": "Market Id",
      "examples": [
       "654412"
      ],
      "description": "Market ID"
     },
     "side_held": {
      "anyOf": [
       {
        "type": "string"
       }
      ],
      "title": "Side Held",
      "examples": [
       "Yes"
      ],
      "description": "Side held: Yes, No, or Both. Reflects last known position even if fully exited (unrealized_value_usd = 0). Null only if no buy activity on record."
     },
     "event_title": {
      "anyOf": [
       {
        "type": "string"
       }
      ],
      "title": "Event Title",
      "description": "Parent event title"
     },
     "owner_address": {
      "anyOf": [
       {
        "type": "string"
       }
      ],
      "title": "Owner Address",
      "description": "SAFE proxy owner address (hex)"
     },
     "total_pnl_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Total Pnl Usd",
      "description": "Total PnL in USD"
     },
     "market_resolved": {
      "anyOf": [
       {
        "type": "boolean"
       }
      ],
      "title": "Market Resolved",
      "description": "Whether market is resolved"
     },
     "net_buy_cost_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Net Buy Cost Usd",
      "description": "Net buy cost in USD"
     },
     "redemption_value_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Redemption Value Usd",
      "description": "Redemption value in USD"
     },
     "unrealized_value_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Unrealized Value Usd",
      "description": 
… (truncated)
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/nansen-pnl-by-market-2dd804cf/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)