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

# Analytics

> Understand activity and performance across Polymarket.

Use these reads to understand where trading activity is concentrated and how
traders and integrations perform over time.

## Market Activity

The examples below assume you already have a market object. To find or fetch
one, see [**Discover Markets**](/market-data/discover-markets).

**TypeScript**

Given a market, read its condition and event IDs:

```ts theme={null}
const conditionId = market.conditionId;
const eventId = market.events[0].id;
```

**Python**

Given a market, read its condition and event IDs:

```python theme={null}
condition_id = market.condition_id
event_id = market.events[0].id
```

**API**

Given a market object, its condition and event IDs are available in these
fields:

```json theme={null}
{
  "conditionId": "<condition_id>",
  "events": [{ "id": "<event_id>" }]
}
```

Assign the identifiers for the requests below:

```bash theme={null}
CONDITION_ID="<condition_id>"
EVENT_ID="<event_id>"
```

### Recent Trades

Review the trades recently matched in a market, including their side, price,
size, outcome, wallet, and timestamp. Trades are always returned in descending
timestamp order (newest first).

**TypeScript**

Call `listTrades()` on a `PublicClient` or `SecureClient`.

```ts theme={null}
const pages = client.listTrades({ conditionId: [conditionId], pageSize: 1 });

for await (const page of pages) {
  // page.items: Trade[]
}
```

> **Output: Trade\[]**
>
> ```ts Trade Type theme={null}
> type Trade = {
>   wallet: EvmAddress;
>   side: OrderSide;
>   assetId: TokenId | PositionId;
>   conditionId: ConditionId;
>   size: DecimalString;
>   price: DecimalString;
>   timestamp: EpochMilliseconds;
>   transactionHash: TxHash;
>   title?: string;
>   slug?: string;
>   icon?: string;
>   eventSlug?: string;
>   outcome?: string;
>   outcomeIndex?: number;
>   name?: string;
>   pseudonym?: string;
>   bio?: string;
>   profileImage?: string;
>   profileImageOptimized?: string;
> };
> ```
>
> ```json Trade Example theme={null}
> [
>   {
>     "side": "SELL",
>     "conditionId": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
>     "size": "42.62",
>     "price": "0.91",
>     "timestamp": 1782752879000,
>     "title": "Will the US confirm that aliens exist before 2027?",
>     "outcome": "No",
>     "wallet": "0x50a0cebecfb81dbcbfa6d38f82040343f1e3d95f",
>     "assetId": "7305630249804085635496399869905769372294302716159034447326228509068694952392",
>     "transactionHash": "0x4f3d2c1b0a9876543210fedcba9876543210fedcba9876543210fedcba987654"
>   }
> ]
> ```

**Python**

Call `list_trades()` on an existing `AsyncPublicClient` or `AsyncSecureClient`.

```python theme={null}
pages = client.list_trades(condition_id=[condition_id], page_size=1)

async for page in pages:
    # page.items: tuple[Trade, ...]
    pass
```

> **Output: Trade**
>
> ```python Trade Type theme={null}
> class Trade:
>     wallet: EvmAddress
>     asset_id: ClobAssetId
>     condition_id: ConditionId
>     side: OrderSide
>     size: Decimal
>     price: Decimal
>     timestamp: datetime
>     transaction_hash: TransactionHash
>     title: str | None
>     slug: str | None
>     icon: str | None
>     event_slug: str | None
>     outcome: str | None
>     outcome_index: int | None
>     name: str | None
>     pseudonym: str | None
>     bio: str | None
>     profile_image: str | None
>     profile_image_optimized: str | None
> ```
>
> ```json Trade Example theme={null}
> {
>   "wallet": "0x84cfffc3f16dcc353094de30d4a45226eccd2f63",
>   "asset_id": "100621704916396384184205224105871827982844371725320616822883322969092312254616",
>   "condition_id": "0xc8a2f17f42fa8493ebae503abec9d51efa7b57c3cc59a7b88933bffaa3618387",
>   "side": "BUY",
>   "size": "78.55",
>   "price": "0.62",
>   "timestamp": "2026-09-08T17:03:34Z",
>   "transaction_hash": "0x8b2fd0c7480cd78bd9f57e8b935cf10c6635d2c479c66ea26d358e1425f44a95",
>   "title": "Will Real Madrid CF win on 2026-09-08?",
>   "slug": "ucl-rma-int-2026-09-08-rma",
>   "icon": "https://polymarket-upload.s3.us-east-2.amazonaws.com/champions-league-pic-QIUFsL8vaDdq.png",
>   "event_slug": null,
>   "outcome": "Yes",
>   "outcome_index": null,
>   "name": "mooseborzoi",
>   "pseudonym": "Agitated-Bricklaying",
>   "bio": null,
>   "profile_image": "https://polymarket-upload.s3.us-east-2.amazonaws.com/profile-image-7634413-4dea3150-84ad-4278-9e45-d96e51769b7e.png",
>   "profile_image_optimized": null
> }
> ```

