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

1. Trading Closes: Market stops accepting orders at end_date_iso
2. Resolution: Oracle determines the outcome
3. Settlement:
   • Winning tokens redeem for $1.00 USDC
   • Losing tokens become worthless ($0.00)
4. 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 approac