polymarket

1---2name: polymarket3description: "Query Polymarket: markets, prices, orderbooks, history."4version: 1.0.05author: Hermes Agent + Teknium6license: MIT7tags: [polymarket, prediction-markets, market-data, trading]8platforms: [linux, macos, windows]9---10 11# Polymarket — Prediction Market Data12 13Query prediction market data from Polymarket using their public REST APIs.14All endpoints are read-only and require zero authentication.15 16See `references/api-endpoints.md` for the full endpoint reference with curl examples.17 18## When to Use19 20- User asks about prediction markets, betting odds, or event probabilities21- User wants to know "what are the odds of X happening?"22- User asks about Polymarket specifically23- User wants market prices, orderbook data, or price history24- User asks to monitor or track prediction market movements25 26## Key Concepts27 28- **Events** contain one or more **Markets** (1:many relationship)29- **Markets** are binary outcomes with Yes/No prices between 0.00 and 1.0030- Prices ARE probabilities: price 0.65 means the market thinks 65% likely31- `outcomePrices` field: JSON-encoded array like `["0.80", "0.20"]`32- `clobTokenIds` field: JSON-encoded array of two token IDs [Yes, No] for price/book queries33- `conditionId` field: hex string used for price history queries34- Volume is in USDC (US dollars)35 36## Three Public APIs37 381. **Gamma API** at `gamma-api.polymarket.com` — Discovery, search, browsing392. **CLOB API** at `clob.polymarket.com` — Real-time prices, orderbooks, history403. **Data API** at `data-api.polymarket.com` — Trades, open interest41 42## Typical Workflow43 44When a user asks about prediction market odds:45 461. **Search** using the Gamma API public-search endpoint with their query472. **Parse** the response — extract events and their nested markets483. **Present** market question, current prices as percentages, and volume494. **Deep dive** if asked — use clobTokenIds for orderbook, conditionId for history50 51## Presenting Results52 53Format prices as percentages for readability:54- outcomePrices `["0.652", "0.348"]` becomes "Yes: 65.2%, No: 34.8%"55- Always show the market question and probability56- Include volume when available57 58Example: `"Will X happen?" — 65.2% Yes ($1.2M volume)`59 60## Parsing Double-Encoded Fields61 62The Gamma API returns `outcomePrices`, `outcomes`, and `clobTokenIds` as JSON strings63inside JSON responses (double-encoded). When processing with Python, parse them with64`json.loads(market['outcomePrices'])` to get the actual array.65 66## Rate Limits67 68Generous — unlikely to hit for normal usage:69- Gamma: 4,000 requests per 10 seconds (general)70- CLOB: 9,000 requests per 10 seconds (general)71- Data: 1,000 requests per 10 seconds (general)72 73## Limitations74 75- This skill is read-only — it does not support placing trades76- Trading requires wallet-based crypto authentication (EIP-712 signatures)77- Some new markets may have empty price history78- Geographic restrictions apply to trading but read-only data is globally accessible79