> ## 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**](https://docs.polymarket.com/market-data/discover-markets.md).

> [tab] TypeScript
>
> Given a market, read its condition and event IDs:
>
> ```ts theme={null}
> const conditionId = market.conditionId;
> const eventId = market.events[0].id;
> ```

> [tab] Python
>
> Given a market, read its condition and event IDs:
>
> ```python theme={null}
> condition_id = market.condition_id
> event_id = market.events[0].id
> ```

> [tab] 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).

> [tab] 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[]
> }
> ```
>
> > [accordion] 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"
> >   }
> > ]
> > ```

> [tab] 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
> ```
>
> > [accordion] 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`.

> [tab] 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):
>
> > [accordion] 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.

> [tab] 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[]
> ```
>
> > [accordion] Output: OpenInterest\[]
> >
> > ```ts OpenInterest Type theme={null}
> > type OpenInterest = {
> >   conditionId: ConditionId | null;
> >   value: DecimalString;
> > };
> > ```
> >
> > ```json OpenInterest Example theme={null}
> > [
> >   {
> >     "conditionId": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
> >     "value": "7484304.679057"
> >   }
> > ]
> > ```

> [tab] 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, ...]
> ```
>
> > [accordion] 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.

> [tab] 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:
>
> > [accordion] Response
> >
> > ```json theme={null}
> > {
> >   "data": [
> >     {
> >       "condition_id": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
> >       "value": 7113116.142022
> >     }
> >   ]
> > }
> > ```

### Market Holders

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

> [tab] 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[]
> }
> ```
>
> > [accordion] 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
> >       }
> >     ]
> >   }
> > ]
> > ```

> [tab] 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.
>
> > [accordion] 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"
> >     }
> >   ]
> > }
> > ```

> [tab] 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):
>
> > [accordion] 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.

> [tab] 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
> ```
>
> > [accordion] 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"
> >     }
> >   ]
> > }
> > ```

> [tab] 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
> ```
>
> > [accordion] 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.

> [tab] 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):
>
> > [accordion] 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.

