Install to Claude Code
npx -y skills add https://github.com/axwelbrand-byte/arbibot --skill polymarket-prediction-marketDescription
polymarket prediction market
SKILL.md
---
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
```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 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:
```javascript
// 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](https://docs.polymarket.com)
- [Polymarket API Reference](https://docs.polymarket.com/#api-reference)
- [Conditional Token Framework](https://docs.gnosis.io/conditionaltokens/)