Python functions: screenPolymarkets(), getPolymarketOHLCV(), getPolymarketPriceAndBook(), 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 seven functions covering market discovery, price history, live order books, 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. Because prices are probabilities and every trade is on-chain, this dataset supports strategies that have no equivalent in traditional markets: probability arbitrage between related markets, event-driven signals extracted from prediction prices, and copy-trading of wallets with verified track records.

Polymarket is a tradable venue on Scalar Field: outcome tokens execute live or in paper mode through venue.trade() or strategy.execute(). See Trading on Polymarket for order semantics, funding, and connection steps.

Functions at a Glance

Function	Purpose	Example strategy use
`screenPolymarkets()`	Search and filter markets by keyword, tags, volume, status	Universe selection; finding mispriced or related markets
`getPolymarketOHLCV()`	OHLCV price bars for outcome tokens (daily to 5-min)	Backtesting probability drift and event-reaction patterns
`getPolymarketPriceAndBook()`	Live last-trade price and CLOB order book	Slippage checks and spread-capture before entering
`getPolymarketTrades()`	Trade-level history with wallet, price, size, USDC value	Whale-flow signals; detecting informed money
`screenPolymarketWallets()`	Wallet leaderboards by PnL or volume, filterable by category	Finding wallets worth copying, per category
`getPolymarketPositions()`	Open and closed positions for a wallet or all holders of a market	Copy-trading; mapping who is on each side of a market
`getPolymarketProfile()`	Trader profile: name, bio, portfolio value, markets traded	Vetting a wallet’s scale and history before mirroring

Data Pipeline

Scalar Field ingests Polymarket data through several 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.
Order Books & Last Trade: Fetched live from Polymarket’s CLOB API per query — full bid/ask depth, tick size, and minimum order size per outcome token.
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. Strategy angle: the universe-selection step. An event-driven strategy screens for open markets in its category (e.g. 'crypto' or 'economics'); an arbitrage strategy searches for related markets (e.g. several markets about the same election) whose implied probabilities should be consistent — and trades when they are not. market_outcome_prices is a live probability estimate you can compare against your own model.

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). Strategy angle: since prices are probabilities, these bars are a time series of the market’s belief. Backtest how fast markets converge to resolution (buying favorites at 0.90 and holding to resolution is a measurable, testable strategy), study overreaction to news with 5-minute bars around known events, or use a Polymarket probability series (e.g. a Fed-decision market) as an input feature for strategies trading other asset classes.

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

`getPolymarketPriceAndBook()`

Latest trade price and live order book for outcome tokens, fetched from Polymarket’s CLOB API: full bid/ask depth plus the last executed trade per token. Strategy angle: the pre-trade check for any Polymarket strategy. Prediction market books can be thin — walk the ask side to see how much of your intended size fills near the quoted probability before committing. The bid-ask spread is also an opportunity in itself: wide spreads in low-attention markets reward patient limit orders over market orders, and tick_size / min_order_size tell you exactly how to place them.

from scalarlib import getPolymarketPriceAndBook

data = getPolymarketPriceAndBook(token_ids=['abc123...'])
info = data['abc123...']

info['last_trade_price']           # 0.962
info['asks'].iloc[0]['price']      # best ask
info['bids'].iloc[0]['price']      # best bid

# How much can be bought within 1 cent of the best ask?
asks = info['asks']
asks[asks['price'] <= asks.iloc[0]['price'] + 0.01]['size'].sum()

Parameters

Parameter	Type	Required	Description
`token_ids`	list of str	Yes	Outcome token IDs from `screenPolymarkets()`.
`book_depth`	int	No	Price levels per side (default 10). `None` = full book.

Return Schema

Returns Dict[str, dict] keyed by token ID:

Field	Type	Description
`last_trade_price`	float	Last executed trade price (0–1)
`last_trade_side`	string	`"BUY"` or `"SELL"`
`ts`	datetime	Book snapshot timestamp (New York time, naive)
`tick_size`	float	Minimum price increment
`min_order_size`	float	Minimum order size in shares
`bids`	pd.DataFrame	Columns `price`, `size` — best bid first
`asks`	pd.DataFrame	Columns `price`, `size` — best ask first

