Python functions: screenPolymarkets(), getPolymarketOHLCV(), getPolymarketTrades(), screenPolymarketWallets(), getPolymarketPositions(), getPolymarketProfile()

Specification	Value
Delivery Frequency	continuous, real-time
Data Frequency	event-driven (trades), bar-aggregated (OHLCV)
Coverage	All active and resolved Polymarket prediction markets
OHLCV Timeframes	daily, hourly, 5-min, 15-min, 30-min
Availability	Free

Product Overview

Overview

Polymarket Data provides comprehensive access to Polymarket’s on-chain prediction market exchange. The dataset spans six functions covering market discovery, price history, trade-level data, wallet analytics, position tracking, and trader profiles. Prediction markets on Polymarket are binary or multi-outcome events (e.g. “Will X happen?”) where outcome tokens trade between

0.00 and

1.00. Each market has one or more outcome tokens identified by token_id, which you obtain from screenPolymarkets() and use across all other functions.

Functions at a Glance

Function	Purpose
`screenPolymarkets()`	Search and filter markets by keyword, tags, volume, status
`getPolymarketOHLCV()`	OHLCV price bars for outcome tokens (daily to 5-min)
`getPolymarketTrades()`	Trade-level history with wallet, price, size, USDC value
`screenPolymarketWallets()`	Wallet leaderboards by PnL or volume, filterable by category
`getPolymarketPositions()`	Open and closed positions for a wallet or all holders of a market
`getPolymarketProfile()`	Trader profile: name, bio, portfolio value, markets traded

Data Pipeline

Scalar Field ingests Polymarket data through three complementary paths:

Events & Markets: Polled from the Polymarket Gamma API every ~1 minute. Market metadata (questions, outcomes, prices, volume, status) stays current within seconds of changes on Polymarket.
On-chain Trades: Indexed directly from Polymarket’s exchange contracts on Polygon, with ~2-second polling. Each trade is enriched with market and event metadata before storage.
OHLCV Bars: Aggregated from on-chain trades at 5-minute, hourly, and daily granularity. 15-minute and 30-minute bars are derived from 5-minute bars at query time.
Wallet, Position & Profile data: Proxied live from the Polymarket API — each query fetches current data directly, with no local caching delay.

Coverage

Markets: All active and resolved Polymarket prediction markets, continuously synced.
Trades: On-chain trade history from Polymarket’s V2 exchange contracts on Polygon, plus earlier indexed trades.
Categories: sports, politics, crypto, culture, weather, economics, tech, finance.
OHLCV Timeframes: daily, hourly, 30-min, 15-min, 5-min.

Querying the Data

`screenPolymarkets()`

Search and filter prediction markets. Returns market metadata, current prices, volume, token IDs, and resolution status.

from scalarlib import screenPolymarkets

# Browse top markets by volume
df = screenPolymarkets()

# Search for bitcoin-related markets
df = screenPolymarkets(query="bitcoin")

# Open sports markets with minimum volume
df = screenPolymarkets(event_tags='sports', closed=False, min_volume=10000)

# Get token_ids for use in other functions
df = screenPolymarkets(query="super bowl", closed=False)
token_ids = df.iloc[0]['token_ids']

# Bulk lookup of specific markets by ID
df = screenPolymarkets(market_ids=['1476588', '1519231', '1518255'], closed=True)

Parameters

Parameter	Type	Required	Description
`query`	str	No	Search string (e.g. `"trump election"`, `"bitcoin price"`).
`market_ids`	list of str	No	Specific market IDs for bulk lookup (faster than filtering).
`event_tags`	str or list	No	Filter by tag(s), OR logic. Options: `'sports'`, `'politics'`, `'crypto'`, `'culture'`, etc.
`exclude_event_tags`	str or list	No	Exclude markets with these tags.
`closed`	bool	No	`False` = open markets, `True` = resolved markets.
`min_volume`	float	No	Minimum USD volume. Defaults to 1,000 when `query` is provided.
`start_date`	str	No	`"YYYY-MM-DD"`. Filter on market lifecycle: `market_start_date >= start_date`.
`end_date`	str	No	`"YYYY-MM-DD"`. Filter on market lifecycle: `market_end_date <= end_date`.
`sort_by`	str	No	`"volume"` (default) or `"created_at"`.
`limit`	int	No	Maximum results (default 50).
`offset`	int	No	Pagination offset (default 0).

Return Schema

