Holders

Holders answers “who is in this event, and how are they doing?” Each row is one wallet’s position across an entire event — what they put in, what it’s worth, and their PnL — with the individual outcomes they hold nested inside the row. That nesting is what lets a client render a collapsed leaderboard and expand any trader to reveal the outcomes behind their number, without a second request.

Holders leaderboard ranked by total PnL, with a trader row expanded into per-outcome invested, PnL and ROI — One wallet expanded to show the six outcomes behind its event-level total.

Three views

Endpoint	Returns
`POST /api/v1/market-holders/all`	Every position, open and closed.
`POST /api/v1/market-holders/active`	Only currently-held positions.
`POST /api/v1/market-holders/closed`	Only exited positions.

They share a shape, but not every column appears on all three — currentValue is absent from closed, since an exited position has none. The table below marks where each column applies.

Columns

Column	Meaning
`userId`	The wallet.
`outcomes`	How many distinct outcomes this wallet holds in the event.
`invested`	Total USD put in.
`currentValue`	Current market value of what’s still held. (all, active)
`totalPnl`	Realized plus unrealized PnL, in USD.
`unrealizedPnl`	PnL on positions still open. (all only)
`pnlPercentage`	Return on investment, as a percentage.
`volume`	Total traded volume. (all, closed)
`tokenMetadata`	The per-outcome breakdown — see below.

Outcome-level detail

tokenMetadata is an array, one entry per outcome the wallet holds:

Field	Meaning
`tokenName`	The outcome’s name.
`isYesToken`	Whether this is the Yes side.
`avgBuyingPrice`	Average entry price.
`total_bought_shares`	Shares acquired.
`invested`	USD put into this outcome.
`totalPnl`	PnL on this outcome.
`unrealizedPnl`	PnL on the part still held. (all, active)
`pnlPercentage`	ROI on this outcome.
`volume`	Traded volume on this outcome.
`marketId`	The market this outcome belongs to.
`marketClosed`	Whether that market has closed.

Every value inside tokenMetadata is a string, including the numeric and boolean ones — "invested": "30740.5", "isYesToken": "true". Parse them before use. The top-level columns are properly typed; only this nested payload is string-encoded.

Scoping the query

Holders is always scoped to an event, so eventId is required.

{
  "page": { "limit": 50 },
  "filter": [
    { "field": "eventId", "operator": "eq", "value": 1234 }
  ],
  "orderBy": [{ "field": "totalPnl", "direction": "desc" }]
}

Omitting it returns 400.

Narrowing further

Beyond eventId, you can filter on userId, positionId, userRank, and the numeric measures — invested, totalPnl, unrealizedPnl, pnlPercentage, currentValue and volume. See Filtering for the syntax. Whales with a losing position, for example:

{
  "page": { "limit": 50 },
  "filter": [
    { "field": "eventId",  "operator": "eq",  "value": 1234 },
    { "field": "invested", "operator": "gte", "value": 100000 },
    { "field": "totalPnl", "operator": "lt",  "value": 0 }
  ],
  "orderBy": [{ "field": "invested", "direction": "desc" }]
}

Or restrict to a cohort of wallets you already track:

{
  "page": { "limit": 50 },
  "filter": [
    { "field": "eventId", "operator": "eq",       "value": 1234 },
    { "field": "userId",  "operator": "inCohort", "value": ["01HQ2K..."] }
  ]
}

Holders has no searchKey — it’s already scoped to one event, so there’s nothing to search across. Use the Activity endpoint to find an event by name first.

API endpoints

All Holders

POST /api/v1/market-holders/all

Active Holders

POST /api/v1/market-holders/active

Closed Holders

POST /api/v1/market-holders/closed

Getting Started

Features

Using the API

Three views

Columns

Outcome-level detail

Scoping the query

Narrowing further

API endpoints

All Holders

Active Holders

Closed Holders

​Three views

​Columns

​Outcome-level detail

​Scoping the query

​Narrowing further

​API endpoints

All Holders

Active Holders

Closed Holders

Three views

Columns

Outcome-level detail

Scoping the query

Narrowing further

API endpoints