polymarket-prediction-market

SKILL.md

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 Framework