polymarket

# Polymarket — Prediction Market Data Query prediction market data from Polymarket using their public REST APIs. All endpoints are read-only and require zero authentication. See `references/api-endpoints.md` for the full endpoint reference with curl examples. ## When to Use - User asks about prediction markets, betting odds, or event probabilities - User wants to know "what are the odds of X happening?" - User asks about Polymarket specifically - User wants market prices, orderbook data, or price history - User asks to monitor or track prediction market movements ## Key Concepts - **Events** contain one or more **Markets** (1:many relationship) - **Markets** are binary outcomes with Yes/No prices between 0.00 and 1.00 - Prices ARE probabilities: price 0.65 means the market thinks 65% likely - `outcomePrices` field: JSON-encoded array like `["0.80", "0.20"]` - `clobTokenIds` field: JSON-encoded array of two token IDs [Yes, No] for price/book queries - `conditionId` field: hex string used for price history queries - Volume is in USDC (US dollars) ## Three Public APIs 1. **Gamma API** at `gamma-api.polymarket.com` — Discovery, search, browsing 2. **CLOB API** at `clob.polymarket.com` — Real-time prices, orderbooks, history 3. **Data API** at `data-api.polymarket.com` — Trades, open interest ## Typical Workflow When a user asks about prediction market odds: 1. **Search** using the Gamma API public-search endpoint with their query 2. **Parse** the response — extract events and their nested markets 3. **Present** market question, current prices as percentages, and volume 4. **Deep dive** if asked — use clobTokenIds for orderbook, conditionId for history ## Presenting Results Format prices as percentages for readability: - outcomePrices `["0.652", "0.348"]` becomes "Yes: 65.2%, No: 34.8%" - Always show the market question and probability - Include volume when available Example: `"Will X happen?" — 65.2% Yes ($1.2M volume)` ## Parsing Double-Encoded Fields The Gamma API returns `outcomePrices`, `outcomes`, and `clobTokenIds` as JSON strings inside JSON responses (double-encoded). Parse them with `JSON.parse(market.outcomePrices)` to get the actual array — the bundled `scripts/polymarket.mjs` helper (see below) does this automatically. ## Helper Script The `scripts/polymarket.mjs` script wraps all three APIs with clean, formatted output: ```bash node scripts/polymarket.mjs search "bitcoin" node scripts/polymarket.mjs trending --limit 10 node scripts/polymarket.mjs market <slug> node scripts/polymarket.mjs event <slug> node scripts/polymarket.mjs price <token_id> node scripts/polymarket.mjs book <token_id> node scripts/polymarket.mjs history <condition_id> --interval all --fidelity 50 node scripts/polymarket.mjs trades --limit 10 ``` No dependencies — uses only Node.js built-ins (requires Node 18+ for global `fetch`). ## Rate Limits Generous — unlikely to hit for normal usage: - Gamma: 4,000 requests per 10 seconds (general) - CLOB: 9,000 requests per 10 seconds (general) - Data: 1,000 requests per 10 seconds (general) ## Limitations - This skill is read-only — it does not support placing trades - Trading requires wallet-based crypto authentication (EIP-712 signatures) - Some new markets may have empty price history - Geographic restrictions apply to trading but read-only data is globally accessible