# Nansen Prediction Market Top Holders

> Nansen Prediction Market Top Holders is a paid API for AI agents from api.nansen.ai, paid per call via x402, $0.05/call, status unknown (last checked 2026-09-14).

Returns the largest position holders for a Polymarket prediction market, computed from on-chain data with Nansen wallet labels and smart money analytics.

## Facts

- Endpoint: GET https://api.nansen.ai/api/v1/prediction-market/top-holders
- Price: $0.05/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/api-nansen-ai-7bc68a17
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_1bfFXGo0mmvXTC5iyhGJQ

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 api-nansen-ai-7bc68a17
```

Example prompt: Who are the top holders in the Polymarket prediction market for the 2024 US election — show me the biggest positions with any Nansen wallet labels or smart money flags.

## When to prefer this

Use this endpoint when you need to identify the dominant position holders in a specific Polymarket prediction market with enriched wallet intelligence (Nansen labels, smart money flags). Prefer this over generic on-chain queries when wallet entity labeling and ranking by position size is needed in one call.

## Known failure modes

- Invalid or unknown market ID returns an error or empty result
- Market not indexed by Nansen returns no data
- Malformed POST body causes 400 bad request
- Rate limit or authentication failure returns 401/429
- Very new markets may have incomplete on-chain data

## How this service works

Get Prediction Market Top Holders

## Output

A ranked list of the largest position holders in the specified Polymarket prediction market, including wallet addresses, position sizes computed from on-chain data, and Nansen entity labels identifying smart money, institutions, or notable wallets where available.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "title": "TopHoldersRequest",
 "required": [
  "market_id"
 ],
 "properties": {
  "sort": {
   "anyOf": [
    {
     "type": "array",
     "items": {
      "type": "object",
      "title": "SortOrder[TopHolderSortField]",
      "required": [
       "field",
       "direction"
      ],
      "properties": {
       "field": {
        "enum": [
         "position_size",
         "unrealized_pnl_usd",
         "avg_entry_price"
        ],
        "type": "string",
        "title": "TopHolderSortField",
        "description": "Sortable fields for top holders endpoint."
       },
       "direction": {
        "enum": [
         "ASC",
         "DESC"
        ],
        "type": "string",
        "title": "SortDirection",
        "description": "Enum for sort directions."
       }
      }
     }
    }
   ],
   "title": "Sort",
   "description": "Deprecated: use 'order_by' instead."
  },
  "order_by": {
   "anyOf": [
    {
     "type": "array",
     "items": {
      "type": "object",
      "title": "SortOrder[TopHolderSortField]",
      "required": [
       "field",
       "direction"
      ],
      "properties": {
       "field": {
        "enum": [
         "position_size",
         "unrealized_pnl_usd",
         "avg_entry_price"
        ],
        "type": "string",
        "title": "TopHolderSortField",
        "description": "Sortable fields for top holders endpoint."
       },
       "direction": {
        "enum": [
         "ASC",
         "DESC"
        ],
        "type": "string",
        "title": "SortDirection",
        "description": "Enum for sort directions."
       }
      }
     }
    }
   ],
   "title": "Order By",
   "examples": [
    [
     {
      "field": "position_size",
      "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.
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "title": "TopHoldersResponse",
 "required": [
  "data"
 ],
 "properties": {
  "data": {
   "type": "array",
   "items": {
    "type": "object",
    "title": "TopHolder",
    "required": [
     "market_id"
    ],
    "properties": {
     "side": {
      "anyOf": [
       {
        "type": "string"
       }
      ],
      "title": "Side",
      "examples": [
       "Yes"
      ],
      "description": "Side held (Yes/No)"
     },
     "address": {
      "anyOf": [
       {
        "type": "string"
       }
      ],
      "title": "Address",
      "examples": [
       "0x1234567890abcdef1234567890abcdef12345678"
      ],
      "description": "Holder address (hex)"
     },
     "market_id": {
      "type": "string",
      "title": "Market Id",
      "examples": [
       "654412"
      ],
      "description": "Market ID"
     },
     "current_price": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Current Price",
      "examples": [
       0.52
      ],
      "description": "Current price"
     },
     "outcome_index": {
      "anyOf": [
       {
        "type": "integer"
       }
      ],
      "title": "Outcome Index",
      "examples": [
       1
      ],
      "description": "Outcome index"
     },
     "owner_address": {
      "anyOf": [
       {
        "type": "string"
       }
      ],
      "title": "Owner Address",
      "examples": [
       "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
      ],
      "description": "SAFE proxy owner address (hex)"
     },
     "position_size": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Position Size",
      "examples": [
       15000
      ],
      "description": "Token position size"
     },
     "avg_entry_price": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Avg Entry Price",
      "examples": [
       0.45
      ],
      "description": "Average entry price"
     },
     "unrealized_pnl_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Unrealized Pnl Usd",
      "examples": [
       1050
      ],
      "description": "Unrealized PnL in USD"
     }
    },
    "description": "Top holder data from ch_api_pm_top_holders."
   },
   "title": "Data",
   "description": "List of top holder records"
  },
  "pagination": {
   "type": "object",
   "title": "PaginationInfo",
   "properties": {
    "page": {
     "type": "integer",
     "title"
… (truncated)
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/api-nansen-ai-7bc68a17/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)