分析 - Polymarket Documentation

使用这些读取操作，了解交易活动集中在哪些市场，以及交易者和集成应用随时间推移的表现。

市场活动

以下示例假设你已经有一个市场对象。要查找或获取市场，请参阅 发现市场。

TypeScript
Python
API

给定一个市场，读取其条件 ID 和事件 ID：

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

给定一个市场，读取其条件 ID 和事件 ID：

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

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

给定一个市场对象，可以从以下字段获取其条件 ID 和事件 ID：

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

为下方请求设置这些标识符：

CONDITION_ID="<condition_id>"
EVENT_ID="<event_id>"

未平仓量

衡量一个或多个市场当前未平仓头寸中持有的价值。

TypeScript
Python
API

在 PublicClient 或 SecureClient 上调用 listOpenInterest()。

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

// openInterest: OpenInterest[]

输出：OpenInterest[]

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

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

在 AsyncPublicClient 或 AsyncSecureClient 上调用 get_open_interests()。同步的 PublicClient 和 SecureClient 也提供相同方法。

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

# open_interest: tuple[OpenInterest, ...]

输出：tuple[OpenInterest, ...]

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

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

获取某个市场的未平仓量：

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

响应包含按市场划分的未平仓量：

响应

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

市场持仓者

查找市场中每种结果代币的最大公开持仓者。

TypeScript
Python
API

在 PublicClient 或 SecureClient 上调用 listMarketHolders()。

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

// holders: MetaHolder[]

输出：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"
      }
    ]
  }
]

在 AsyncPublicClient 或 AsyncSecureClient 上调用 get_market_holders()。同步的 PublicClient 和 SecureClient 也提供相同方法。

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

# holders: tuple[MetaHolder, ...]

输出：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"
      }
    ]
  }
]

列出某个市场的最大持仓者：

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

响应按结果代币对持仓者分组：

响应

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

事件实时交易量

汇总一个事件的整体活动，并按市场细分交易量。

TypeScript
Python
API

在 PublicClient 或 SecureClient 上调用 fetchEventLiveVolume()。

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

// liveVolume: LiveVolume[]

输出：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"
      },
      "..."
    ]
  }
]

在 AsyncPublicClient 或 AsyncSecureClient 上调用 get_event_live_volumes()。同步的 PublicClient 和 SecureClient 也提供相同方法。

live_volume = await client.get_event_live_volumes(id=event_id)

# live_volume: tuple[LiveVolume, ...]

输出：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"
      },
      "..."
    ]
  }
]

获取某个事件的实时交易量：

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

响应包含事件总交易量及其市场明细：

响应

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

交易者排行榜

比较选定时间段内交易者的交易量和盈亏。

TypeScript
Python
API

在 PublicClient 或 SecureClient 上调用 listTraderLeaderboard()。

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

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

输出：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"
  }
]

在 AsyncPublicClient 或 AsyncSecureClient 上调用 list_trader_leaderboard()。同步的 PublicClient 和 SecureClient 也提供相同方法。

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

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

输出：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"
  }
]

列出某个时间段的交易者排行榜：

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

响应包含按排名排列的交易者：

响应

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

Builder 分析

通过归因到 Builder 集成的交易活动，评估其覆盖范围。

Builder 排行榜

根据归因交易量和活跃用户数比较各个 Builder。

TypeScript
Python
API

在 PublicClient 或 SecureClient 上调用 listBuilderLeaderboard()。

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

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

输出：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
  }
]

在 AsyncPublicClient 或 AsyncSecureClient 上调用 list_builder_leaderboard()。同步的 PublicClient 和 SecureClient 也提供相同方法。

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

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

输出：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
  }
]

列出某个时间段的 Builder 排行榜：

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

响应包含按排名排列的 Builder：

响应

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

Builder 交易量

跟踪归因到 Builder 的交易量和活跃用户数随时间的变化。

TypeScript
Python
API

在 PublicClient 或 SecureClient 上调用 fetchBuilderVolume()。

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

// builderVolume: BuilderVolumeEntry[]

输出：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"
  },
  "..."
]

在 AsyncPublicClient 或 AsyncSecureClient 上调用 get_builder_volumes()。同步的 PublicClient 和 SecureClient 也提供相同方法。

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

# builder_volume: tuple[BuilderVolumeEntry, ...]

输出：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"
  },
  "..."
]

获取某个 Builder 的时间序列交易量：

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

响应包含按时间桶划分的 Builder 活动：

响应

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

入门指南

核心概念

市场数据

交易

计划

资源

分析

市场活动

最近成交

未平仓量

市场持仓者

事件实时交易量

交易者排行榜

Builder 分析

Builder 排行榜

Builder 交易量

​市场活动

​最近成交

​未平仓量

​市场持仓者

​事件实时交易量

​交易者排行榜

​Builder 分析

​Builder 排行榜

​Builder 交易量

市场活动

最近成交

未平仓量

市场持仓者

事件实时交易量

交易者排行榜

Builder 分析

Builder 排行榜

Builder 交易量