`size` is in shares and `price` is in USDC per share. To read a wallet's full trade history, pass `user=address, full_history=True`. Do not combine `full_history` with `start` or `end`.

**API**

List recent trades for a market:

```bash theme={null}
curl "https://data-api.polymarket.com/v2/trades?condition=$CONDITION_ID&limit=1"
```

The response contains the recent trades (row fields trimmed for brevity):

> **Response**
>
> ```json theme={null}
> {
>   "data": [
>     {
>       "proxy_wallet": "0xc6a5ceb4083f9209c31c45dc86f5714583f552e3",
>       "side": "SELL",
>       "token_id": "7305630249804085635496399869905769372294302716159034447326228509068694952392",
>       "condition_id": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
>       "size": 6.96,
>       "price": 0.962,
>       "timestamp": 1788204232,
>       "transaction_hash": "0x6929c40832394d64d84a0a9170c4174f9d9f18de23f82de05a750fdbf7350ca9",
>       "title": "Will the US confirm that aliens exist before 2027?",
>       "outcome": "No"
>     }
>   ],
>   "pagination": {
>     "limit": 1,
>     "offset": 0,
>     "has_more": true,
>     "next_cursor": "eyJkYXRhIjp7InR5cGUiOiJ0cmFkZXMi…"
>   }
> }
> ```

### Open Interest

Measure the value currently held in outstanding positions for one or more
markets.

**TypeScript**

Call `fetchOpenInterest()` on a `PublicClient` or `SecureClient`. Pass up
to 20 condition IDs, or omit `conditionIds` for the single global figure
(served as `conditionId: null`).

```ts theme={null}
const openInterest = await client.fetchOpenInterest({
  conditionIds: [conditionId],
});

// openInterest: OpenInterest[]
```

> **Output: OpenInterest\[]**
>
> ```ts OpenInterest Type theme={null}
> type OpenInterest = {
>   conditionId: ConditionId | null;
>   value: DecimalString;
> };
> ```
>
> ```json OpenInterest Example theme={null}
> [
>   {
>     "conditionId": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
>     "value": "7484304.679057"
>   }
> ]
> ```

**Python**

Call `get_open_interests()` on an existing `AsyncPublicClient` or `AsyncSecureClient`.

```python theme={null}
open_interest = await client.get_open_interests()

# open_interest: tuple[OpenInterest, ...]
```

> **Output: OpenInterest**
>
> ```python OpenInterest Type theme={null}
> class OpenInterest:
>     condition_id: ConditionId | None
>     value: Decimal
> ```
>
> ```json OpenInterest Example theme={null}
> {
>   "condition_id": null,
>   "value": "356037494.1056115"
> }
> ```

The result is a tuple of `OpenInterest` rows. Global open interest has `condition_id=None`. Pass `condition_ids=[condition_id]` to read a market’s open interest. Values are in USDC.

**API**

Fetch open interest for a market:

```bash theme={null}
curl "https://data-api.polymarket.com/v2/oi?condition=$CONDITION_ID"
```

The response contains open interest by market:

> **Response**
>
> ```json theme={null}
> {
>   "data": [
>     {
>       "condition_id": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
>       "value": 7113116.142022
>     }
>   ]
> }
> ```

### Market Holders

Find the largest public holders for each outcome in a market.

**TypeScript**

Call `listMarketHolders()` on a `PublicClient` or `SecureClient` and walk
the cursor pages. `pageSize` applies separately to each outcome token, so
merge groups by `assetId` across pages. Set `includePnl: true` (one
condition ID, page size at most 100) to add position economics to every
holder row.

```ts theme={null}
const pages = client.listMarketHolders({
  conditionIds: [conditionId],
  pageSize: 1,
});

for await (const page of pages) {
  // page.items: MetaHolder[]
}
```

> **Output: MetaHolder\[]**
>
> ```ts MetaHolder Type theme={null}
> type Holder = {
>   wallet: EvmAddress;
>   assetId: TokenId | PositionId;
>   /** Net holding in shares; per-side gross when `includePnl` is set. */
>   amount: DecimalString;
>   outcomeIndex: number | null;
>   verified: boolean;
>   name: string | null;
>   pseudonym: string | null;
>   bio: string | null;
>   displayUsernamePublic: boolean;
>   profileImage: string | null;
>   profileImageOptimized: string | null;
>   avgPrice?: DecimalString | null;
>   entryCostUsdc?: DecimalString | null;
>   currentPrice?: DecimalString | null;
>   currentValue?: DecimalString | null;
>   realizedPnl?: DecimalString | null;
>   unrealizedPnl?: DecimalString | null;
>   totalPnl?: DecimalString | null;
> };
>
> type MetaHolder = {
>   assetId: TokenId | PositionId;
>   /** Holders for this outcome, ordered by amount descending. */
>   holders: Holder[];
> };
> ```
>
> ```json MetaHolder Example theme={null}
> [
>   {
>     "assetId": "92338023949892178944669766466918011858071833335063600591564160751176113496073",
>     "holders": [
>       {
>         "wallet": "0x1b5ca5e84705cd14ca9953b57434094cac726c0f",
>         "amount": "1878.77239",
>         "outcomeIndex": 0,
>         "verified": false,
>         "name": null
>       }
>     ]
>   }
> ]
> ```

