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://data-api.polymarket.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://data-api.polymarket.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://data-api.polymarket.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://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

{
  "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 a PublicClient or SecureClient.

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

Call get_resolutions() on an existing AsyncPublicClient or AsyncSecureClient.

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

Fetch resolution progress for the market:

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:

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:

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
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://data-api.polymarket.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://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
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://data-api.polymarket.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://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

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