Concepts

​

Core Entities

​

Events

A top-level question or topic on Polymarket. An event contains one or more markets (outcomes). For example, “Who will win the 2024 US Presidential Election?” is an event, and the individual candidates are markets within it. Events can be filtered by status, category, tags, and series. They include aggregate trading metrics and metadata like whether they’re active, featured, or live.

​

Markets

A single tradeable outcome within an event. Each market has a binary yes/no structure with a price between 0 and 1 representing the implied probability. Markets are identified by their condition ID. For example, within the presidential election event, “Will Trump win?” is one market and “Will Harris win?” is another.

​

Series

A grouping of related events that recur over time. Weekly “Bitcoin price” events or a seasonal set of political events might be grouped into a series. Series can track external price feeds via Pyth or Chainlink integrations.

​

Tags

Labels used to categorize events by topic (e.g., “US Politics”, “Crypto”, “Sports”). Events can have multiple tags. Use tags to filter and discover events.

​

Trading Concepts

​

Shares

Tokenized units representing a claim on a specific outcome. If the outcome resolves to “Yes”, each share pays out 1 pUSD. If it resolves to “No”, each share is worth 0. The price of a share reflects the market’s implied probability.

​

Trades

An on-chain event on a market’s trade feed. The most common case is a buy or sell of outcome shares, which records the price, size, side, and the trader who executed it. The feed also covers position management and protocol payouts. The on-chain trade types: These are the actual on-chain trades. The trade feed also carries protocol lifecycle (oracle) events such as proposals, disputes, and resolutions. For the full discriminated union and per-variant fields, see Trade Types.

​

Volume

The total size of trades over a window. Struct payloads expose volume two ways: Polymarket’s UI labels volume as notional (the count of shares or contracts traded), which corresponds to shares_volume in Struct. usd_volume is the dollar value of those same trades. The two diverge because shares trade between 0 and 1 pUSD: 1,000 shares filled at 0.65 each is a shares_volume of 1,000 and a usd_volume of 650. Every metric stream (market, event, position, condition, tag) reports both, alongside builder-attributed counterparts (builder_usd_volume, builder_shares_volume) covering activity routed through builder-signed orders.

​

Bonds

A view of markets through a fixed-income lens. The bonds endpoint surfaces markets where the expected return and time-to-resolution create a yield-like profile, including APY (annualized percentage yield) and return percentage.

​

Candlesticks

Standard OHLCV (Open, High, Low, Close, Volume) price bars for charting a market’s price history. Available in resolutions from 1 minute to 1 day.

​

Holders

Traders who currently hold shares in a specific market outcome. The holders endpoint provides position sizes, average entry prices, and unrealized PnL.

​

Resolution

The process of determining the final outcome of a market. Once resolved, winning shares can be redeemed for 1 pUSD each. Markets can be resolved manually or automatically.

​

Identifiers

​

condition_id

The primary identifier for a market. Derived from Polymarket’s Conditional Token Framework (CTF) smart contracts on Polygon. Every endpoint that references a specific market uses this ID.

​

position_id

The token ID for a specific outcome within a market. Each outcome (e.g., “Yes” or “No”) has its own position ID, corresponding to an ERC-1155 token on Polygon. Used for candlestick queries and trade filtering.

​

slug

A URL-friendly, human-readable string used to identify events, markets, series, and tags. Example: will-bitcoin-hit-100k-by-december. Used as a path parameter in several endpoints.

​

Infrastructure Terms

​

pUSD and USDC.e

Polymarket settles trades in pUSD, its own dollar-pegged stablecoin issued on Polygon. pUSD is the active collateral for new trades, positions, and PnL across the platform. USDC.e (bridged USD Coin on Polygon) remains supported for legacy balances and on-ramps and still appears on accounts that haven’t migrated. Both are pegged 1:1 to the US Dollar, so monetary values are interchangeable in dollar terms. The accounts Websocket room exposes balances for both via separate pusd_update and usdce_update events so you can track holdings independently.

​

CLOB

Central Limit Order Book. Polymarket’s order-matching system that matches buy and sell orders at specific prices, as opposed to an AMM (Automated Market Maker).

​

Neg Risk

A framework for multi-outcome events where the sum of all outcome probabilities must equal 1. Buying “No” on one outcome is economically equivalent to buying “Yes” on all other outcomes. Used for events with more than two mutually exclusive outcomes.

​

PnL

Profit and Loss, calculated mark-to-market at the block level: a position’s value is the current market value of your shares minus what you paid, recomputed on every block. PnL reflects on-chain reality from the moment you buy, with no sell or resolution required.

• Unrealized PnL is the live paper profit/loss on shares you still hold, updated each block as the market price moves.
• Realized PnL is the locked-in result from reducing a position, settling on every sell, merge, or redemption.
• Total PnL combines the two into a single net figure (total_pnl_usd), the headline number for a wallet.

The figure folds in merges, splits, neg-risk conversions, redemptions, fees, maker rebates, rewards, and yield, so it is the actual economic outcome of holding a position rather than just price times shares minus cost. It is a more complete figure than Polymarket’s own display, which omits fees, rebates, rewards, and yield. This true net PnL is what the trader leaderboards rank on (by default total_pnl_usd), so a board reflects what traders have actually earned rather than how much they have traded. The global leaderboard and the per market, position, and category boards all share the same accounting, and a wallet’s standing always matches its own PnL summary. For worked examples, see the live trader PnL dashboard and PnL history charts guides.