# Nansen Prediction Market Position Detail

> Nansen Prediction Market Position Detail 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 per-token position data for all holders in a specific Polymarket prediction market, including balances, entry prices, current prices, and PnL.

## Facts

- Endpoint: POST https://api.nansen.ai/api/v1/prediction-market/position-detail?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-position-detail-9e7f6e25
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_3TXaeL8EgihvZ776QVA9D

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-position-detail-9e7f6e25 -d '<json body>'
```

Example prompt: Show me all the holder positions for Polymarket market ID 654412 — I want to see each wallet's token balance, average entry price, current price, and their PnL in USD.

## When to prefer this

Use this endpoint when you need granular per-wallet, per-token position data for a specific Polymarket market — including entry price, current price, and individual PnL. Prefer this over market-level summary endpoints when you need to identify specific winning/losing wallets, analyze smart money positioning, or audit individual holder exposure in a prediction market.

## Known failure modes

- Invalid or non-existent market_id returns empty data array
- Market ID too long (>100 chars) or empty triggers validation error
- Pagination page/per_page out of range returns 422 validation error
- Payment not attached or insufficient USDC returns 402 Payment Required
- Rate limiting or API key issues return 401/403 errors
- Market with no holders returns empty data array

## How this service works

Get detailed per-token position data for all holders in a specific prediction market.
Includes token balances, entry prices, current prices, and per-token PnL.

**What it helps to answer:**

1. **What are the exact positions of each holder in this market?**
2. **What is the average entry price vs current price for each position?**
3. **How much has each token position gained or lost?**

## Output

An array of position records, one per holder-token combination in the market. Each record includes the holder address, token balance, outcome label (e.g. Yes/No), average entry price, current market price, token PnL in USD, total buy cost, sell proceeds, redemption value, and whether the market is resolved. Supports pagination up to 1000 records per page.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "title": "PositionDetailRequest",
 "required": [
  "market_id"
 ],
 "properties": {
  "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 position detail endpoint.",
 "additionalProperties": false
}
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "title": "PositionDetailResponse",
 "required": [
  "data"
 ],
 "properties": {
  "data": {
   "type": "array",
   "items": {
    "type": "object",
    "title": "PositionDetailItem",
    "required": [
     "market_id"
    ],
    "properties": {
     "address": {
      "anyOf": [
       {
        "type": "string"
       }
      ],
      "title": "Address",
      "description": "Holder address (hex)"
     },
     "balance": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Balance",
      "description": "Token balance"
     },
     "outcome": {
      "anyOf": [
       {
        "type": "string"
       }
      ],
      "title": "Outcome",
      "examples": [
       "Yes"
      ],
      "description": "Outcome label"
     },
     "event_id": {
      "anyOf": [
       {
        "type": "string"
       }
      ],
      "title": "Event Id",
      "description": "Parent event ID"
     },
     "token_id": {
      "anyOf": [
       {
        "type": "string"
       }
      ],
      "title": "Token Id",
      "description": "CLOB token ID"
     },
     "market_id": {
      "type": "string",
      "title": "Market Id",
      "examples": [
       "654412"
      ],
      "description": "Market ID"
     },
     "buy_tokens": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Buy Tokens",
      "description": "Total tokens bought"
     },
     "event_title": {
      "anyOf": [
       {
        "type": "string"
       }
      ],
      "title": "Event Title",
      "description": "Parent event title"
     },
     "sell_tokens": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Sell Tokens",
      "description": "Total tokens sold"
     },
     "buy_cost_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Buy Cost Usd",
      "description": "Total buy cost in USD"
     },
     "current_price": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Current Price",
      "description": "Current price"
     },
     "outcome_index": {
      "anyOf": [
       {
        "type": "integer"
       }
      ],
      "title": "Outcome Index",
      "examples": [
       1
      ],
      "description": "Outcome index"
     },
     "owner_address": {
      "anyOf": [
       {
        "type": "string"
       }
      ],
      "title": "Owner Address",
      "description": "SAFE proxy owner 
… (truncated)
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/nansen-position-detail-9e7f6e25/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)