polymarket-prediction-market
Understand Polymarket's prediction markets—binary event contracts, CLOB pricing, order books, conditional tokens, and API integration.
Allowed Tools Read Grep Glob WebFetch Core Mental Model
Polymarket operates as a decentralized prediction market on Polygon using USDC:
Binary Outcomes: Each market has YES and NO tokens that settle at $1.00 or $0.00 Price = Probability: A YES token at $0.65 implies 65% probability of the outcome CLOB (Central Limit Order Book): Prices determined by limit orders, not AMM Conditional Token Framework (CTF): Outcomes represented as ERC-1155 tokens USDC Collateral: All trading uses USDC on Polygon network Data Hierarchy Condition (Event) └── Market ├── YES Token (token_id) └── NO Token (token_id)
Condition: The overarching question/event (e.g., "Will Team Liquid win?") Market: A specific tradeable contract with YES/NO outcomes Tokens: Each outcome is a separate ERC-1155 token with unique token_id Market Objects
Key fields in Polymarket market data:
Field Description condition_id Unique identifier for the condition/event question The market question text tokens Array of outcome tokens (YES/NO) token_id Unique ID for each outcome token outcome Token outcome name ("Yes" or "No") price Current mid-market price ($0.00-$1.00) volume Total trading volume in USDC liquidity Available liquidity in the order book end_date_iso When the market closes for trading active Whether market is currently tradeable closed Whether market has been resolved resolved Settlement status resolution Final outcome if resolved Order Book Structure
Polymarket uses a Central Limit Order Book (CLOB):
Order Book for "YES" Token
BIDS (Buy Orders) | ASKS (Sell Orders) $0.62 - 500 shares | $0.64 - 300 shares $0.61 - 1000 shares | $0.65 - 800 shares $0.60 - 2000 shares | $0.66 - 1500 shares
Bid: Highest price buyers will pay Ask: Lowest price sellers will accept Spread: Difference between best bid and ask Mid Price: (Best Bid + Best Ask) / 2 Trading Mechanics Order Types Type Description GTC Good-Til-Cancelled - stays until filled or cancelled GTD Good-Til-Date - expires at specified time FOK Fill-Or-Kill - must fill entirely or cancel Position Management Buy YES: Profit if outcome is true (settles at $1.00) Buy NO: Profit if outcome is false (settles at $1.00) Sell: Close position by selling tokens back to order book Merge: Combine YES + NO tokens to redeem $1.00 USDC Fees Maker Fee: ~0% (providing liquidity) Taker Fee: ~1-2% (taking liquidity) Fees may vary; check current fee schedule Settlement & Resolution Trading Closes: Market stops accepting orders at end_date_iso Resolution: Oracle determines the outcome Settlement: Winning tokens redeem for $1.00 USDC Losing tokens become worthless ($0.00) Redemption: Users claim winnings via smart contract API Conventions Base URLs Environment URL CLOB API https://clob.polymarket.com Gamma API https://gamma-api.polymarket.com Public Endpoints (No Auth) Endpoint Description GET /markets List all markets GET /markets/{condition_id} Get specific market GET /book Get order book for a token GET /price Get current prices GET /midpoint Get mid-market price Authenticated Endpoints Endpoint Description POST /order Place a new order DELETE /order/{order_id} Cancel an order GET /orders Get user's open orders GET /trades Get user's trade history Authentication
Polymarket uses EIP-712 signatures for authentication:
Headers:
POLY_ADDRESS:
WebSocket (Real-time Updates)
Connect to wss://ws-subscriptions-clob.polymarket.com/ws/ for:
price - Real-time price updates book - Order book changes trades - Trade execution notifications API Response Examples Market Object { "condition_id": "0x1234...", "question": "Will Team Liquid win the CS2 Major?", "tokens": [ { "token_id": "12345", "outcome": "Yes", "price": 0.65 }, { "token_id": "12346", "outcome": "No", "price": 0.35 } ], "volume": "150000.00", "liquidity": "25000.00", "end_date_iso": "2024-03-15T00:00:00Z", "active": true, "closed": false }
Order Book Response { "token_id": "12345", "bids": [ {"price": "0.64", "size": "500"}, {"price": "0.63", "size": "1000"} ], "asks": [ {"price": "0.66", "size": "300"}, {"price": "0.67", "size": "800"} ] }
Sports & Esports Markets
Polymarket hosts various sports and esports betting markets. Understanding the naming conventions and market structures is critical for matching markets across platforms.
Supported Categories Category Examples Esports CS2, League of Legends, Valorant, Dota 2, Call of Duty Basketball NBA games, playoffs, championships Soccer Premier League, UEFA, Champions League, World Cup American Football NFL games, Super Bowl Tennis ATP, WTA, Grand Slams (Wimbledon, US Open, etc.) MMA/Fighting UFC events, Bellator Market Naming Conventions
Polymarket sports markets typically follow these patterns:
Match Winner: "Will [Team A] beat [Team B]?" "Will [Team A] win against [Team B]?" "[Team A] vs [Team B] - Winner"
Tournament Winner: "Will [Team/Player] win [Tournament]?" "[Tournament] Winner: [Team/Player]"
Player Props: "Will [Player] score [X] points?" "Will [Player] get [X] kills?"
Common Name Variations
When matching markets across platforms, watch for these variations:
Polymarket Kalshi Notes Team Liquid Team Liquid, TL Abbreviations G2 Esports G2, G2 eSports Spacing/capitalization FaZe Clan FaZe, Faze Clan Case sensitivity Natus Vincere NaVi, Na'Vi Common nicknames Manchester United Man United, Man U Shortened names Los Angeles Lakers LA Lakers, Lakers City abbreviations Esports-Specific Patterns CS2 (Counter-Strike 2) Market formats: "Will Team Liquid win vs FaZe Clan?" "Team Liquid vs FaZe - CS2 Major" "CS2 Major Champion: Team Liquid"
Common tournaments: - Major Championships (Copenhagen, Shanghai) - ESL Pro League - BLAST Premier - IEM (Intel Extreme Masters)
League of Legends Market formats: "Will T1 win Worlds 2024?" "T1 vs Gen.G - LCK Finals" "League of Legends World Champion"
Common tournaments: - Worlds (World Championship) - MSI (Mid-Season Invitational) - LCK, LEC, LCS (Regional leagues)
Valorant Market formats: "Will Sentinels win VCT Champions?" "Sentinels vs LOUD - VCT Finals"
Common tournaments: - VCT Champions - VCT Masters - Regional Challengers
Call of Duty Market formats: "Will OpTic win CDL Championship?" "OpTic vs FaZe - CDL Major"
Common tournaments: - CDL (Call of Duty League) Majors - CDL Championship - Warzone events
Traditional Sports Patterns NBA Basketball Market formats: "Will the Lakers beat the Celtics?" "Lakers vs Celtics - NBA Finals Game 1" "NBA Champion 2024"
Identifiers: - Team city + name (Los Angeles Lakers) - Just team name (Lakers) - Abbreviations (LAL)
Soccer/Football Market formats: "Will Manchester City beat Arsenal?" "Man City vs Arsenal - Premier League" "Champions League Winner 2024"
Leagues/Tournaments: - Premier League (England) - La Liga (Spain) - Serie A (Italy) - Bundesliga (Germany) - UEFA Champions League - UEFA Europa League - World Cup
NFL Football Market formats: "Will the Chiefs beat the Eagles?" "Chiefs vs Eagles - Super Bowl" "Super Bowl LVIII Winner"
Identifiers: - City + name (Kansas City Chiefs) - Just name (Chiefs) - Abbreviations (KC)
Tennis Market formats: "Will Djokovic win Wimbledon?" "Djokovic vs Alcaraz - Wimbledon Final" "US Open Men's Singles Winner"
Tournaments: - Grand Slams: Australian Open, French Open, Wimbledon, US Open - ATP/WTA Masters events
MMA/UFC Market formats: "Will Jon Jones beat Stipe Miocic?" "Jones vs Miocic - UFC 309" "UFC Heavyweight Champion after UFC 309"
Identifiers: - Fighter full name - Last name only - Nickname ("Bones" for Jon Jones)
API Filtering for Sports Markets
To find sports markets programmatically:
// Filter by tags/categories GET /markets?tag=sports GET /markets?tag=esports GET /markets?tag=nba GET /markets?tag=cs2
// Search by keywords in question GET /markets?search=NBA GET /markets?search=Team%20Liquid GET /markets?search=UFC
// Filter active sports markets GET /markets?active=true&tag=sports
Market Matching Strategy
For cross-platform arbitrage, use this matching approach:
Normalize team/player names
Remove special characters: FaZe Clan → faze clan Handle abbreviations: TL → team liquid Map nicknames: NaVi → natus vincere
Extract key entities
Team A name Team B name Tournament/League name Match date/time
Match by similarity
Levenshtein distance for fuzzy matching Token overlap for multi-word names Date proximity for same matchup
Verify market type
Both markets must be "match winner" type Same teams/players involved Same event timeframe Example: Cross-Platform Match Polymarket Market: Question: "Will Team Liquid beat G2 Esports?" YES price: $0.55 End date: 2024-03-15
Kalshi Market: Title: "Team Liquid vs G2 - CS2 Major Semifinal" YES price: $0.52 NO price: $0.51
Matching confidence: HIGH - Same teams (Team Liquid, G2) - Similar timeframe - Both match-winner markets
Arbitrage check: Polymarket NO: $0.45 Kalshi YES: $0.52 Total: $0.97 → $0.03 profit potential
Application Guidance
When answering questions about Polymarket:
Clarify terminology: Explain that prices represent implied probabilities Highlight CLOB: Unlike AMMs, Polymarket uses limit orders Explain tokens: YES/NO are separate tradeable ERC-1155 tokens Note fees: Taker fees reduce profit margins Mention settlement: Winning tokens redeem at exactly $1.00 Stay neutral: Do not provide financial advice or predictions Arbitrage Context (ArbiBot)
For cross-platform arbitrage with Kalshi:
Concept Polymarket Kalshi Settlement $1.00 USDC $1.00 USD Order Type CLOB CLOB Currency USDC (Polygon) USD Auth EIP-712 Signatures RSA Signatures Fees ~1-2% taker Variable/Quadratic Valid Arbitrage Strategy
Buy opposing outcomes across platforms when total cost < $1.00:
Example: Polymarket YES @ $0.45 Kalshi NO @ $0.48 Total Cost: $0.93 Guaranteed Profit: $0.07 (one side pays $1.00)
Examples Explaining a Price
"The YES token trading at $0.72 means the market collectively estimates a 72% probability of this outcome occurring."
Describing Order Execution
"Your limit order to buy 100 YES shares at $0.65 will sit in the order book until someone sells at that price or lower."
Settlement Explanation
"If Team Liquid wins, your YES tokens settle at $1.00 each. If they lose, those tokens become worthless, but any NO tokens would pay out $1.00."
References Polymarket CLOB Documentation Polymarket API Reference Conditional Token Framework