Skip to main content
Execution: venue.trade() in chat code, strategy.execute() in strategy agents. Data reference: Polymarket Data.

​
Overview

Polymarket is an on-chain prediction market exchange. Markets are binary or multi-outcome events whose outcome tokens trade between 0.00and0.00 and 1.00, so prices read as probabilities. Scalar Field connects to Polymarket in two modes: a live account funded through a managed Polygon wallet, and a paper account with virtual USDC whose fills are simulated against the live order book.
SpecificationValue
InstrumentsOutcome tokens, identified by token_id
ModesPOLYMARKET (live), POLYMARKET_PAPER (paper)
Hours24/7
Fill modelSynchronous — orders block until filled or rejected
Slippage toleranceslippage_bps, default 500 (5%)
Minimum orderMarket-specific, typically 1-25+ shares; keep order value ≥ $1.00
CurrencyUSDC (pUSD) via the Polygon wallet; virtual USDC for paper

​
Order Semantics

  • Symbols are outcome token IDs, taken from the token_ids column of screenPolymarkets(). There are no tickers.
  • Fills are synchronous on both live and paper accounts.
  • Paper fills are simulated against the live order book with realistic execution prices and real taker fees, so paper results track live behavior closely. The paper account is auto-provisioned with virtual USDC on first use — no wallet or connection needed.
  • Fractional quantities are supported. When sizing from a dollar budget, use round(budget / price, 2) rather than int(), which floors to zero when the budget is below one share price.
  • Orders below the market’s minimum size are rejected with ORDER_BELOW_MINIMUM.
  • A platform fee is charged separately from the fill; fee_bps and fee_amount appear in the trade response when active.

​
Market Resolution

Every market resolves at its end date (market_end_date). After resolution, positions are settled and can no longer be traded. screenPolymarkets() exposes winning_outcome_index — None while unresolved. Strategies holding outcome tokens should track time to resolution and exit before it by policy (stop loss, take profit, exit buffer), since a position held through resolution cannot be managed.

​
Connecting and Funding

  1. Paper: no setup — POLYMARKET_PAPER is provisioned automatically on first use.
  2. Live: Scalar Field provisions a managed wallet on Polygon (WALLET_POL). Fund it with USDC from the portfolio page; the wallet funds the exchange account.

​
Usage

from scalarlib import screenPolymarkets, venue

# Find open markets and take a token id
markets = screenPolymarkets(query="bitcoin", closed=False, min_volume=10_000)
token_id = markets.iloc[0]["token_ids"][0]

# Paper account — same call shape as live
resp = venue.trade("buy", token_id, 100, account="POLYMARKET_PAPER")
print(resp["status"], resp["filled_qty"], resp["avg_price"])

# Live account
resp = venue.trade("buy", token_id, 100, account="POLYMARKET")
In strategy agents, use strategy.execute(token_id, target_qty) instead — see Strategies.

​
Data Functions

All functions read public on-chain and CLOB data; wallet positions and trades are visible for any address. Full parameter and schema documentation: Polymarket Data.
FunctionPurposeReturns
screenPolymarkets(...)Search/filter markets by keyword, tags, volume, open/resolved statusDataFrame: market metadata, prices, token_ids, winning_outcome_index
getPolymarketOHLCV(token_ids, start, end, timeframe)Price (probability) bars — daily to 5-minuteDict of DataFrames keyed by token_id: OHLCV
getPolymarketTrades(...)Trade-level history filterable by token, wallet, market, side, size, valueDataFrame: wallet, side, price, size, usdc_value, market info
screenPolymarketWallets(...)Wallet leaderboard by PnL or volume, per category and time periodDataFrame: rank, wallet, pnl, volume, profile fields
getPolymarketPositions(...)Open/closed positions for a wallet, or all holders of a tokenDataFrame: size, avg price, current value, PnL per position
getPolymarketProfile(wallet)Trader profileSingle-row DataFrame: name, bio, portfolio_value, markets_traded
getLatestSnapshot(tickers=[token_id])Live last/bid/ask and full order book for a tokenDict per token: last, bid, ask, bids/asks DataFrames

​
Notes

  • Selling an entire position may leave a dust quantity from rounding; treat positions with abs(market_value) < $0.10 as closed.
  • Positions and balances read on-chain state that can lag a fill by a moment — allow for settlement delay before re-querying after a trade.
  • Live-account funds are held in the Polygon wallet (WALLET_POL), not on the exchange account; venue.balances() reflects this.

​
Related