STAT-API

Polymarket GraphQL Reference

Polymarket's on-chain prediction markets — events and the YES/NO outcome tokens that trade against them, with OHLC candles, minute-fidelity price history, and the full public trade tape.

Every GraphQL type, relation, argument, and field — generated from the served schema, so it can never disagree with the API. Each column is documented inline; relations and foreign keys link straight to the type they resolve to. Root fields take the same filters as REST; requests are metered by rows resolved, nested lists included.

Main

eventsPolymarketEvents
A real-world event that anchors a set of Polymarket markets — a single sports game, an election, a futures question, or any other resolvable scenario. E.g., "Mavericks vs Suns" game event or "2026 NBA Champion" futures event.
REST endpoint →Open in playground →
Required filters: one of league_code.
Fields (19)
idBigIntkey

Primary Key

condition_idString

Polymarket event condition ID (stable identifier)

ex: 10354
slugString

URL slug, e.g. "nba-dal-phx-2026-04-08"

ex: nba-play-in-lakers-vs-pelicans
titleString
ex: NBA
descriptionStringnullable
ex: asd
start_dateStringnullable
ex: 2024-08-17T12:00:00.000Z
end_dateStringnullable
ex: 2025-02-09T12:00:00.000Z
statusString

"active", "closed", "resolved"

ex: closedValues:closedactive
neg_riskBoolean

True for multi-outcome groups (e.g., 30-team NBA Champion)

ex: falseValues:falsetrue
competition_idBigIntnullable

Polymorphic cross-schema ref — {league}.games (team sports) or golf.tournaments (golf), resolved at app level by slug parsing via league_code. Dereference via main.competitions. NULL until linked.

ex: 124
game_dateStringnullable

Game date parsed from slug

ex: 2025-04-11T04:00:00.000Z
home_teamStringnullable

Tricode: "PHX"

ex: PHI
away_teamStringnullable

Tricode: "DAL"

ex: MIN
league_codeStringnullable

e.g. "nba", denormalized for filtering

ex: nbaValues:nbanflmlbnhl
volumeBigIntnullable

Lifetime volume in USDC minor units

ex: 150
liquidityBigIntnullable

Current liquidity in USDC minor units

ex: 272
market_countIntnullable
ex: 1
created_atString
updated_atString
Relations (3)
markets[PolymarketMarkets!]!→ PolymarketMarkets

polymarket.markets rows whose event_id references this row.

tokens[PolymarketTokens!]!→ PolymarketTokens

polymarket.tokens rows whose event_id references this row.

competitionCompetition→ Competition

The sporting event this row prices, resolved through the cross-sport competition registry via (league_code, competition_id); null when the row is not linked to a game or tournament.

Arguments (6)
  • firstIntPage size; clamped to the table's REST default/max limits.
  • afterBigIntKeyset cursor — returns rows with id > after, ordered by id ascending.
  • league_codeStringFilter to events for a single league/sport slug (e.g., "nba", "nfl", "soccer").
  • competition_idIntFilter to events linked to a specific competition (cross-schema game; resolved from slug).
  • statusStringFilter by event status — "active" or "closed".
  • game_dateStringFilter to events scheduled on a specific date (YYYY-MM-DD).
tokensPolymarketTokens
The tradable outcome tokens within a Polymarket market — YES and NO for binary markets, or one token per outcome for multi-outcome markets (e.g., each team in a championship futures market). The clobTokenId is used to query CLOB API for pricing and trades.
REST endpoint →Open in playground →
Required filters: one of market_id.
Fields (11)
idBigIntkey

Primary Key

token_idString→ PolymarketTokens

Polymarket clobTokenId (used for CLOB API queries)

ex: 112051992614671133201592400050969953043323338832721778933622167799976620794248
market_idBigInt→ PolymarketMarkets
ex: 1
event_idBigIntnullable→ PolymarketEvents

Denormalized for direct event queries

ex: 1088
outcomeString

Outcome label: team name, "Yes", "No"

ex: Yes
outcome_indexInt

0-based index of this outcome within the market

ex: 0
price_bpsIntnullable

