Markets Dataset Schema

The markets dataset contains metadata for all markets on an exchange. Use this to discover available markets, find asset IDs, and understand market structure.

Updated Daily

This dataset is updated daily after normalized files are generated.

caution

Some markets may have no data availability at all — these were created on-chain but never went live on the Polymarket frontend (e.g., 5M crypto markets). Additionally, some older markets may have empty slug, question, or outcome fields if Polymarket no longer exposes them through their API. Filter on non-empty availability fields to find markets with downloadable data.

Download

curl -L "https://api.telonex.io/v1/datasets/polymarket/markets" -o markets.parquet

import pandas as pd

df = pd.read_parquet("https://api.telonex.io/v1/datasets/polymarket/markets")

Or using the Python SDK:

from telonex import get_markets_dataframe

df = get_markets_dataframe(exchange="polymarket")

Schema

Core Identifiers

Field	Type	Description
exchange	string	Exchange name (e.g., polymarket).
market_id	string	On-chain condition ID. Primary identifier for the market.
slug	string	URL-friendly identifier from Polymarket (e.g., will-trump-win-2024).

Event Hierarchy

Markets can be grouped under events. For example, "Will Trump win 2024?" and "Will Biden win 2024?" might belong to the same "2024 Presidential Election" event.

Field	Type	Description
event_id	string	Parent event ID (empty if standalone market).
event_slug	string	URL-friendly identifier for the parent event.
event_title	string	Human-readable title of the parent event.

Market Content

Field	Type	Description
question	string	The question being predicted (e.g., "Will Trump win the 2024 election?").
description	string	Longer description with context and resolution criteria.
category	string	Category label (e.g., Sports, Crypto, Pop-Culture). May be empty.
tags	list[string]	List of tag slugs for categorization (e.g., ["politics", "elections"]).

Outcomes

Polymarket markets are binary (two outcomes). Each outcome has a label and an associated token (asset).

Field	Type	Description
outcome_0	string	Label for outcome 0 (typically "Yes" or affirmative).
outcome_1	string	Label for outcome 1 (typically "No" or negative).
asset_id_0	string	Token ID for outcome 0. Use this with asset_id parameter.
asset_id_1	string	Token ID for outcome 1. Use this with asset_id parameter.

Status & Resolution

Status is derived from two sources: the Polymarket API status flags and on-chain settlement data. If a market has been settled on-chain, status is always resolved regardless of the API flags. Otherwise:

• active — Polymarket API active flag is true (open for trading)
• closed — Polymarket API closed or archived flag is true (trading ended, not yet settled)
• unopened — default when no API status flags are set (created on-chain but not yet live)
• resolved — settled on-chain with a result (overrides all above)

Field	Type	Description
status	string	Derived market status: unopened, active, closed, or resolved. See above.
result_id	string	On-chain winning outcome index ("0" or "1") if resolved, empty otherwise.
settled_at_us	int64	On-chain settlement block timestamp in microseconds since epoch. 0 if not settled.
prepared_at_us	int64	On-chain ConditionPreparation block timestamp in microseconds since epoch. 0 if not available.
resolution_source	string	Description or URL of the resolution source.
rules_url	string	Link to the market rules and resolution criteria.

Timestamps

All timestamps are in microseconds since Unix epoch (divide by 1,000,000 for seconds).

Field	Type	Description
start_date_us	int64	When the market opened for trading. 0 if not set.
end_date_us	int64	When the market closes/closed for trading. 0 if not set.
created_at_us	int64	When the market was created.

Data Availability

These fields indicate what historical data is available for each market. Values are dates in YYYY-MM-DD format, or empty string if no data exists. The *_from dates are inclusive and the *_to dates are exclusive (the day after the last available date).

Field	Type	Description
trades_from	string	First date with trade data available.
trades_to	string	Day after last date with trade data available (exclusive).
quotes_from	string	First date with quote data available.
quotes_to	string	Day after last date with quote data available (exclusive).
book_snapshot_5_from	string	First date with 5-level book snapshots.
book_snapshot_5_to	string	Day after last date with 5-level book snapshots (exclusive).
book_snapshot_25_from	string	First date with 25-level book snapshots.
book_snapshot_25_to	string	Day after last date with 25-level book snapshots (exclusive).
book_snapshot_full_from	string	First date with full book snapshots.
book_snapshot_full_to	string	Day after last date with full book snapshots (exclusive).
onchain_fills_from	string	First date with on-chain fill data.
onchain_fills_to	string	Day after last date with on-chain fill data (exclusive).

Example: Find Markets with Data

from telonex import get_markets_dataframe

df = get_markets_dataframe(exchange="polymarket")

# Filter to markets with trade data
has_trades = df[df['trades_from'] != '']
print(f"Markets with trade data: {len(has_trades)}")

# Find active markets tagged with "politics"
active_politics = df[(df['status'] == 'active') & (df['tags'].apply(lambda t: 'politics' in t))]
print(active_politics[['slug', 'question']].head(10))

Example: Get Asset IDs for Download

from telonex import get_markets_dataframe, download

df = get_markets_dataframe(exchange="polymarket")

# Find a specific market by slug
market = df[df['slug'] == 'will-trump-win-2024'].iloc[0]

# Download data using the asset_id
files = download(
    api_key="YOUR_API_KEY",
    exchange="polymarket",
    channel="trades",
    from_date="2024-01-01",
    to_date="2024-01-02",
    asset_id=market['asset_id_0'],  # Yes outcome
)