Polymarket Concepts

Lifecycle Overview

Market

Polymarket has five concepts that are easy to confuse: market, event, series, slug, and token. A token is the lowest-level settleable asset. A market is the tradable question. An event organizes one or more related markets. A series is a broader collection that can group events across seasons, recurring themes, elections, tournaments, or long-running topics. A slug is a human-readable lookup key used in URLs and APIs.

A market is the smallest tradable unit. In the common binary case, it asks one concrete Yes/No question and has two outcome tokens. An event is the page-level container users often see in the Polymarket frontend. A slug is not a chain id and it is not the asset a wallet holds. The token is the actual result asset.

Series
- title: 2028 U.S. Presidential Election
- slug: us-presidential-election-2028

  Event
  - title: Who will win the 2028 U.S. presidential election?
  - slug: who-will-win-the-2028-us-presidential-election

    Market
    - question: Will Donald Trump win the 2028 U.S. presidential election?
    - slug: will-donald-trump-win-the-2028-us-presidential-election
    - conditionId: 0xabc...
    - token A: YES
    - token B: NO

Polymarket price history is not traditional OHLCV candle data. It is midpoint-oriented price history. Midpoint is the average of the current best bid and best ask. The frontend generally displays midpoint and falls back to last traded price when the spread is wider than $0.10. Live order book data is a separate layer, and Polymarket does not provide a complete official historical LOB archive.

OrderFilled

A trade is the execution-result view: it says which market traded, which outcome was involved, what side the taker took, what price was matched, what total size traded, and which maker orders were consumed.

OrderFilled is the on-chain fill-event view. When execution is settled through the Exchange contract, the contract emits fill-level events with orderHash, maker, taker, makerAssetId, takerAssetId, makerAmountFilled, takerAmountFilled, and fee. In short: trade is the execution receipt; OrderFilled is the fill-level ledger.

Aggregated trade:
- side: BUY
- price: 0.52
- size: 100
- maker_orders: A 30, B 20, C 50

OrderFilled rows:
- A_SELL filled for 30
- B_SELL filled for 20
- C_SELL filled for 50

Maker and taker are roles in a specific execution, not permanent user categories. Order, trade, fill, and transaction are also separate layers: an order is the instruction, a trade is the matching result, OrderFilled is the chain-level fill event, and a transaction is the blockchain settlement record.

Oracle

Oracle data explains how a market leaves the trading phase and becomes a settled outcome. Price alone does not prove settlement. The oracle layer records what answer was requested, what was proposed, whether the proposal was disputed, and what finally settled.

Many Polymarket markets resolve through UMA-related adapter and oracle contracts. The lifecycle can include question initialization, request, proposal, dispute, and settlement. polyData stores transaction hashes, log indexes, block numbers, event times, proposed prices, settled prices, participants, and matching metadata for these events.

The hard part is identity matching. Some oracle events can be matched directly through question id or condition id. Others require adapter mappings, ancillary data decoding, title/date matching, or neg-risk request mappings.

Market lifecycle:
1. Discovered from Gamma, CLOB, or on-chain registry events
2. Made tradeable through condition id and outcome tokens
3. Actively traded through CLOB prices and OrderFilled flow
4. Closed or locked near the market end date
5. Reviewed through oracle request, proposal, dispute, and settlement
6. Resolved, final, and archived for historical analysis