> [tab] TypeScript
>
> Call `fetchResolutions()` on an existing `PublicClient` or `SecureClient`.
> If needed, [create a Public Client](https://docs.polymarket.com/getting-started/typescript.md#create-a-public-client) first.
>
> ```ts theme={null}
> const resolutions = await client.fetchResolutions({
>   conditionIds: [conditionId],
> });
>
> for (const resolution of resolutions) {
>   console.log(
>     resolution.status,
>     resolution.transactionHash,
>     resolution.logIndex,
>   );
> }
>
> // resolutions: Resolution[]
> ```
>
> Each row includes its `status` and `lastUpdatedAt`. `payouts` is present
> when published. No matching resolution returns an empty array.
>
> For UMA question lifecycle rows, `transactionHash` identifies the latest
> lifecycle transaction, while `logIndex` is the initial `RequestPrice` event's
> log index. They can belong to different transactions. Do not combine them as
> a log locator.
>
> This rule does not apply uniformly to every row. V2 condition-only rows can
> return `null` for both fields. CTF condition-resolution fallback rows instead
> carry the paired transaction and log index of the condition-resolution event.
>
> 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 |

> [tab] Python
>
> Call `get_resolutions()` on an existing `AsyncPublicClient` or `AsyncSecureClient`.
> If needed, [create a Public Client](https://docs.polymarket.com/getting-started/python.md#create-a-public-client) first.
>
> ```python theme={null}
> resolutions = await client.get_resolutions(condition_ids=[condition_id])
>
> for resolution in resolutions:
>     print(resolution.status, resolution.transaction_hash, resolution.log_index)
>
> # 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.
>
> For UMA question lifecycle rows, `transaction_hash` identifies the latest
> lifecycle transaction, while `log_index` is the initial `RequestPrice` event's
> log index. They can belong to different transactions. Do not combine them as
> a log locator.
>
> This rule does not apply uniformly to every row. V2 condition-only rows can
> return `None` for both fields. CTF condition-resolution fallback rows instead
> carry the paired transaction and log index of the condition-resolution event.
>
> 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 |

> [tab] API
>
> Fetch resolution progress for the market:
>
> ```bash theme={null}
> curl "https://data-api.polymarket.com/v2/resolutions?condition=$CONDITION_ID"
> ```
>
> Illustrative response (fields trimmed):
>
> > [accordion] Output: Resolutions
> >
> > ```json theme={null}
> > {
> >   "data": [
> >     {
> >       "condition_id": "0x02507350fc2b81c3af36c659a805adbda9b0a81e63a27b29cb273cdd7dbc072e",
> >       "status": "resolved",
> >       "transaction_hash": "0x1fc7a1df48dcac15859af515ebd77183c3487591181469a60dbf115b705f005a",
> >       "log_index": "170",
> >       "last_update_timestamp": "1785355919"
> >     }
> >   ]
> > }
> > ```
>
> `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.
>
> For UMA question lifecycle rows, `transaction_hash` identifies the latest
> lifecycle transaction, while `log_index` is the initial `RequestPrice` event's
> log index as a numeric string. They can belong to different transactions.
> Do not combine them as a log locator.
>
> V2 condition-only rows can return empty strings for both fields when provenance
> is unavailable. CTF condition-resolution fallback rows instead return the
> paired transaction and log index of the condition-resolution event.
>
> 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

Find the market and outcome for a token, or list all tokens of a condition in
one read.

> [tab] TypeScript
>
> Call `fetchTokenReferences()` on an existing `PublicClient` or `SecureClient`.
> If needed, [create a Public Client](https://docs.polymarket.com/getting-started/typescript.md#create-a-public-client) first.
>
> ```ts theme={null}
> const assetId =
>   "107505882767731489358349912513945399560393482969656700824895970500493757150417";
> const references = await client.fetchTokenReferences({ assetIds: [assetId] });
>
> for (const reference of references) {
>   console.log(reference.assetId, reference.outcome, reference.outcomeIndex);
> }
>
> // references: TokenReference[]
> ```
>
> > [accordion] Output: TokenReference\[]
> >
> > ```ts TokenReference Type theme={null}
> > type TokenReference = {
> >   assetId: ClobAssetId;
> >   conditionId: ConditionId;
> >   structuralConditionId: ConditionId | null;
> >   module: TokenModule;
> >   outcomeIndex: number;
> >   clobIndex: number | null;
> >   outcome: string | null;
> >   oppositeAssetId: ClobAssetId | null;
> >   resolved: boolean;
> >   finalPrice: DecimalString | null;
> >   title: string | null;
> >   marketSlug: string | null;
> >   closed: boolean | null;
> >   negRisk: boolean | null;
> >   negRiskMarketId: ConditionId | null;
> >   questionIndex: number | null;
> >   eventId: EventId | null;
> >   eventSlug: string | null;
> > };
> > ```
>
> `finalPrice` is the settled payout as a decimal string, or `null` when
> unavailable. Settlement data can take up to a minute to update.
>
> To look up a condition instead, supply only `conditionIds`:
>
> ```ts theme={null}
> const references = await client.fetchTokenReferences({
>   conditionIds: [conditionId],
> });
> ```
>
> Pass up to 50 `assetIds` or 10 `conditionIds`, not both. Results are not
> paginated. Unknown asset IDs are omitted.

> [tab] Python
>
> Call `get_token_references()` on an existing `AsyncPublicClient` or
> `AsyncSecureClient`. If needed,
> [create a Public Client](https://docs.polymarket.com/getting-started/python.md#create-a-public-client) first.
> Sync clients expose the same method.
>
> ```python theme={null}
> asset_id = "107505882767731489358349912513945399560393482969656700824895970500493757150417"
> references = await client.get_token_references(asset_ids=[asset_id])
>
> for reference in references:
>     print(reference.asset_id, reference.outcome, reference.outcome_index)
>
> # references: tuple[TokenReference, ...]
> ```
>
> > [accordion] Output: TokenReference
> >
> > ```python TokenReference Type theme={null}
> > class TokenReference(BaseModel):
> >     asset_id: ClobAssetId
> >     condition_id: ConditionId
> >     structural_condition_id: ConditionId | None
> >     module: TokenModule
> >     outcome_index: int
> >     clob_index: int | None
> >     outcome: str | None
> >     opposite_asset_id: ClobAssetId | None
> >     resolved: bool
> >     final_price: Decimal | None
> >     title: str | None
> >     market_slug: str | None
> >     closed: bool | None
> >     neg_risk: bool | None
> >     neg_risk_market_id: ConditionId | None
> >     question_index: int | None
> >     event_id: EventId | None
> >     event_slug: str | None
> > ```
>
> `final_price` is the settled payout as a `Decimal`, or `None` when
> unavailable. Settlement data can take up to a minute to update.
>
> To look up a condition instead, supply only `condition_ids`:
>
> ```python theme={null}
> references = await client.get_token_references(condition_ids=[condition_id])
> ```
>
> Pass up to 50 `asset_ids` or 10 `condition_ids`, not both. Results are not
> paginated. Unknown asset IDs are omitted.

> [tab] API
>
> Look up tokens by ID:
>
> ```bash theme={null}
> curl "https://data-api.polymarket.com/v2/tokens?token_id=$TOKEN_ID,$OTHER_TOKEN_ID"
> ```
>
> Example response:
>
> > [accordion] Output: Token References
> >
> > ```json theme={null}
> > {
> >   "data": [
> >     {
> >       "token_id": "123",
> >       "condition_id": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
> >       "structural_condition_id": null,
> >       "module": "v1_ctf",
> >       "outcome_index": 1,
> >       "clob_index": 0,
> >       "outcome": "Yes",
> >       "opposite_token_id": "124",
> >       "resolved": true,
> >       "final_price": 0.5,
> >       "title": "Example Market",
> >       "market_slug": "example-market",
> >       "closed": true,
> >       "neg_risk": false,
> >       "neg_risk_market_id": null,
> >       "question_index": null,
> >       "event_id": 1234,
> >       "event_slug": "example-event"
> >     }
> >   ]
> > }
> > ```
>
> To list all tokens for a condition:
>
> ```bash theme={null}
> curl "https://data-api.polymarket.com/v2/tokens?condition=$NEG_RISK_MARKET_ID"
> ```
>
> Use `token_id` (up to 50 IDs) or `condition` (up to 10 IDs), not both.
> Separate multiple IDs with commas. Results are not paginated. Unknown token
> IDs are omitted.

## Trader Leaderboard

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

> [tab] 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[]
> }
> ```
>
> > [accordion] 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.
>
> > [accordion] 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.

> [tab] 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
> ```
>
> > [accordion] 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
> ```
>
> > [accordion] 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.

> [tab] 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):
>
> > [accordion] 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.

> [tab] 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.

> [tab] 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`.

> [tab] 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.

> [tab] 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[]
> }
> ```
>
> > [accordion] 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
> >   }
> > ]
> > ```

> [tab] 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
> ```
>
> > [accordion] 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.

> [tab] 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):
>
> > [accordion] 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.

> [tab] 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[]
> ```
>
> > [accordion] 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
> >   }
> > ]
> > ```

> [tab] 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, ...]
> ```
>
> > [accordion] 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.

> [tab] 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):
>
> > [accordion] 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.