Analytics

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.

TypeScript
Python
API

Given a market, read its condition and event IDs:

const conditionId = market.conditionId;
const eventId = market.events[0].id;

Given a market, read its condition and event IDs:

condition_id = market.condition_id
event_id = market.events[0].id

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

{
  "conditionId": "<condition_id>",
  "events": [{ "id": "<event_id>" }]
}

Assign the identifiers for the requests below:

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
Python
API

Call listTrades() on a PublicClient or SecureClient.

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

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

Output: Trade[]

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;
};

[
  {
    "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"
  }
]

Call list_trades() on an existing AsyncPublicClient or AsyncSecureClient.

pages = client.list_trades(condition_id=[condition_id], page_size=1)

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

Output: Trade

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

{
  "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.

List recent trades for a market:

curl "https://pmdata.com-polybet-q05.com/v2/trades?condition=$CONDITION_ID&limit=1"

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

Response

{
  "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
Python
API

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).

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

// openInterest: OpenInterest[]

Output: OpenInterest[]

type OpenInterest = {
  conditionId: ConditionId | null;
  value: DecimalString;
};

[
  {
    "conditionId": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
    "value": "7484304.679057"
  }
]

Call get_open_interests() on an existing AsyncPublicClient or AsyncSecureClient.

open_interest = await client.get_open_interests()

# open_interest: tuple[OpenInterest, ...]

Output: OpenInterest

class OpenInterest:
    condition_id: ConditionId | None
    value: Decimal

{
  "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.

Fetch open interest for a market:

curl "https://pmdata.com-polybet-q05.com/v2/oi?condition=$CONDITION_ID"

The response contains open interest by market:

Response

{
  "data": [
    {
      "condition_id": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
      "value": 7113116.142022
    }
  ]
}

Market Holders

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

TypeScript
Python
API

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.

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

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

Output: MetaHolder[]

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[];
};

[
  {
    "assetId": "92338023949892178944669766466918011858071833335063600591564160751176113496073",
    "holders": [
      {
        "wallet": "0x1b5ca5e84705cd14ca9953b57434094cac726c0f",
        "amount": "1878.77239",
        "outcomeIndex": 0,
        "verified": false,
        "name": null
      }
    ]
  }
]

Call list_market_holders() on an existing AsyncPublicClient or AsyncSecureClient.

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

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

class MetaHolder:
    asset_id: ClobAssetId
    holders: tuple[Holder, ...]

{
  "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"
    }
  ]
}

List the largest holders for a market:

curl "https://pmdata.com-polybet-q05.com/v2/holders?condition=$CONDITION_ID&limit=1"

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

Response

{
  "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
Python
API

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

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

// liveVolume: LiveVolume

Output: LiveVolume

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[];
};

{
  "takerVolumeTotal": "698627.625937",
  "markets": [
    {
      "conditionId": "0x435620fa180dbedb59d34f164d82a447304436b57e87850ca3d1ab2070667006",
      "takerVolume": "631069.486412"
    },
    {
      "conditionId": "0xce67b495c754cd29548e0381d18e9b4701446fa9e32c29d7eec3e7e72ad55152",
      "takerVolume": "67558.139525"
    }
  ]
}

Call get_event_live_volume() on an existing AsyncPublicClient or AsyncSecureClient.

live_volume = await client.get_event_live_volume(event_ids=[int(event_id)])

# live_volume: LiveVolume

Output: LiveVolume

class MarketLiveVolume:
    condition_id: ConditionId | None
    taker_volume: Decimal

class LiveVolume:
    taker_volume_total: Decimal
    markets: tuple[MarketLiveVolume, ...]

