polymarket-prediction-market
Understand Polymarket's prediction markets—binary event contracts, CLOB pricing, order books, conditional tokens, and API integration.
Allowed Tools
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:
GET /markets?tag=sports
GET /markets?tag=esports
GET /markets?tag=nba
GET /markets?tag=cs2
GET /markets?search=NBA
GET /markets?search=Team%20Liquid
GET /markets?search=UFC
GET /markets?active=true&tag=sports
Market Matching Strategy
For cross-platform arbitrage, use this matching approac