**Python**

Call `list_market_holders()` on an existing `AsyncPublicClient` or `AsyncSecureClient`.

```python theme={null}
pages = client.list_market_holders(condition_ids=[condition_id], page_size=1)

async for page in pages:
    # page.items: tuple[MetaHolder, ...]
    pass
```

`page_size` applies separately to each outcome asset. Merge groups across pages by `asset_id`. Set `include_pnl=True` to include position economics for one condition, with a page size of at most 100.

> **Output: MetaHolder**
>
> ```python Holder Type theme={null}
> class Holder:
>     wallet: EvmAddress
>     asset_id: ClobAssetId
>     amount: Decimal
>     outcome_index: int | None
>     display_username_public: bool
>     verified: bool
>     name: str | None
>     pseudonym: str | None
>     bio: str | None
>     profile_image: str | None
>     profile_image_optimized: str | None
>     avg_price: Decimal | None
>     entry_cost_usdc: Decimal | None
>     current_price: Decimal | None
>     current_value: Decimal | None
>     realized_pnl: Decimal | None
>     unrealized_pnl: Decimal | None
>     total_pnl: Decimal | None
> ```
>
> ```python MetaHolder Type theme={null}
> class MetaHolder:
>     asset_id: ClobAssetId
>     holders: tuple[Holder, ...]
> ```
>
> ```json MetaHolder Example theme={null}
> {
>   "asset_id": "92338023949892178944669766466918011858071833335063600591564160751176113496073",
>   "holders": [
>     {
>       "wallet": "0x1b5ca5e84705cd14ca9953b57434094cac726c0f",
>       "asset_id": "92338023949892178944669766466918011858071833335063600591564160751176113496073",
>       "amount": "1878.77239",
>       "outcome_index": 0,
>       "display_username_public": false,
>       "verified": false,
>       "name": null,
>       "pseudonym": null,
>       "bio": null,
>       "profile_image": null,
>       "profile_image_optimized": null,
>       "avg_price": "0.2794",
>       "entry_cost_usdc": "524.991",
>       "current_price": "1.0",
>       "current_value": "1878.7723",
>       "realized_pnl": "0.0001",
>       "unrealized_pnl": "1353.7812",
>       "total_pnl": "1353.7813"
>     }
>   ]
> }
> ```

**API**

List the largest holders for a market:

```bash theme={null}
curl "https://data-api.polymarket.com/v2/holders?condition=$CONDITION_ID&limit=1"
```

The response groups holders by outcome (holder fields trimmed for brevity):

> **Response**
>
> ```json theme={null}
> {
>   "data": [
>     {
>       "token_id": "107505882767731489358349912513945399560393482969656700824895970500493757150417",
>       "holders": [
>         {
>           "proxy_wallet": "0xcd09c7f5132a160b41578a79a9e3453da7aeda63",
>           "amount": 550253.927993,
>           "outcome_index": 0,
>           "name": "ShayaEredyon"
>         }
>       ]
>     },
>     {
>       "token_id": "7305630249804085635496399869905769372294302716159034447326228509068694952392",
>       "holders": [
>         {
>           "proxy_wallet": "0xa2cd4ccda9a1f95949df7a3355c4c2daa0642ba0",
>           "amount": 1455975.51944,
>           "outcome_index": 1,
>           "name": "0xA2cd4CcdA9A1f95949DF7A3355C4c2DAa0642Ba0-1729178570395"
>         }
>       ]
>     }
>   ],
>   "pagination": {
>     "limit": 1,
>     "offset": 0,
>     "has_more": true,
>     "next_cursor": "eyJkYXRhIjp7InR5cGUiOiJob2xkZXJzIi…"
>   }
> }
> ```

### Event Live Volume

Summarize activity across an event and break the volume down by market.

**TypeScript**

Call `fetchEventLiveVolume()` on a `PublicClient` or `SecureClient`. Pass
one or more event IDs; a list spans events and returns one combined
result.

```ts theme={null}
const liveVolume = await client.fetchEventLiveVolume({
  eventIds: [eventId],
});

// liveVolume: LiveVolume
```

> **Output: LiveVolume**
>
> ```ts LiveVolume Type theme={null}
> type MarketLiveVolume = {
>   /** Condition ID of the market, or `null` when the source row is unidentified. */
>   conditionId: ConditionId | null;
>   /** Cumulative one-side taker volume in shares. */
>   takerVolume: DecimalString;
> };
>
> type LiveVolume = {
>   /** Sum of every returned market's taker volume, in shares. */
>   takerVolumeTotal: DecimalString;
>   /** Markets ordered by taker volume descending. */
>   markets: MarketLiveVolume[];
> };
> ```
>
> ```json LiveVolume Example theme={null}
> {
>   "takerVolumeTotal": "698627.625937",
>   "markets": [
>     {
>       "conditionId": "0x435620fa180dbedb59d34f164d82a447304436b57e87850ca3d1ab2070667006",
>       "takerVolume": "631069.486412"
>     },
>     {
>       "conditionId": "0xce67b495c754cd29548e0381d18e9b4701446fa9e32c29d7eec3e7e72ad55152",
>       "takerVolume": "67558.139525"
>     }
>   ]
> }
> ```

