polymarket-prediction-market

What this skill does

# 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

```json
{
  "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

```json
{
  "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 ci