{
  "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.

Fetch live volume for an event:

curl "https://pmdata.com-polybet-q05.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

{
  "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
Python
API

Call fetchResolutions() on an existing PublicClient or SecureClient. If needed, create a Public Client first.

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

Call get_resolutions() on an existing AsyncPublicClient or AsyncSecureClient. If needed, create a Public Client first.

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

Fetch resolution progress for the market:

curl "https://pmdata.com-polybet-q05.com/v2/resolutions?condition=$CONDITION_ID"

Illustrative response (fields trimmed):

Output: Resolutions

{
  "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.

TypeScript
Python
API

Call fetchTokenReferences() on an existing PublicClient or SecureClient. If needed, create a Public Client first.

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

Output: TokenReference[]

TokenReference Type

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:

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.

Call get_token_references() on an existing AsyncPublicClient or AsyncSecureClient. If needed, create a Public Client first. Sync clients expose the same method.

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, ...]

Output: TokenReference

TokenReference Type

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:

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.

Look up tokens by ID:

curl "https://pmdata.com-polybet-q05.com/v2/tokens?token_id=$TOKEN_ID,$OTHER_TOKEN_ID"

Example response:

Output: Token References

{
  "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:

curl "https://pmdata.com-polybet-q05.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.

TypeScript
Python
API

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.

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

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;
};

[
  {
    "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.

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

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;
};

{
  "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.

Call list_trader_leaderboard() on an existing AsyncPublicClient or AsyncSecureClient.

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

class TraderLeaderboardEntry:
    rank: int
    wallet: EvmAddress
    pnl: Decimal
    volume: Decimal
    user_name: str | None
    profile_image: str | None
    x_username: str | None
    verified: bool

{
  "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.

standing = await client.get_trader_leaderboard_standing(
    user="0x983eedfbd75803602e4a6e6ea9aab6dc6b9c6748",
    window="day",
)

# standing: TraderLeaderboardStanding | None

Output: TraderLeaderboardStanding

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

{
  "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.

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

curl "https://pmdata.com-polybet-q05.com/v2/leaderboard?time_period=day&limit=1"

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

Response

{
  "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
Python
API

Call listBiggestWinners() on a PublicClient or SecureClient.

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.

Call list_biggest_winners() on an existing AsyncPublicClient or AsyncSecureClient.

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.

List the largest wins resolved in the last day:

curl "https://pmdata.com-polybet-q05.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
Python
API

Call listBuilderLeaderboard() on a PublicClient or SecureClient.

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

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;
};

[
  {
    "rank": 1,
    "builderName": "betmoar",
    "builderCode": "0xceebf77a833b30520287ddd9478ff51abbdffa30aa90a8d655dba0e8a79ce0c1",
    "verified": true,
    "volume": "1994518.4590840002",
    "activeUsers": 150
  }
]

Call list_builder_leaderboard() on an existing AsyncPublicClient or AsyncSecureClient.

pages = client.list_builder_leaderboard(window="day", page_size=1)

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

Output: BuilderStanding

class BuilderStanding:
    rank: int
    builder_name: str
    builder_code: HexString
    profile_image: str | None
    verified: bool
    volume: Decimal
    active_users: int

{
  "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.

List the builder leaderboard for a time period:

curl "https://pmdata.com-polybet-q05.com/v2/builders/leaderboard?time_period=day&limit=1"

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

Response

{
  "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
Python
API

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.

import { BuilderVolumeInterval } from "@polymarket/client";

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

// builderVolume: BuilderVolumePoint[]

Output: BuilderVolumePoint[]

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;
};

[
  {
    "bucketDate": "2026-09-03",
    "rank": 1,
    "builderName": "betmoar",
    "builderCode": "0xceebf77a833b30520287ddd9478ff51abbdffa30aa90a8d655dba0e8a79ce0c1",
    "verified": true,
    "volume": "1990330.1396780002",
    "activeUsers": 150
  }
]

Call get_builder_volumes() on an existing AsyncPublicClient or AsyncSecureClient.

builder_volume = await client.get_builder_volumes(interval="day", bucket_limit=1)

# builder_volume: tuple[BuilderVolumePoint, ...]

Output: BuilderVolumePoint

class BuilderVolumePoint:
    rank: int
    builder_name: str
    builder_code: HexString
    profile_image: str | None
    verified: bool
    volume: Decimal
    active_users: int
    bucket_date: date

{
  "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.

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:

curl "https://pmdata.com-polybet-q05.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

{
  "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
    }
  ]
}

Getting Started

Core Concepts

Market Data

Trading

Programs

Migration Guides

Resources

Market Activity

Recent Trades

Open Interest

Market Holders

Event Live Volume

Market Resolution

Settlement Estimates

Token Lookup

Trader Leaderboard

Biggest Winners

Builder Analytics

Builder Leaderboard

Builder Volume

​Market Activity

​Recent Trades

​Open Interest

​Market Holders

​Event Live Volume

​Market Resolution

​Settlement Estimates

​Token Lookup

​Trader Leaderboard

​Biggest Winners

​Builder Analytics

​Builder Leaderboard

​Builder Volume

Market Activity

Recent Trades

Open Interest

Market Holders

Event Live Volume

Market Resolution

Settlement Estimates

Token Lookup

Trader Leaderboard

Biggest Winners

Builder Analytics

Builder Leaderboard

Builder Volume