**Python**

Call `get_event_live_volume()` on an existing `AsyncPublicClient` or `AsyncSecureClient`.

```python theme={null}
live_volume = await client.get_event_live_volume(event_ids=[int(event_id)])

# live_volume: LiveVolume
```

> **Output: LiveVolume**
>
> ```python MarketLiveVolume Type theme={null}
> class MarketLiveVolume:
>     condition_id: ConditionId | None
>     taker_volume: Decimal
> ```
>
> ```python LiveVolume Type theme={null}
> class LiveVolume:
>     taker_volume_total: Decimal
>     markets: tuple[MarketLiveVolume, ...]
> ```
>
> ```json LiveVolume Example theme={null}
> {
>   "taker_volume_total": "4439931.266595",
>   "markets": [
>     {
>       "condition_id": "0xe7f239d76b59c4e614f0bdb80467026da833083e38a31a27fde8e0907417ea12",
>       "taker_volume": "1057493.399838"
>     },
>     {
>       "condition_id": "0x4d162a40c3e3f458b0e0017485d7f9e6ead0cdd0573e38b26e0d5420525ccfa4",
>       "taker_volume": "780331.374022"
>     },
>     {
>       "condition_id": "0xc8929e80e74ae959b3ed9b9e1c5e0903ad38e02e1339462e3acf8b49bbca35a9",
>       "taker_volume": "588112.023677"
>     },
>     {
>       "condition_id": "0x02507350fc2b81c3af36c659a805adbda9b0a81e63a27b29cb273cdd7dbc072e",
>       "taker_volume": "576353.148052"
>     },
>     {
>       "condition_id": "0x626d0441b078eefbe2c49047960e7a3b6b4512c235507a2528ccc0f95f2474a6",
>       "taker_volume": "507319.025175"
>     },
>     {
>       "condition_id": "0xb4022c0b2718eca7ad27195f2d48f06527fa000269d188e1d3001ff8bbc16956",
>       "taker_volume": "479549.81298"
>     },
>     {
>       "condition_id": "0xc60022fe066abd6f96c375adb09f38d92c4931f09c10b805354581b4e5465e93",
>       "taker_volume": "313649.055908"
>     },
>     {
>       "condition_id": "0x4092815fea8f91e60586882d45fa2f61bfca8a36d595f47fdea9eec5d2893025",
>       "taker_volume": "137123.426943"
>     }
>   ]
> }
> ```

Pass one or more integer event IDs to get a combined result. `taker_volume_total` is total taker volume in shares. `markets` contains the per-market breakdown.

**API**

Fetch live volume for an event:

```bash theme={null}
curl "https://data-api.polymarket.com/v2/live-volume?event_id=$EVENT_ID"
```

The response contains the event's total taker volume and its market
breakdown (additional rows trimmed for brevity):

> **Response**
>
> ```json theme={null}
> {
>   "data": {
>     "taker_volume_total": 65834357.807271,
>     "conditions": [
>       {
>         "condition_id": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
>         "taker_volume": 37828643.727694
>       },
>       {
>         "condition_id": "0xa7962b12241616d83dcb8c70fc33aa0f48b1ec46a3ad6a23db21d3885dedc4cb",
>         "taker_volume": 11161362.976257
>       }
>     ]
>   }
> }
> ```

Markets are ordered by taker volume, largest first.

### Market Resolution

Check a market's resolution progress.

**TypeScript**

Call `fetchResolutions()` on a `PublicClient` or `SecureClient`.

```ts theme={null}
const resolutions = await client.fetchResolutions({
  conditionIds: [conditionId],
});

// resolutions: Resolution[]
```

Each row includes its `status` and `lastUpdatedAt`. `payouts` is present
when published. No matching resolution returns an empty array.

Settlement estimates use these optional fields on `Resolution`:

| Field | Type |
| - | - |
| `expectedSettlementTime` | `IsoDateTimeString` or `undefined` |
| `settlementTimeBasis` | `ResolutionSettlementTimeBasis` or `undefined` |

`expectedSettlementTime` is an ISO datetime string in UTC. The fields are
omitted when no estimate is available. Import `ResolutionSettlementTimeBasis`
from `@polymarket/client` to interpret the estimate:

| Enum member | Estimate |
| - | - |
| `ManagedProposalExpiration` | End of the managed UMA proposal's challenge window |
| `ProposalExpiration` | End of the ordinary UMA proposal's challenge window |
| `DvmRoundEstimate` | Earliest end of the UMA voting round the dispute can settle in |
| `Liveness` | Proposal time plus the Polymarket v2 oracle's liveness window |