Latest price in basis points (0-10000)

ex: 10000
winnerBooleannullable

True if this outcome won, null if unresolved

ex: falseValues:falsetrue
created_atString
updated_atString
final_price_bpsIntnullable

Settlement price (10000 for winner, 0 for loser)

ex: 10000
Relations (2)
marketPolymarketMarkets→ PolymarketMarkets

The polymarket.markets row referenced by market_id; null when unlinked.

eventPolymarketEvents→ PolymarketEvents

The polymarket.events row referenced by event_id; null when unlinked.

Arguments (4)
  • firstIntPage size; clamped to the table's REST default/max limits.
  • afterBigIntKeyset cursor — returns rows with id > after, ordered by id ascending.
  • market_idIntFilter to outcome tokens for a single Polymarket market.
  • event_idIntFilter to tokens linked to a single event (denormalized for direct event queries).
marketsPolymarketMarkets
An individual prediction market on Polymarket — a specific question tied to an event, resolved on-chain, with one or more tradable outcome tokens. Each market has 2+ tokens representing outcome positions.
REST endpoint →Open in playground →
Required filters: one of event_id | competition_id.
Fields (22)
idBigIntkey

Primary Key

condition_idString

Polymarket market condition ID (stable identifier)

ex: 0x141f2fb7dc316ca019d7ce9d0fe530a78e18b637ea84211d8f4cebe43742a7bb
event_idBigInt→ PolymarketEvents
ex: 1088
questionStringnullable

Full question text

ex: Over 229.5
slugStringnullable
ex: nba-play-in-lakers-vs-pelicans
competition_idBigIntnullable

Polymorphic cross-schema ref (denormalized from event) resolved at app level by league_code. Dereference via main.competitions. NULL until linked.

ex: 4801
neg_riskBoolean
ex: falseValues:falsetrue
statusString

"active", "closed", "resolved"

ex: closed
resultStringnullable

Winning outcome string, null if unresolved

ex: Over
outcome_countInt

Number of tokens/outcomes (2 for binary, N for multi-outcome)

ex: 2
activeBoolean
ex: trueValues:truefalse
closedBoolean
ex: true
volumeBigIntnullable
ex: 150
liquidityBigIntnullable
best_bid_bpsIntnullable

Basis points (0-10000)

ex: 100
best_ask_bpsIntnullable

Basis points (0-10000)

ex: 10000
last_trade_price_bpsIntnullable

Basis points (0-10000)

ex: 10000
created_atString
updated_atString
resolved_atStringnullable

When the market was resolved

ex: 2026-06-30T19:02:32.753Z
resolution_sourceStringnullable

"uma", "manual", etc.

ex: uma
payout_token_idStringnullable→ PolymarketTokens

Token ID that paid out at 1.00 (winner)

ex: 112051992614671133201592400050969953043323338832721778933622167799976620794248
Relations (7)
eventPolymarketEvents→ PolymarketEvents

The polymarket.events row referenced by event_id; null when unlinked.

tokens[PolymarketTokens!]!→ PolymarketTokens

polymarket.tokens rows whose market_id references this row.

candles[PolymarketCandles!]!→ PolymarketCandles

polymarket.candles rows whose market_id references this row.

price_histories[PolymarketPriceHistories!]!→ PolymarketPriceHistories

polymarket.price_histories rows whose market_id references this row.

public_trades[PolymarketPublicTrades!]!→ PolymarketPublicTrades

polymarket.public_trades rows whose market_id references this row.

order_book_snapshots[PolymarketOrderBookSnapshots!]!→ PolymarketOrderBookSnapshots

polymarket.order_book_snapshots rows whose market_id references this row.

market_snapshots[PolymarketMarketSnapshots!]!→ PolymarketMarketSnapshots

polymarket.market_snapshots rows whose market_id references this row.

Arguments (6)
  • firstIntPage size; clamped to the table's REST default/max limits.
  • afterBigIntKeyset cursor — returns rows with id > after, ordered by id ascending.
  • event_idIntFilter to all markets that belong to a single Polymarket event.
  • competition_idIntFilter to markets linked to a specific competition (denormalized from event).
  • statusStringFilter by market status — "active" or "closed" ("resolved" appears only on 22 legacy rows that carry no resolution data; resolution fields live on closed rows).
  • activeBooleanFilter by active status (defaults to true to show only currently-active rows; pass active=false to include inactive).

