---
title: "Get Prediction Market Position Detail"
method: POST
path: "/api/v1/prediction-market/position-detail"
tags: ["Prediction Markets"]
---

# Get Prediction Market Position Detail

`POST /api/v1/prediction-market/position-detail`

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?**

## Request body

- PositionDetailRequest — Request for position detail endpoint.
  - `market_id` string, required — Polymarket market ID
  - `pagination` PaginationRequest — Pagination parameters for API requests.
    - `page` integer — Page number (1-based)
    - `per_page` integer — Number of records per page (max 1000)

## Response `200`

Position detail data

- PositionDetailResponse — Response for position detail endpoint.
  - `pagination` PaginationInfo — Pagination information for API responses.
    - `page` integer — Current page number
    - `per_page` integer — Number of records per page
    - `is_last_page` boolean — Whether this is the last page
  - `data` PositionDetailItem[], required — List of position detail records
    - `address` string — Holder address (hex)
    - `owner_address` string — SAFE proxy owner address (hex)
    - `outcome` string — Outcome label
    - `outcome_index` integer — Outcome index
    - `token_id` string — CLOB token ID
    - `balance` number — Token balance
    - `buy_cost_usd` number — Total buy cost in USD
    - `buy_tokens` number — Total tokens bought
    - `sell_proceeds_usd` number — Total sell proceeds in USD
    - `sell_tokens` number — Total tokens sold
    - `avg_entry_price` number — Average entry price
    - `current_price` number — Current price
    - `unrealized_value_usd` number — Unrealized value in USD
    - `redemption_value_usd` number — Redemption value in USD
    - `token_pnl_usd` number — Token PnL in USD
    - `event_id` string — Parent event ID
    - `event_title` string — Parent event title
    - `market_resolved` boolean — Whether market is resolved
    - `market_id` string, required — Market ID

## Other responses

- `400` — Bad Request - Invalid request parameters or malformed request
- `401` — Authentication error - No API key found in request
- `402` — Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.
- `403` — Forbidden - User does not have required subscription tier or has exceeded credit limit
- `404` — Not Found - The requested resource was not found
- `422` — Validation error - Invalid request parameters
- `429` — Too Many Requests - Rate limit exceeded
- `500` — Internal Server Error - An unexpected error occurred

---

[API](https://skmtc.net/nansen/apis/nansen-api.md) · [All operations](https://skmtc.net/nansen/apis/nansen-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nansen/nansen-api/revisions/02a4d2e7d827/schema)