**Python**

Call `get_resolutions()` on an existing `AsyncPublicClient` or `AsyncSecureClient`.

```python theme={null}
resolutions = await client.get_resolutions(condition_ids=[condition_id])

# resolutions: tuple[Resolution, ...]
```

Each row includes `status` and `last_updated_at`. `payouts` contains the published payouts when available. No matching resolution returns an empty tuple.

Settlement estimates use these fields on `Resolution`:

| Field | Type |
| - | - |
| `expected_settlement_time` | `datetime` or `None` |
| `settlement_time_basis` | `ResolutionSettlementTimeBasis` or `None` |

`expected_settlement_time` is a timezone-aware UTC `datetime`. The fields are
`None` when no estimate is available. Import `ResolutionSettlementTimeBasis`
from `polymarket` to interpret the estimate:

| Enum member | Estimate |
| - | - |
| `MANAGED_PROPOSAL_EXPIRATION` | End of the managed UMA proposal's challenge window |
| `PROPOSAL_EXPIRATION` | End of the ordinary UMA proposal's challenge window |
| `DVM_ROUND_ESTIMATE` | Earliest end of the UMA voting round the dispute can settle in |
| `LIVENESS` | Proposal time plus the Polymarket v2 oracle's liveness window |

**API**

Fetch resolution progress for the market:

```bash theme={null}
curl "https://data-api.polymarket.com/v2/resolutions?condition=$CONDITION_ID"
```

`data` contains resolution rows with `status` and `last_update_timestamp`, or
an empty list when no resolution matches. While a market waits on its oracle,
a row can carry the settlement estimate fields described below.

A row that is waiting on an oracle can carry `expected_settlement_time`
(RFC3339 UTC) and `settlement_time_basis`. Both are omitted whenever no
estimate applies, including settled markets and proposals under extended
review.

| `settlement_time_basis` | Row state | `expected_settlement_time` |
| - | - | - |
| `managed_proposal_expiration` | UMA proposal on the managed oracle, still in its challenge window | End of the challenge window |
| `proposal_expiration` | UMA proposal on the ordinary oracle, still in its challenge window | End of the challenge window |
| `dvm_round_estimate` | UMA proposal under dispute | Earliest end of the UMA voting round the dispute can settle in |
| `liveness` | Proposal on Polymarket's v2 oracle | Proposal time plus its liveness window |

#### Settlement Estimates

Treat an estimate as the earliest time the market can settle, not as a
deadline. A disputed vote can roll into a later voting round, and a proposal's
liveness window can already have elapsed while it awaits finalization.

No estimate is available for settled markets, proposals under extended review,
or markets that are still initialized or active.

### Token Lookup

Resolve ERC-1155 token ids to their market, outcome and neg-risk structure, or
list every token of a condition, in one call.

By token id, up to 50 per call, one row per known id in request order; unknown
ids are simply absent:

```bash theme={null}
curl "https://data-api.polymarket.com/v2/tokens?token_id=$TOKEN_ID,$OTHER_TOKEN_ID"
```

By condition, up to 10 selectors per call. A selector is any of the condition
ids the other routes carry: a ConditionalTokens condition id, a neg-risk market
id, a polymarket-v2 condition id (64 or 66 characters), or the on-chain event id
of a polymarket-v2 neg-risk structure. A neg-risk market id returns every market
of the structure in question order, so the rows line up with the structure's
question indexes:

```bash theme={null}
curl "https://data-api.polymarket.com/v2/tokens?condition=$NEG_RISK_MARKET_ID"
```

Each row carries `token_id`, `condition_id` (the 66-character id every other
route uses), `structural_condition_id` (the polymarket-v2 id in the same form,
null on ConditionalTokens tokens), `module` (`v1_ctf` for the ConditionalTokens
market; every other value is a polymarket-v2 module), `outcome_index`,
`clob_index`, `outcome`, `opposite_token_id`, `resolved` and `final_price` from
on-chain settlement, the market's `title`, `market_slug`, `closed`, `neg_risk`
and `neg_risk_market_id`, `question_index` inside a neg-risk structure, and the
market's `event_id` and `event_slug`. A request that sets both selectors, or
neither, returns `400`. The response is not paginated. The TypeScript and
Python SDKs do not expose this route yet; call it over HTTP.

## Trader Leaderboard

Compare trader volume and profit and loss over a selected period.

**TypeScript**

Call `listTraderLeaderboard()` on a `PublicClient` or `SecureClient`.
`window` defaults to one day, `category` to overall, and `sortBy` to PnL.
Tied traders share a rank and the next rank skips.

```ts theme={null}
import { LeaderboardWindow, TraderLeaderboardSort } from "@polymarket/client";

const pages = client.listTraderLeaderboard({
  window: LeaderboardWindow.Day,
  sortBy: TraderLeaderboardSort.Pnl,
  pageSize: 1,
});

for await (const page of pages) {
  // page.items: TraderLeaderboardEntry[]
}
```