Markets

candlesPolymarketCandles
OHLC candlestick price summaries for Polymarket outcome tokens — the open, high, low, close, and volume over standard time bins (1 minute, 5 minute, 1 hour, 1 day). Bucketed by (token_id, period_interval, end_period_ts).
REST endpoint →Open in playground →
Required filters: one of market_id.
Fields (13)
idBigIntkey

Primary Key

token_idString→ PolymarketTokens
ex: 66335248502015003064991075849688982103034628117228927894281920977953935738380
market_idBigInt→ PolymarketMarkets
ex: 51150
period_intervalInt

Period length in seconds (1, 60, 300, 3600)

ex: 1
end_period_tsInt

Unix epoch second of period end

ex: 1775238091
open_bpsIntnullable
ex: 9980
high_bpsIntnullable
ex: 9980
low_bpsIntnullable
ex: 9980
close_bpsIntnullable
ex: 9980
volumeInt

Trade count in period

ex: 1
sizeBigInt

Total share size in micro-units

ex: 5000000
created_atString
updated_atString
Relations (1)
marketPolymarketMarkets→ PolymarketMarkets

The polymarket.markets row referenced by market_id; null when unlinked.

Arguments (5)
  • firstIntPage size; clamped to the table's REST default/max limits.
  • afterBigIntKeyset cursor — returns rows with id > after, ordered by id ascending.
  • market_idIntFilter to candles for all tokens in a single Polymarket market.
  • token_idStringFilter to candles for a single outcome token (clobTokenId).
  • period_intervalIntBin width in seconds. Currently every row is period_interval=1 (event-driven captures, irregular spacing) — resample client-side for fixed OHLC bins.
price_historiesPolymarketPriceHistories
Historical price tracks for each Polymarket outcome token — the full time-series of trading prices since the market opened. Analogous to kalshi.candle.
REST endpoint →Open in playground →
Required filters: one of token_id.
Fields (12)
idBigIntkey

Primary Key

token_idString→ PolymarketTokens

Polymarket clobTokenId

ex: 5771676627182954113677164857547228277089396639521594262964034606220001939923
market_idBigInt→ PolymarketMarkets

Denormalized for market-level queries

ex: 51144
interval_secondsInt

Period length in seconds (60, 3600, 86400)

ex: 86400
period_startString

Start of this OHLC period

ex: 2026-04-03T03:36:43.000Z
open_bpsInt

Opening price in basis points

ex: 5
high_bpsInt
ex: 5
low_bpsInt
ex: 5
close_bpsInt
ex: 5
volumeBigIntnullable

Period volume

created_atString
updated_atString
Relations (1)
marketPolymarketMarkets→ PolymarketMarkets

The polymarket.markets row referenced by market_id; null when unlinked.

Arguments (5)
  • firstIntPage size; clamped to the table's REST default/max limits.
  • afterBigIntKeyset cursor — returns rows with id > after, ordered by id ascending.
  • token_idStringFilter to price history for a single Polymarket outcome token (clobTokenId).
  • market_idIntFilter to price history for all tokens in a single market.
  • interval_secondsIntUpstream fetch-window label (currently always 86400) — NOT a bin width; points within a window are irregularly spaced. Resample client-side.
public_tradesPolymarketPublicTrades
Every executed trade on Polymarket — price, size, side (buy or sell of each token), and timestamp, comprising the public market tape. Represents completed market trades.
REST endpoint →Open in playground →
Required filters: one of market_id.
Fields (12)
idBigIntkey

Primary Key

trade_idString

Trade ID from Polymarket API

ex: 0x8cf169f32ea173f635deebbeab98aeb505e9b654687ec7a243d288e3ab12a3f3
token_idString→ PolymarketTokens

Polymarket clobTokenId

ex: 44914465637297319816681463234953032477919413063019359633128421605039733545953
market_idBigInt→ PolymarketMarkets