Column	Type	Description
`market_id`	string	Unique market identifier
`market_question`	string	The market’s question (e.g. “Will X happen?”)
`market_slug`	string	URL-friendly market slug
`market_volume`	float	Total traded volume (USD)
`market_closed`	bool	Whether the market has resolved
`market_outcomes`	list	Outcome labels (e.g. `['Yes', 'No']`)
`market_outcome_prices`	list	Current prices for each outcome (0 to 1)
`market_best_bid`	float	Best bid price
`market_best_ask`	float	Best ask price
`market_last_trade_price`	float	Last trade price
`market_start_date`	datetime	Market start date
`market_end_date`	datetime	Market end/resolution date
`market_created_at`	datetime	Market creation timestamp
`event_id`	string	Parent event identifier
`event_title`	string	Parent event title
`event_slug`	string	Parent event slug
`token_ids`	list of str	Outcome token IDs — use these with all other Polymarket functions
`winning_outcome_index`	int or None	Index of the winning outcome (None if unresolved)

`getPolymarketOHLCV()`

OHLCV price bars for prediction market outcome tokens. Supports daily, hourly, and sub-hourly timeframes. Omit start and end for live mode (latest bar).

from scalarlib import getPolymarketOHLCV

# Daily bars
data = getPolymarketOHLCV(token_ids=['abc123...'], start='2026-01-01', end='2026-02-01')
df = data['abc123...']

# Hourly bars (inferred from datetime format)
data = getPolymarketOHLCV(token_ids=['abc123...'], start='2026-02-01T09:00:00', end='2026-02-01T18:00:00')

# 5-minute bars with explicit timeframe
data = getPolymarketOHLCV(token_ids=['abc123...'], start='2026-02-01', end='2026-02-02', timeframe='5min')

# Live mode — latest bar
data = getPolymarketOHLCV(token_ids=['abc123...', 'def456...'])

Parameters

Parameter	Type	Required	Description
`token_ids`	list of str	Yes	Outcome token IDs from `screenPolymarkets()`.
`start`	str	No	`"YYYY-MM-DD"` or `"YYYY-MM-DDTHH:MM:SS"` (New York time). Omit for live mode.
`end`	str	No	Same format as `start`. Omit for live mode.
`timeframe`	str	No	`"day"`, `"hour"`, `"5min"`, `"15min"`, or `"30min"`. If omitted, inferred from date format (date-only = daily, datetime = hourly).

Return Schema

Returns Dict[str, pd.DataFrame] keyed by token ID. Each DataFrame:

Column	Type	Description
`ts_recv`	datetime64[ns, US/Eastern]	Bar timestamp (New York time)
`ticker`	string	Token identifier
`open`	float	Opening price (0–1)
`high`	float	High price
`low`	float	Low price
`close`	float	Closing price
`volume`	float	Trading volume

`getPolymarketTrades()`

Trade-level history for prediction markets. Filter by token, wallet, market, event, side, size, price, or USDC value. At least one filter parameter is required.

from scalarlib import getPolymarketTrades

# Recent trades on specific tokens
df = getPolymarketTrades(token_ids=['abc...'], start='2026-02-01')

# Wallet trade history
df = getPolymarketTrades(wallets=['0x1234...'], start='2026-01-01')

# Whale trades (> $50k)
df = getPolymarketTrades(min_usdc_value=50000, start='2026-02-01', sort_by='usdc_value')

# Buy-side only, sorted by size
df = getPolymarketTrades(market_ids=['1356546'], side='BUY', start='2026-02-01', sort_by='size')

Parameters

Parameter	Type	Required	Description
`token_ids`	list of str	No	Filter by outcome token IDs.
`wallets`	list of str	No	Filter by wallet addresses (0x-prefixed).
`market_ids`	list of str	No	Filter by market IDs.
`event_ids`	list of str	No	Filter by event IDs.
`side`	str	No	`"BUY"` or `"SELL"`.
`min_size`	float	No	Minimum trade size in shares.
`max_size`	float	No	Maximum trade size in shares.
`min_usdc_value`	float	No	Minimum USDC value.
`max_usdc_value`	float	No	Maximum USDC value.
`min_price`	float	No	Minimum price (0–1).
`max_price`	float	No	Maximum price (0–1).
`start`	str	No	`"YYYY-MM-DD"` or `"YYYY-MM-DDTHH:MM:SS"` (New York time). Recommended for performance.
`end`	str	No	Same format as `start`.
`include_market_info`	bool	No	Enrich with market question, outcomes, event title (default `True`).
`sort_by`	str	No	`"timestamp"` (default), `"size"`, `"usdc_value"`, or `"price"`.
`ascending`	bool	No	`False` = newest/largest first (default).
`limit`	int	No	Maximum results (default 1,000).
`offset`	int	No	Pagination offset (default 0).