> **Output: TraderLeaderboardEntry\[]**
>
> ```ts TraderLeaderboardEntry Type theme={null}
> type TraderLeaderboardEntry = {
>   /** Competition rank; ties share a rank and the next rank skips. */
>   rank: number;
>   wallet: EvmAddress;
>   /** PnL in USD for the selected window. */
>   pnl: DecimalString;
>   /** Both-sides traded volume in shares. */
>   volume: DecimalString;
>   userName: string | null;
>   profileImage: string | null;
>   xUsername: string | null;
>   verified: boolean;
> };
> ```
>
> ```json TraderLeaderboardEntry Example theme={null}
> [
>   {
>     "rank": 1,
>     "wallet": "0xfe787d2da716d60e8acff57fb87eb13cd4d10319",
>     "pnl": "372027.33333288063",
>     "volume": "3036239.1641930016",
>     "userName": "ferrariChampions2026",
>     "verified": false
>   }
> ]
> ```

Call `fetchTraderLeaderboardStanding()` on a `PublicClient` or
`SecureClient` to read one wallet's standing on both boards.

```ts theme={null}
const standing = await client.fetchTraderLeaderboardStanding({
  user: wallet,
  window: LeaderboardWindow.Day,
});

// standing: TraderLeaderboardStanding | null
```

When called on a `SecureClient`, `user` can be omitted and defaults to the
authenticated account's wallet.

> **Output: TraderLeaderboardStanding**
>
> ```ts TraderLeaderboardStanding Type theme={null}
> type TraderLeaderboardStanding = {
>   wallet: EvmAddress;
>   pnl: DecimalString;
>   volume: DecimalString;
>   pnlRank: number | null;
>   volumeRank: number | null;
>   userName: string | null;
>   profileImage: string | null;
>   xUsername: string | null;
>   verified: boolean;
> };
> ```
>
> ```json TraderLeaderboardStanding Example theme={null}
> {
>   "wallet": "0xfe787d2da716d60e8acff57fb87eb13cd4d10319",
>   "pnl": "420711.02199365385",
>   "volume": "3920263.4910460007",
>   "pnlRank": 1,
>   "volumeRank": 1,
>   "userName": "ferrariChampions2026",
>   "profileImage": null,
>   "xUsername": null,
>   "verified": false
> }
> ```

A `null` rank means the wallet is unranked on that board.

**Python**

Call `list_trader_leaderboard()` on an existing `AsyncPublicClient` or `AsyncSecureClient`.

```python theme={null}
pages = client.list_trader_leaderboard(window="day", sort_by="PNL", page_size=1)

async for page in pages:
    # page.items: tuple[TraderLeaderboardEntry, ...]
    pass
```

> **Output: TraderLeaderboardEntry**
>
> ```python TraderLeaderboardEntry Type theme={null}
> class TraderLeaderboardEntry:
>     rank: int
>     wallet: EvmAddress
>     pnl: Decimal
>     volume: Decimal
>     user_name: str | None
>     profile_image: str | None
>     x_username: str | None
>     verified: bool
> ```
>
> ```json TraderLeaderboardEntry Example theme={null}
> {
>   "rank": 1,
>   "wallet": "0x31e5d54aded22aa7cd80dbe9e33102abe2504879",
>   "pnl": "966725.5781960003",
>   "volume": "1491184.383039",
>   "user_name": "Noprajsk",
>   "profile_image": null,
>   "x_username": null,
>   "verified": false
> }
> ```

`pnl` is in USDC and `volume` is in shares. Tied traders share a rank and the next rank skips.

Call `get_trader_leaderboard_standing()` on an existing `AsyncPublicClient` or `AsyncSecureClient`.

```python theme={null}
standing = await client.get_trader_leaderboard_standing(
    user="0x983eedfbd75803602e4a6e6ea9aab6dc6b9c6748",
    window="day",
)

# standing: TraderLeaderboardStanding | None
```

> **Output: TraderLeaderboardStanding**
>
> ```python TraderLeaderboardStanding Type theme={null}
> class TraderLeaderboardStanding:
>     wallet: EvmAddress
>     pnl: Decimal
>     volume: Decimal
>     user_name: str | None
>     profile_image: str | None
>     x_username: str | None
>     verified: bool
>     pnl_rank: int | None
>     volume_rank: int | None
> ```
>
> ```json TraderLeaderboardStanding Example theme={null}
> {
>   "wallet": "0x7c3db723f1d4d8cb9c550095203b686cb11e5c6b",
>   "pnl": "957.4473660823187",
>   "volume": "64431.760178000004",
>   "user_name": "Car",
>   "profile_image": "https://polymarket-upload.s3.us-east-2.amazonaws.com/profile-image-501613-aa434e55-7732-41b1-9650-83a9d1d716ef.png",
>   "x_username": "CarOnPolymarket",
>   "verified": true,
>   "pnl_rank": 1045,
>   "volume_rank": 424
> }
> ```

