Understand Polymarket prediction markets for sports and esports betting. Use when working with Polymarket API, sports arbitrage, binary contracts, CLOB…
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: <wallet_address>
POLY_SIGNATURE: <eip712_signature>
POLY_TIMESTAMP: <unix_timestamp>
POLY_NONCE: <random_nonce>
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 Frameworkdon't have the plugin yet? install it then click "run inline in claude" again.