Return Schema

Base columns (always present):

Column	Type	Description
`ts_recv`	datetime64[ns, US/Eastern]	Trade timestamp (New York time)
`timestamp`	int	Unix timestamp
`wallet`	string	Trader wallet address
`side`	string	`"BUY"` or `"SELL"`
`price`	float	Execution price (0–1)
`size`	float	Number of shares traded
`usdc_value`	float	Trade value in USDC
`outcome_token_id`	string	Outcome token traded
`outcome_index`	int	Outcome index (0 or 1)
`market_id`	string	Market identifier
`event_id`	string	Event identifier

Additional columns (when include_market_info=True, the default):

Column	Type	Description
`market_question`	string	Market question text
`market_outcomes`	list	Outcome labels
`market_volume`	float	Total market volume
`market_closed`	bool	Whether market has resolved
`traded_outcome`	string	Name of the traded outcome
`event_title`	string	Parent event title
`event_url`	string	Polymarket event URL

`screenPolymarketWallets()`

Wallet leaderboards by PnL or volume, filterable by prediction market category and time period.

from scalarlib import screenPolymarketWallets

# Top 10 wallets by PnL
df = screenPolymarketWallets(limit=10)

# Most active sports traders this week
df = screenPolymarketWallets(category='sports', time_period='week', sort_by='volume')

# Crypto wallets with > $100k PnL this month
df = screenPolymarketWallets(category='crypto', time_period='month', min_value=100000)

# PnL leaderboard in a range
df = screenPolymarketWallets(min_value=10000, max_value=50000)

Parameters

Parameter	Type	Required	Description
`category`	str	No	`"overall"` (default), `"sports"`, `"crypto"`, `"politics"`, `"culture"`, `"weather"`, `"economics"`, `"tech"`, `"finance"`.
`time_period`	str	No	`"all"` (default), `"month"`, `"week"`, `"day"`.
`sort_by`	str	No	`"pnl"` (default) or `"volume"`.
`min_value`	float	No	Minimum PnL or volume threshold (depends on `sort_by`).
`max_value`	float	No	Maximum PnL or volume threshold.
`limit`	int	No	Maximum results (default 50).
`offset`	int	No	Pagination offset (default 0).

Return Schema

Column	Type	Description
`rank`	int	Leaderboard rank
`wallet`	string	Wallet address
`pnl`	float	Profit and loss (USD)
`volume`	float	Total trading volume (USD)
`username`	string	Polymarket username
`profile_image`	string	Profile image URL
`verified`	bool	Whether the wallet is verified
`x_username`	string	X (Twitter) username

`getPolymarketPositions()`

Open and closed positions for a wallet in prediction markets, or all holders of a specific market. At least one of wallet or token_id is required.

from scalarlib import getPolymarketPositions

# Wallet's open positions
df = getPolymarketPositions(wallet='0x6a72...')

# Wallet's closed (resolved) positions
df = getPolymarketPositions(wallet='0x6a72...', status='closed', sort_by='realized_pnl')

# All holders of a market
df = getPolymarketPositions(token_id='7546712961...')

# Biggest holders by size
df = getPolymarketPositions(token_id='7546712961...', sort_by='size')

# A specific wallet's position in a market
df = getPolymarketPositions(wallet='0x6a72...', token_id='7546712961...')

# Who exited a market?
df = getPolymarketPositions(token_id='7546712961...', status='closed', sort_by='realized_pnl')

Parameters

Parameter	Type	Required	Description
`wallet`	str	No*	Wallet address, 0x-prefixed. *At least one of `wallet` or `token_id` required.
`token_id`	str	No*	Outcome token ID from `screenPolymarkets()`. *At least one of `wallet` or `token_id` required.
`event_id`	int	No	Filter by event ID.
`status`	str	No	`"open"` (default), `"closed"`, or `"all"`.
`sort_by`	str	No	`"size"` (default), `"pnl"`, `"percent_pnl"`, `"realized_pnl"`, `"price"`, `"avg_price"`, `"total_pnl"`.
`ascending`	bool	No	`False` = largest first (default).
`limit`	int	No	Maximum results (default 100).
`offset`	int	No	Pagination offset (default 0).