`None` means no standing is available. A `None` rank means the wallet is unranked on that board. Secure clients default `user` to the authenticated wallet.

**API**

List the trader leaderboard for a time period. The board ranks by PnL by
default; pass `sort_by=VOLUME` for the volume board:

```bash theme={null}
curl "https://data-api.polymarket.com/v2/leaderboard?time_period=day&limit=1"
```

The response contains the ranked traders (row fields trimmed for brevity):

> **Response**
>
> ```json theme={null}
> {
>   "data": [
>     {
>       "rank": 1,
>       "user_id": "0x34dd4a4b70eaf79a17878f7938263c801d4dfd83",
>       "user_name": "vito3corleone",
>       "pnl": 470760.47323424,
>       "volume": 1485869.23,
>       "verified": false
>     }
>   ],
>   "pagination": {
>     "limit": 1,
>     "offset": 0,
>     "has_more": true,
>     "next_cursor": "eyJkYXRhIjp7InR5cGUiOiJsZWFkZXJib2FyZCI…"
>   }
> }
> ```

## Biggest Winners

Compare individual winning positions by their profit at resolution.

**TypeScript**

Call `listBiggestWinners()` on a `PublicClient` or `SecureClient`.

```ts theme={null}
import { LeaderboardWindow } from "@polymarket/client";

const pages = client.listBiggestWinners({
  window: LeaderboardWindow.Day,
  pageSize: 10,
});

for await (const page of pages) {
  // page.items: BiggestWinner[]
}
```

`window` selects the resolution period. Each row is one position. Check
`kind` before using `eventId`, which is `null` for Combos.

**Python**

Call `list_biggest_winners()` on an existing `AsyncPublicClient` or `AsyncSecureClient`.

```python theme={null}
pages = client.list_biggest_winners(window="day", page_size=10)

async for page in pages:
    # page.items: tuple[MarketBiggestWinner | ComboBiggestWinner, ...]
    pass
```

`window` selects the resolution period. Each row is one winning position. Check `kind` before accessing market-specific fields. `MarketBiggestWinner` identifies the asset with `asset_id` and includes `event_id`. `ComboBiggestWinner` uses `position_id`.

**API**

List the largest wins resolved in the last day:

```bash theme={null}
curl "https://data-api.polymarket.com/v2/biggest-winners?time_period=day&limit=10"
```

`data` contains one row per winning position. Continue with
`pagination.next_cursor` as `cursor` until it is `null`.

## Builder Analytics

Evaluate the reach of a builder integration through its attributed trading
activity.

### Builder Leaderboard

Compare builders by attributed volume and active users.

**TypeScript**

Call `listBuilderLeaderboard()` on a `PublicClient` or `SecureClient`.

```ts theme={null}
import { LeaderboardWindow } from "@polymarket/client";

const pages = client.listBuilderLeaderboard({
  window: LeaderboardWindow.Day,
  pageSize: 1,
});

for await (const page of pages) {
  // page.items: BuilderStanding[]
}
```

> **Output: BuilderStanding\[]**
>
> ```ts BuilderStanding Type theme={null}
> type BuilderStanding = {
>   rank: number;
>   /** Display name; use `builderCode` as the stable identifier. */
>   builderName: string;
>   builderCode: BuilderCode;
>   profileImage?: string;
>   verified: boolean;
>   /** Builder-attributed volume in shares. */
>   volume: DecimalString;
>   activeUsers: number;
> };
> ```
>
> ```json BuilderStanding Example theme={null}
> [
>   {
>     "rank": 1,
>     "builderName": "betmoar",
>     "builderCode": "0xceebf77a833b30520287ddd9478ff51abbdffa30aa90a8d655dba0e8a79ce0c1",
>     "verified": true,
>     "volume": "1994518.4590840002",
>     "activeUsers": 150
>   }
> ]
> ```

**Python**

Call `list_builder_leaderboard()` on an existing `AsyncPublicClient` or `AsyncSecureClient`.

```python theme={null}
pages = client.list_builder_leaderboard(window="day", page_size=1)

async for page in pages:
    # page.items: tuple[BuilderStanding, ...]
    pass
```

> **Output: BuilderStanding**
>
> ```python BuilderStanding Type theme={null}
> class BuilderStanding:
>     rank: int
>     builder_name: str
>     builder_code: HexString
>     profile_image: str | None
>     verified: bool
>     volume: Decimal
>     active_users: int
> ```
>
> ```json BuilderStanding Example theme={null}
> {
>   "rank": 1,
>   "builder_name": "betmoar",
>   "builder_code": "0xceebf77a833b30520287ddd9478ff51abbdffa30aa90a8d655dba0e8a79ce0c1",
>   "profile_image": "https://polymarket-upload.s3.us-east-2.amazonaws.com/betmoar_2.png",
>   "verified": true,
>   "volume": "3420022.424486001",
>   "active_users": 165
> }
> ```

Use `builder_code` as the stable identifier. `volume` is builder-attributed trading volume in shares.

**API**

