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:

if market.condition_id is None:
    raise RuntimeError("Market condition ID not found")

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.

TypeScript
Python
API

Call listTrades() on a PublicClient or SecureClient.

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

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

Output: Trade[]

type Trade = {
  side?: Side | null;
  conditionId?: CtfConditionId | null;
  size?: DecimalString | null;
  price?: DecimalString | null;
  timestamp?: EpochMilliseconds | null;
  title?: string | null;
  slug?: string | null;
  icon?: string | null;
  eventSlug?: string | null;
  outcome?: string | null;
  outcomeIndex?: number | null;
  name?: string | null;
  pseudonym?: string | null;
  bio?: string | null;
  profileImage?: string | null;
  profileImageOptimized?: string | null;
  transactionHash?: string | null;
  wallet?: Address | null;
  tokenId?: TokenId | 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",
    "tokenId": "7305630249804085635496399869905769372294302716159034447326228509068694952392"
  }
]

Call list_trades() on an AsyncPublicClient or AsyncSecureClient. The synchronous PublicClient and SecureClient provide the same method.

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

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

Output: tuple[Trade, ...]

class Trade:
    side: Literal["BUY", "SELL"] | None
    condition_id: CtfConditionId | None
    size: Decimal | None
    price: Decimal | None
    timestamp: datetime | None
    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
    transaction_hash: TransactionHash | None
    wallet: EvmAddress | None
    token_id: TokenId | None

[
  {
    "side": "SELL",
    "condition_id": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
    "size": "42.62",
    "price": "0.91",
    "timestamp": "2026-06-29T17:07:59Z",
    "title": "Will the US confirm that aliens exist before 2027?",
    "outcome": "No",
    "wallet": "0x50A0cebecFb81DbCbFA6d38F82040343F1E3D95F",
    "token_id": "7305630249804085635496399869905769372294302716159034447326228509068694952392"
  }
]

List recent trades for a market:

curl "https://data-api.polymarket.com/trades?market=$CONDITION_ID&limit=1"

The response contains the recent trades:

Response

[
  {
    "proxyWallet": "0x50A0cebecFb81DbCbFA6d38F82040343F1E3D95F",
    "side": "SELL",
    "asset": "7305630249804085635496399869905769372294302716159034447326228509068694952392",
    "conditionId": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
    "size": 42.62,
    "price": 0.91,
    "timestamp": 1782752879,
    "title": "Will the US confirm that aliens exist before 2027?",
    "outcome": "No"
  }
]

Open Interest

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

TypeScript
Python
API

Call listOpenInterest() on a PublicClient or SecureClient.

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

// openInterest: OpenInterest[]

Output: OpenInterest[]

type OpenInterest = {
  market?: Hash64 | null;
  value?: DecimalString | null;
};

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

Call get_open_interests() on an AsyncPublicClient or AsyncSecureClient. The synchronous PublicClient and SecureClient provide the same method.

open_interest = await client.get_open_interests(market=[condition_id])

# open_interest: tuple[OpenInterest, ...]

Output: tuple[OpenInterest, ...]

class OpenInterest:
    market: CtfConditionId | Literal["GLOBAL"] | None
    value: Decimal | None

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

Fetch open interest for a market:

curl "https://data-api.polymarket.com/oi?market=$CONDITION_ID"

The response contains open interest by market:

Response

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

Market Holders

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

TypeScript
Python
API

Call listMarketHolders() on a PublicClient or SecureClient.

const holders = await client.listMarketHolders({
  market: [conditionId],
  limit: 1,
});

// holders: MetaHolder[]

Output: MetaHolder[]

type Holder = {
  wallet?: Address | null;
  tokenId?: TokenId | null;
  amount?: DecimalString | null;
  outcomeIndex?: number | null;
  name?: string | null;
  pseudonym?: string | null;
  bio?: string | null;
  displayUsernamePublic?: boolean | null;
  profileImage?: string | null;
  profileImageOptimized?: string | null;
};

type MetaHolder = {
  token?: string | null;
  holders?: Holder[] | null;
};