Return Schema

Columns vary depending on the query: By wallet (open positions):

Column	Type	Description
`wallet`	string	Wallet address
`asset`	string	Token identifier
`condition_id`	string	Market condition ID
`size`	float	Position size (shares)
`avg_price`	float	Average entry price
`initial_value`	float	Cost basis
`current_value`	float	Current market value
`cash_pnl`	float	Unrealized P&L
`percent_pnl`	float	P&L percentage
`realized_pnl`	float	Realized P&L
`cur_price`	float	Current price
`title`	string	Market question
`outcome`	string	Outcome name (e.g. “Yes”)
`outcome_index`	int	Outcome index
`event_slug`	string	Event URL slug
`end_date`	datetime	Market end date

By wallet (closed positions):

Column	Type	Description
`wallet`	string	Wallet address
`asset`	string	Token identifier
`condition_id`	string	Market condition ID
`avg_price`	float	Average entry price
`total_bought`	float	Total shares purchased
`realized_pnl`	float	Realized P&L
`cur_price`	float	Settlement price
`title`	string	Market question
`outcome`	string	Outcome name
`outcome_index`	int	Outcome index
`event_slug`	string	Event URL slug

By token_id (all holders):

Column	Type	Description
`wallet`	string	Holder wallet address
`name`	string	Polymarket username
`profile_image`	string	Profile image URL
`verified`	bool	Whether verified
`asset`	string	Token identifier
`avg_price`	float	Average entry price
`size`	float	Position size
`cur_price`	float	Current price
`current_value`	float	Current market value
`cash_pnl`	float	Unrealized P&L
`realized_pnl`	float	Realized P&L
`total_pnl`	float	Total P&L (unrealized + realized)
`outcome`	string	Outcome name
`outcome_index`	int	Outcome index

`getPolymarketProfile()`

Trader profile information for a Polymarket wallet.

from scalarlib import getPolymarketProfile

df = getPolymarketProfile(wallet='0x6a72...')
print(df.iloc[0]['portfolio_value'])
print(df.iloc[0]['name'], df.iloc[0]['verified'])

Parameters

Parameter	Type	Required	Description
`wallet`	str	Yes	Wallet address, 0x-prefixed.

Return Schema

Returns a single-row DataFrame:

Column	Type	Description
`wallet`	string	Wallet address
`name`	string	Display name
`pseudonym`	string	Pseudonym
`bio`	string	Profile bio
`profile_image`	string	Profile image URL
`verified`	bool	Whether the account is verified
`x_username`	string	X (Twitter) username
`created_at`	datetime	Account creation date (New York time)
`portfolio_value`	float	Total portfolio value (USD)
`markets_traded`	int	Number of markets traded

Getting Started

Trading

Market Data

Usage & Pricing

Polymarket Prediction Markets

Product Overview

Overview

Functions at a Glance

Data Pipeline

Coverage

Querying the Data

`screenPolymarkets()`

Parameters

Return Schema

`getPolymarketOHLCV()`

Parameters

Return Schema

`getPolymarketTrades()`

Parameters

Return Schema

`screenPolymarketWallets()`

Parameters

Return Schema

`getPolymarketPositions()`

Parameters

Return Schema

`getPolymarketProfile()`

Parameters

Return Schema

Getting Started

Trading

Market Data

Usage & Pricing

Documentation Index

​Product Overview

​Overview

​Functions at a Glance

​Data Pipeline

​Coverage

​Querying the Data

​screenPolymarkets()

​Parameters

​Return Schema

​getPolymarketOHLCV()

​Parameters

​Return Schema

​getPolymarketTrades()

​Parameters

​Return Schema

​screenPolymarketWallets()

​Parameters

​Return Schema

​getPolymarketPositions()

​Parameters

​Return Schema

​getPolymarketProfile()

​Parameters

​Return Schema

Product Overview

Overview

Functions at a Glance

Data Pipeline

Coverage

Querying the Data

`screenPolymarkets()`

Parameters

Return Schema

`getPolymarketOHLCV()`

Parameters

Return Schema

`getPolymarketTrades()`

Parameters

Return Schema

`screenPolymarketWallets()`

Parameters

Return Schema

`getPolymarketPositions()`

Parameters

Return Schema

`getPolymarketProfile()`

Parameters

Return Schema