---

name: polymarket-prediction-market description: "Understand Polymarket prediction markets for sports and esports betting. Use when working with Polymarket API, sports arbitrage, binary contracts, CLOB pricing, or cross-platform trading with Kalshi. Triggers on: polymarket, prediction market, sports betting, esports betting, arbitrage, 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

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 approach:

1. Normalize team/player names

   • Remove special characters: FaZe Clan → faze clan
   • Handle abbreviations: TL → team liquid
   • Map nicknames: NaVi → natus vincere

2. Extract key entities

   • Team A name
   • Team B name
   • Tournament/League name
   • Match date/time

3. Match by similarity

   • Levenshtein distance for fuzzy matching
   • Token overlap for multi-word names
   • Date proximity for same matchup

4. 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:

1. Clarify terminology: Explain that prices represent implied probabilities
2. Highlight CLOB: Unlike AMMs, Polymarket uses limit orders
3. Explain tokens: YES/NO are separate tradeable ERC-1155 tokens
4. Note fees: Taker fees reduce profit margins
5. Mention settlement: Winning tokens redeem at exactly $1.00
6. 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