Denormalized for market-level queries

ex: 51137
sideString

"BUY" or "SELL"

ex: BUYValues:BUYSELL
price_bpsInt

Trade price in basis points (0-10000)

ex: 6300
sizeBigInt

Trade size (number of shares)

ex: 5000000
traded_atString
ex: 2026-03-18T20:53:01.000Z
created_atString
updated_atString
maker_addressStringnullable

Maker address (limit order provider) from on-chain event

ex: 0x88906147a72d6e22a916f9bd17351a01e045cefb
taker_addressStringnullable

Taker address (market order) from on-chain event

ex: 0x4bfb41d5b3570defd03c39a9a4d8de6bd8b8982e
Relations (1)
marketPolymarketMarkets→ PolymarketMarkets

The polymarket.markets row referenced by market_id; null when unlinked.

Arguments (4)
  • firstIntPage size; clamped to the table's REST default/max limits.
  • afterBigIntKeyset cursor — returns rows with id > after, ordered by id ascending.
  • market_idIntFilter to trades on a single Polymarket market.
  • token_idStringFilter to trades for a single outcome token (clobTokenId).

Misc

market_snapshotsPolymarketMarketSnapshots
Market-level snapshots on Polymarket — aggregate volume, open interest, last trade price, and resolution status captured over time as the market trades. Tracks bid/ask/last and volume/liquidity over time. Coverage begins 2026-04; cadence is roughly hourly.
REST endpoint →Open in playground →
Required filters: one of market_id.
Fields (11)
idBigInt
market_idBigInt
condition_idString
best_bid_bpsInt
best_ask_bpsInt
last_trade_price_bpsInt
volumeBigInt
liquidityBigInt
captured_atString
created_atString
updated_atString
Relations (1)
marketPolymarketMarkets→ PolymarketMarkets

The polymarket.markets row referenced by market_id; null when unlinked.

Arguments (3)
  • firstIntPage size; clamped to the table's REST default/max limits.
  • afterBigIntKeyset cursor — returns rows with id > after, ordered by id ascending.
  • market_idIntFilter to snapshots for a single Polymarket market.
order_book_snapshotsPolymarketOrderBookSnapshots
Order-book depth snapshots for Polymarket outcome tokens — the bid and ask ladders captured at a point in time, showing the resting liquidity at each price level. Top 10 levels per side per token at capture time. Coverage begins 2026-04; pregame cadence (captures generally stop shortly after tip-off).
REST endpoint →Open in playground →
Required filters: one of market_id.
Fields (12)
idBigInt
token_idString
market_idBigInt
sideString
price_bpsInt
sizeBigInt
depth_rankInt
spread_bpsInt
midpoint_bpsInt
captured_atString
created_atString
updated_atString
Relations (1)
marketPolymarketMarkets→ PolymarketMarkets

The polymarket.markets row referenced by market_id; null when unlinked.

Arguments (4)
  • firstIntPage size; clamped to the table's REST default/max limits.
  • afterBigIntKeyset cursor — returns rows with id > after, ordered by id ascending.
  • market_idIntFilter to order-book snapshots for all tokens in a single Polymarket market.
  • token_idStringFilter to order-book snapshots for a single outcome token (clobTokenId).
token_snapshotsPolymarketTokenSnapshots
Token-level snapshots on Polymarket — the bid, ask, and last trade price for each outcome token captured over time as the market trades. Critical for multi-outcome markets where each token moves independently. Coverage begins 2026-04; cadence is roughly 1-2 hours.
REST endpoint →Open in playground →
Required filters: one of token_id.
Fields (7)
idBigInt
token_idString
market_idBigInt
price_bpsInt
captured_atString
created_atString
updated_atString
Arguments (4)
  • firstIntPage size; clamped to the table's REST default/max limits.
  • afterBigIntKeyset cursor — returns rows with id > after, ordered by id ascending.
  • token_idStringFilter to snapshots for a single Polymarket outcome token (clobTokenId).
  • market_idIntFilter to snapshots for all tokens in a single market (denormalized for market-level queries).