`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. Strategy angle: the informed-money detector. Filtering by min_usdc_value isolates whale trades — a sudden cluster of large buys on one outcome often precedes a price move, since big prediction-market bets tend to be information-driven. Filtering by wallets turns this into the monitoring leg of a copy-trading strategy: watch a proven wallet’s trades in near real time and mirror them.

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. Strategy angle: the discovery step of a copy-trading pipeline — and the category filter is the edge. A wallet at the top of the 'sports' leaderboard has demonstrated skill in sports markets specifically; follow it there rather than in politics. Comparing week vs all rankings separates durable performers from hot streaks before you commit to mirroring anyone.

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. Strategy angle: two strategies in one function. In wallet mode, poll a top trader’s open positions on a schedule and trade the changes — new positions and exits are the copy-trading signal. In token mode, map who holds each side of a market you are researching: if the largest, most profitable holders are concentrated on one outcome, that is a smart-money positioning signal; realized_pnl on closed positions shows who exited early — and whether they were right.

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. Strategy angle: the vetting step before copying a wallet. portfolio_value and markets_traded distinguish a seasoned trader with broad experience from a one-market lottery winner, and created_at reveals whether a strong PnL was earned over years or weeks.

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

Strategy Playbook

Concrete ways to combine these functions into a strategy:

Copy-trading. screenPolymarketWallets(category=...) to shortlist category specialists, getPolymarketProfile() and closed positions from getPolymarketPositions() to vet their history, then poll getPolymarketTrades(wallets=[...]) and mirror new trades via venue.trade() on the Polymarket venue.
Whale-flow momentum. getPolymarketTrades(min_usdc_value=50000) as a rolling scanner for large one-sided flow; confirm with getPolymarketPriceAndBook() that the book still offers a reasonable entry, and size against visible depth.
Favorite convergence. Screen for high-volume markets trading at 0.85–0.95, backtest resolution convergence with getPolymarketOHLCV() on resolved markets (closed=True, using winning_outcome_index), and hold near-certain outcomes to resolution while managing tail risk.
Cross-market consistency. Related markets (same event, different framings or thresholds) imply probability relationships that must hold. Screen them together with screenPolymarkets(), compare market_outcome_prices, and trade violations when book depth on both legs supports it.
Prediction prices as signals elsewhere. Markets on rate decisions, elections, or crypto milestones produce clean probability series via getPolymarketOHLCV() — usable as features in strategies that execute in equities (Alpaca) or crypto (Hyperliquid, Jupiter) rather than on Polymarket itself.

Getting Started

Trading

Trading Venues

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

`getPolymarketPriceAndBook()`

Parameters

Return Schema

`getPolymarketTrades()`

Parameters

Return Schema

`screenPolymarketWallets()`

Parameters

Return Schema

`getPolymarketPositions()`

Parameters

Return Schema

`getPolymarketProfile()`

Parameters

Return Schema

Strategy Playbook

​Product Overview

​Overview

​Functions at a Glance

​Data Pipeline

​Coverage

​Querying the Data

​screenPolymarkets()

​Parameters

​Return Schema

​getPolymarketOHLCV()

​Parameters

​Return Schema

​getPolymarketPriceAndBook()

​Parameters

​Return Schema

​getPolymarketTrades()

​Parameters

​Return Schema

​screenPolymarketWallets()

​Parameters

​Return Schema

​getPolymarketPositions()

​Parameters

​Return Schema

​getPolymarketProfile()

​Parameters

​Return Schema

​Strategy Playbook

Product Overview

Overview

Functions at a Glance

Data Pipeline

Coverage

Querying the Data

`screenPolymarkets()`

Parameters

Return Schema

`getPolymarketOHLCV()`

Parameters

Return Schema

`getPolymarketPriceAndBook()`

Parameters

Return Schema

`getPolymarketTrades()`

Parameters

Return Schema

`screenPolymarketWallets()`

Parameters

Return Schema

`getPolymarketPositions()`

Parameters

Return Schema

`getPolymarketProfile()`

Parameters

Return Schema

Strategy Playbook