List the builder leaderboard for a time period:

```bash theme={null}
curl "https://data-api.polymarket.com/v2/builders/leaderboard?time_period=day&limit=1"
```

The response contains the ranked builders (row fields trimmed for brevity):

> **Response**
>
> ```json theme={null}
> {
>   "data": [
>     {
>       "rank": 1,
>       "builder_name": "betmoar",
>       "builder_code": "0xceebf77a833b30520287ddd9478ff51abbdffa30aa90a8d655dba0e8a79ce0c1",
>       "verified": true,
>       "volume": 3001409.090169,
>       "active_users": 160
>     }
>   ],
>   "pagination": {
>     "limit": 1,
>     "offset": 0,
>     "has_more": true,
>     "next_cursor": "eyJkYXRhIjp7InR5cGUiOiJidWlsZGVyc19sZWFkZXJib2FyZCI…"
>   }
> }
> ```

### Builder Volume

Track attributed builder volume and active users over time.

**TypeScript**

Call `fetchBuilderVolume()` on a `PublicClient` or `SecureClient`.
`interval` picks the bucket width and `bucketLimit` counts the most recent
complete buckets (at most 90); every builder active in a bucket gets one
row.

```ts theme={null}
import { BuilderVolumeInterval } from "@polymarket/client";

const builderVolume = await client.fetchBuilderVolume({
  interval: BuilderVolumeInterval.Day,
  bucketLimit: 1,
});

// builderVolume: BuilderVolumePoint[]
```

> **Output: BuilderVolumePoint\[]**
>
> ```ts BuilderVolumePoint Type theme={null}
> type BuilderVolumePoint = {
>   /** UTC start date of the volume bucket. */
>   bucketDate: IsoCalendarDateString;
>   /** Builder rank within this bucket. */
>   rank: number;
>   /** Display name; use `builderCode` as the stable identifier. */
>   builderName: string;
>   builderCode: BuilderCode;
>   profileImage?: string;
>   verified: boolean;
>   /** Builder-attributed volume in shares for this bucket. */
>   volume: DecimalString;
>   activeUsers: number;
> };
> ```
>
> ```json BuilderVolumePoint Example theme={null}
> [
>   {
>     "bucketDate": "2026-09-03",
>     "rank": 1,
>     "builderName": "betmoar",
>     "builderCode": "0xceebf77a833b30520287ddd9478ff51abbdffa30aa90a8d655dba0e8a79ce0c1",
>     "verified": true,
>     "volume": "1990330.1396780002",
>     "activeUsers": 150
>   }
> ]
> ```

**Python**

Call `get_builder_volumes()` on an existing `AsyncPublicClient` or `AsyncSecureClient`.

```python theme={null}
builder_volume = await client.get_builder_volumes(interval="day", bucket_limit=1)

# builder_volume: tuple[BuilderVolumePoint, ...]
```

> **Output: BuilderVolumePoint**
>
> ```python BuilderVolumePoint Type theme={null}
> class BuilderVolumePoint:
>     rank: int
>     builder_name: str
>     builder_code: HexString
>     profile_image: str | None
>     verified: bool
>     volume: Decimal
>     active_users: int
>     bucket_date: date
> ```
>
> ```json BuilderVolumePoint Example theme={null}
> {
>   "rank": 1,
>   "builder_name": "betmoar",
>   "builder_code": "0xceebf77a833b30520287ddd9478ff51abbdffa30aa90a8d655dba0e8a79ce0c1",
>   "profile_image": "https://polymarket-upload.s3.us-east-2.amazonaws.com/betmoar_2.png",
>   "verified": true,
>   "volume": "3419926.8151110006",
>   "active_users": 165,
>   "bucket_date": "2026-09-08"
> }
> ```

The result is a tuple of calendar buckets. `bucket_limit` counts dates, not rows, and accepts at most 90. Each active builder has a row for that date. `volume` is in shares.

**API**

Fetch builder volume over time. Each row is one builder's volume in one
time bucket, with the builder's rank within that bucket; `limit` counts
the most recent buckets:

```bash theme={null}
curl "https://data-api.polymarket.com/v2/builders/volume?interval=day&limit=1"
```

The response contains builder activity by time bucket (row fields and
additional rows trimmed for brevity):

> **Response**
>
> ```json theme={null}
> {
>   "data": [
>     {
>       "date": "2026-08-31",
>       "rank": 1,
>       "builder_name": "betmoar",
>       "builder_code": "0xceebf77a833b30520287ddd9478ff51abbdffa30aa90a8d655dba0e8a79ce0c1",
>       "verified": true,
>       "volume": 2961462.652905,
>       "active_users": 160
>     },
>     {
>       "date": "2026-08-31",
>       "rank": 2,
>       "builder_name": "traderline",
>       "builder_code": "0x6b0e773fada0a2ec67c956b25a737d353a534ea33db56c717ba7854346c67984",
>       "verified": true,
>       "volume": 2445464.426092,
>       "active_users": 112
>     }
>   ]
> }
> ```


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