[
  {
    "token": "107505882767731489358349912513945399560393482969656700824895970500493757150417",
    "holders": [
      {
        "wallet": "0xaf23273e03A924A257eDD6bEae7133CF9D32377f",
        "amount": "894254.445452",
        "outcomeIndex": 0,
        "name": "SCssss"
      }
    ]
  }
]

Call get_market_holders() on an AsyncPublicClient or AsyncSecureClient. The synchronous PublicClient and SecureClient provide the same method.

holders = await client.get_market_holders(market=[condition_id], limit=1)

# holders: tuple[MetaHolder, ...]

Output: tuple[MetaHolder, ...]

class Holder:
    wallet: EvmAddress | None
    token_id: TokenId | None
    amount: Decimal | None
    outcome_index: int | None
    name: str | None
    pseudonym: str | None
    bio: str | None
    display_username_public: bool | None
    profile_image: str | None
    profile_image_optimized: str | None

class MetaHolder:
    token: str | None
    holders: tuple[Holder, ...] | None

[
  {
    "token": "107505882767731489358349912513945399560393482969656700824895970500493757150417",
    "holders": [
      {
        "wallet": "0xaf23273e03A924A257eDD6bEae7133CF9D32377f",
        "amount": "894254.445452",
        "outcome_index": 0,
        "name": "SCssss"
      }
    ]
  }
]

List the largest holders for a market:

curl "https://data-api.polymarket.com/holders?market=$CONDITION_ID&limit=1"

The response groups holders by outcome token:

Response

[
  {
    "token": "107505882767731489358349912513945399560393482969656700824895970500493757150417",
    "holders": [
      {
        "proxyWallet": "0xaf23273e03A924A257eDD6bEae7133CF9D32377f",
        "amount": 894254.445452,
        "outcomeIndex": 0,
        "name": "SCssss"
      }
    ]
  }
]

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.

const liveVolume = await client.fetchEventLiveVolume({
  id: eventId,
});

// liveVolume: LiveVolume[]

Output: LiveVolume[]

type MarketVolume = {
  market?: Hash64 | null;
  value?: DecimalString | null;
};

type LiveVolume = {
  total?: DecimalString | null;
  markets?: MarketVolume[] | null;
};

[
  {
    "total": "60773073.437817",
    "markets": [
      {
        "market": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
        "value": "34909514.911729"
      },
      {
        "market": "0xa7962b12241616d83dcb8c70fc33aa0f48b1ec46a3ad6a23db21d3885dedc4cb",
        "value": "11192047.412956"
      },
      {
        "market": "0xcddc048c672ee233890b99b18885dbd510e3db3d67c53afb408ddc93f9aadff4",
        "value": "8741732.803805"
      },
      "..."
    ]
  }
]

Call get_event_live_volumes() on an AsyncPublicClient or AsyncSecureClient. The synchronous PublicClient and SecureClient provide the same method.

live_volume = await client.get_event_live_volumes(id=event_id)

# live_volume: tuple[LiveVolume, ...]

Output: tuple[LiveVolume, ...]

class MarketVolume:
    market: CtfConditionId | None
    value: Decimal | None

class LiveVolume:
    total: Decimal | None
    markets: tuple[MarketVolume, ...] | None

[
  {
    "total": "60773073.437817",
    "markets": [
      {
        "market": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
        "value": "34909514.911729"
      },
      {
        "market": "0xa7962b12241616d83dcb8c70fc33aa0f48b1ec46a3ad6a23db21d3885dedc4cb",
        "value": "11192047.412956"
      },
      {
        "market": "0xcddc048c672ee233890b99b18885dbd510e3db3d67c53afb408ddc93f9aadff4",
        "value": "8741732.803805"
      },
      "..."
    ]
  }
]

Fetch live volume for an event:

curl "https://data-api.polymarket.com/live-volume?id=$EVENT_ID"

The response contains total event volume and its market breakdown:

Response

