> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xinsider.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> The Markdown of an API reference page leaves out the OpenAPI schema.
> Every object an endpoint returns or a webhook carries, with each field's type, presence and meaning, is on https://docs.0xinsider.com/api-reference/objects.md.
> The full OpenAPI 3.1 spec names each operation's and each webhook's exact parameters, request body and response schema: https://docs.0xinsider.com/api-reference/openapi.json.

# Market top holders

> List the largest holders on each side of a market, every grade and ungraded wallets included.

Use this endpoint to see the biggest positions in a market, whatever the wallet's grade. It lists up to 100 wallets per side, largest `shares` first, the same table the market's event page shows under Top holders.

For every S, A, and B wallet holding the market, from a complete Polymarket scan with exact counts, use [Market holders](https://docs.0xinsider.com/api-reference/endpoint/get-market-holders.md).

## Parameters

| Parameter | Description |
| - | - |
| `condition_id` | Polymarket's own id for the market, or the market's `mkt_` id. |
| `limit` | How many holders per side, from 1 to 100. The default is 20, and a value outside the range is clamped rather than refused. `totals` covers every holder in the sample whatever the limit. |

## Key response fields

| Field | Meaning |
| - | - |
| `data.yes`, `data.no` | The largest holders on each side, by `shares`. A wallet holding both sides is listed on each, with `other_outcome_shares` set. |
| `rank` | The holder's position on its side, from 1. |
| `grade` | The wallet's [grade](https://docs.0xinsider.com/concepts/grades.md), `S` to `F`. It is `null` for a wallet 0xinsider has not graded. |
| `current_value_usd` | What Polymarket says this position is worth right now, in USD. |
| `avg_entry_price` | The average price paid for the shares still held, from 0 to 1 (0.62 is 62 cents). |
| `position_realized_pnl`, `position_unrealized_pnl`, `position_total_pnl` | Polymarket's P\&L for this position, in USD. On a resolved market the unrealized figure is marked at the settlement price. |
| `in_scope_realized_pnl`, `in_scope_volume` | The wallet's realized P\&L and volume on sports and esports markets, the figures on its 0xinsider profile. They are `null` until 0xinsider has computed the wallet's record, never `0` in its place. |
| `category_win_rate`, `category_win_record`, `category_avg_price`, `category_win_rate_game` | The wallet's record in `market.category`, the same fields [Market holders](https://docs.0xinsider.com/api-reference/endpoint/get-market-holders.md) returns. They are present only when `category_win_rate_status` is `measured`. |
| `category_price_edge`, `category_scope_price_edge`, `category_price_edge_hold`, `category_scope_price_edge_hold` | The wallet's edge over the price it paid, in the category and in the game or league, or why the game page shows none. They are the same fields, from the same read, that [Market holders](https://docs.0xinsider.com/api-reference/endpoint/get-market-holders.md) returns, so a wallet on both carries the same figures. |
| `category_win_rate_status` | `measured` when the rate is present. `not_enough_data` when 0xinsider has the wallet on file and it has fewer than 5 decided markets in the category. `untracked` when 0xinsider has no record of the wallet, so nothing was measured: `grade`, `in_scope_realized_pnl` and `in_scope_volume` are `null` too. `unavailable` when a read failed; retry later. Absent when the market has no category. |
| `totals` | `yes_count`, `no_count`, `yes_shares` and `no_shares` over the whole sample, and `sample_cap`, the most holders the sample keeps per side (100). A count equal to `sample_cap` means that many or more. |
| `market.protocol_version` | The Polymarket protocol the market trades on: `v1` (CTF) or `v2` (Protocol V2), read from the market's condition id, the same value [`GET /api/v1/markets/settled`](https://docs.0xinsider.com/api-reference/endpoint/list-settled-markets) serves. On a `v2` market `token_id_yes` and `token_id_no` are Protocol V2 position ids. |
| `profiles_status` | `unavailable` when 0xinsider could not read the wallets' records for this sample. `in_scope_realized_pnl`, `in_scope_volume` and `strategy_type` are then `null` on every row because they were not read. |
| `computed_at` | When the sample was built. `meta.cache_age_s` says how old it is. It is absent when `profiles_status` is `unavailable`: that sample is built for your request and not kept. |
| `positions_as_of` | When 0xinsider last fetched Polymarket's holder board, the source of every row's position. It is up to 120 seconds before `computed_at` on an open market. It is absent on a resolved market, whose sample reads no live board, and when the fetch time could not be read. |
| `source_stale` | `true` when this is the market's last sample, sent after its 30 seconds were up while a new one builds. `positions_as_of` is then at most 300 seconds old. It is always `false` on a resolved market. |

## Freshness

The sample is shared with the event page and every caller. On an open market it is rebuilt at most every 30 seconds from Polymarket's holder board, which 0xinsider re-reads at most every 120 seconds, so a position is usually up to about 150 seconds old. `positions_as_of` says when the board was fetched, `computed_at` when the sample was built, and `meta.cache_age_s` how old the response is. On a resolved market the sample is at most 300 seconds old and carries no `positions_as_of`.

When a request arrives after the 30 seconds are up, you get the market's last sample with `source_stale: true` right away, and 0xinsider starts building a new one. That happens only while the sample's holder board is at most 300 seconds old. Request again a few seconds later for the new sample. Otherwise, for example on a market nobody has requested in the last few minutes, the request waits for the build, which can take a second or two.

## Example

```bash theme={null}
curl -H "Authorization: Bearer $OXINSIDER_API_KEY" \
  "https://api.0xinsider.com/api/v1/market/0x123.../top-holders?limit=100"
```

## What it does not return

* Every holder. Each side stops at 100 wallets, so a market with more holders shows its largest 100.
* Exact grade counts or USD by grade. [Market holders](https://docs.0xinsider.com/api-reference/endpoint/get-market-holders.md) has them for S, A, and B.
* An empty list in place of an error. When the holder data is busy or Polymarket's holder read fails, the route returns `503` with `error.reason` `read_model_warming` and a `Retry-After`.
* A market 0xinsider has no record of. That id returns `404`, and a market outside sports and esports is refused.
* Paging. There is no cursor: raise `limit` to 100 for the whole sample.

## Caching

Save the response's `ETag` and send it in `If-None-Match` on your next request. If the sample has not changed, the server returns `304 Not Modified` with no body.


## API Specification

The full API specification for this endpoint is available in the [documentation index](https://docs.0xinsider.com/llms.txt).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.