[
  {
    "total": 60773073.437817,
    "markets": [
      {
        "market": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
        "value": 34909514.911729
      },
      {
        "market": "0xa7962b12241616d83dcb8c70fc33aa0f48b1ec46a3ad6a23db21d3885dedc4cb",
        "value": 11192047.412956
      },
      {
        "market": "0xcddc048c672ee233890b99b18885dbd510e3db3d67c53afb408ddc93f9aadff4",
        "value": 8741732.803805
      },
      "..."
    ]
  }
]

Trader Leaderboard

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

TypeScript
Python
API

Call listTraderLeaderboard() on a PublicClient or SecureClient.

const pages = client.listTraderLeaderboard({ period: "1d", pageSize: 1 });

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

Output: TraderLeaderboardEntry[]

type TraderLeaderboardEntry = {
  rank?: string | null;
  userName?: string | null;
  vol?: DecimalString | null;
  pnl?: DecimalString | null;
  wallet?: Address | null;
  profileImage?: string | null;
  xUsername?: string | null;
  verifiedBadge?: boolean | null;
};

[
  {
    "rank": "1",
    "userName": "NonceChaser",
    "vol": "89333.771517",
    "pnl": "193943.93458989085",
    "wallet": "0xb1Ca909E848CC24ec4E220CE1C453Bc290C51705"
  }
]

Call list_trader_leaderboard() on an AsyncPublicClient or AsyncSecureClient. The synchronous PublicClient and SecureClient provide the same method.

pages = client.list_trader_leaderboard(period="1d", page_size=1)

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

Output: tuple[TraderLeaderboardEntry, ...]

class TraderLeaderboardEntry:
    rank: str | None
    user_name: str | None
    vol: Decimal | None
    pnl: Decimal | None
    wallet: EvmAddress | None
    profile_image: str | None
    x_username: str | None
    verified_badge: bool | None

[
  {
    "rank": "1",
    "user_name": "NonceChaser",
    "vol": "89333.771517",
    "pnl": "193943.93458989085",
    "wallet": "0xb1Ca909E848CC24ec4E220CE1C453Bc290C51705"
  }
]

List the trader leaderboard for a period:

curl "https://data-api.polymarket.com/v1/leaderboard?period=1d&limit=1"

The response contains the ranked traders:

Response

[
  {
    "rank": "1",
    "proxyWallet": "0xb1Ca909E848CC24ec4E220CE1C453Bc290C51705",
    "userName": "NonceChaser",
    "vol": 89333.771517,
    "pnl": 193943.93458989085
  }
]

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.

const pages = client.listBuilderLeaderboard({ period: "1d", pageSize: 1 });

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

Output: LeaderboardEntry[]

type LeaderboardEntry = {
  rank?: string | null;
  builder?: string | null;
  volume?: DecimalString | null;
  activeUsers?: number | null;
  verified?: boolean | null;
  builderLogo?: string | null;
};

[
  {
    "rank": "1",
    "builder": "Gate",
    "volume": "5628007.453362993",
    "activeUsers": 11,
    "verified": true
  }
]

Call list_builder_leaderboard() on an AsyncPublicClient or AsyncSecureClient. The synchronous PublicClient and SecureClient provide the same method.

pages = client.list_builder_leaderboard(period="1d", page_size=1)

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

Output: tuple[LeaderboardEntry, ...]

class LeaderboardEntry:
    rank: str | None
    builder: str | None
    volume: Decimal | None
    active_users: int | None
    verified: bool | None
    builder_logo: str | None

[
  {
    "rank": "1",
    "builder": "Gate",
    "volume": "5628007.453362993",
    "active_users": 11,
    "verified": true
  }
]

List the builder leaderboard for a period:

curl "https://data-api.polymarket.com/v1/builders/leaderboard?period=1d&limit=1"

The response contains the ranked builders:

Response

[
  {
    "rank": "1",
    "builder": "Gate",
    "builderCode": "0x2c6624a23b16a2a69acd14c87b7fc03906870c851fa0a7b7f9d7be0fbbedea8a",
    "volume": 5628007.453362993,
    "activeUsers": 11,
    "verified": true
  }
]

Builder Volume

Track attributed builder volume and active users over time.

TypeScript
Python
API

Call fetchBuilderVolume() on a PublicClient or SecureClient.

const builderVolume = await client.fetchBuilderVolume({
  builder: "0x0000000000000000000000000000000000000000",
});

// builderVolume: BuilderVolumeEntry[]

Output: BuilderVolumeEntry[]

type BuilderVolumeEntry = {
  bucketAt?: IsoDateTimeString | null;
  builder?: string | null;
  builderLogo?: string | null;
  verified?: boolean | null;
  volume?: DecimalString | null;
  activeUsers?: number | null;
  rank?: string | null;
};

[
  {
    "bucketAt": "2026-06-29T00:00:00Z",
    "builder": "Gate",
    "volume": "5605762.113572997",
    "activeUsers": 11,
    "rank": "1"
  },
  {
    "bucketAt": "2026-06-29T00:00:00Z",
    "builder": "betmoar",
    "volume": "3888390.1247219997",
    "activeUsers": 168,
    "rank": "2"
  },
  {
    "bucketAt": "2026-06-29T00:00:00Z",
    "builder": "MagicMarkets",
    "volume": "1765982.109793",
    "activeUsers": 1,
    "rank": "3"
  },
  "..."
]

Call get_builder_volumes() on an AsyncPublicClient or AsyncSecureClient. The synchronous PublicClient and SecureClient provide the same method.

builder_volume = await client.get_builder_volumes(
    builder="0x0000000000000000000000000000000000000000",
)

# builder_volume: tuple[BuilderVolumeEntry, ...]

Output: tuple[BuilderVolumeEntry, ...]

class BuilderVolumeEntry:
    bucket_at: datetime | None
    builder: str | None
    builder_logo: str | None
    verified: bool | None
    volume: Decimal | None
    active_users: int | None
    rank: str | None

[
  {
    "bucket_at": "2026-06-29T00:00:00Z",
    "builder": "Gate",
    "volume": "5605762.113572997",
    "active_users": 11,
    "rank": "1"
  },
  {
    "bucket_at": "2026-06-29T00:00:00Z",
    "builder": "betmoar",
    "volume": "3888390.1247219997",
    "active_users": 168,
    "rank": "2"
  },
  {
    "bucket_at": "2026-06-29T00:00:00Z",
    "builder": "MagicMarkets",
    "volume": "1765982.109793",
    "active_users": 1,
    "rank": "3"
  },
  "..."
]

Fetch time-series volume for a builder:

curl "https://data-api.polymarket.com/v1/builders/volume?builder=0x0000000000000000000000000000000000000000"

The response contains builder activity by time bucket:

Response

[
  {
    "dt": "2026-06-29T00:00:00Z",
    "builder": "Gate",
    "builderCode": "0x2c6624a23b16a2a69acd14c87b7fc03906870c851fa0a7b7f9d7be0fbbedea8a",
    "volume": 5605762.113572997,
    "activeUsers": 11,
    "rank": "1"
  },
  {
    "dt": "2026-06-29T00:00:00Z",
    "builder": "betmoar",
    "builderCode": "0xceebf77a833b30520287ddd9478ff51abbdffa30aa90a8d655dba0e8a79ce0c1",
    "volume": 3888390.1247219997,
    "activeUsers": 168,
    "rank": "2"
  },
  {
    "dt": "2026-06-29T00:00:00Z",
    "builder": "MagicMarkets",
    "builderCode": "0xd1d9dd6983c40006b0dc8eab84a41ac9a4f27643296178479ffbebbc01ab7bde",
    "volume": 1765982.109793,
    "activeUsers": 1,
    "rank": "3"
  },
  "..."
]

Getting Started

Core Concepts

Market Data

Trading

Programs

Resources

Market Activity

Recent Trades

Open Interest

Market Holders

Event Live Volume

Trader Leaderboard

Builder Analytics

Builder Leaderboard

Builder Volume

​Market Activity

​Recent Trades

​Open Interest

​Market Holders

​Event Live Volume

​Trader Leaderboard

​Builder Analytics

​Builder Leaderboard

​Builder Volume

Market Activity

Recent Trades

Open Interest

Market Holders

Event Live Volume

Trader Leaderboard

Builder Analytics

Builder Leaderboard

Builder Volume