polymarket

# Polymarket Query [Polymarket](https://polymarket.com) prediction markets and trade from the terminal. Browse odds, research events, compare markets, track your portfolio, stream live data, bridge funds, and execute trades - all through natural language. Polymarket exposes 4 separate APIs plus the Gamma convenience layer. This skill covers all of them. ## Setup **Read-only commands work immediately** (no install needed). Browsing, searching, trending, categories, market research, and comparison mode all use the public Gamma API. For trading, order books, price history, and advanced features, install the [Polymarket CLI](https://github.com/Polymarket/polymarket-cli) (Rust binary, v0.1.5+): ```bash brew install polymarket/tap/polymarket-cli ``` For trading, set up a wallet: ```bash polymarket wallet create polymarket approve set ``` Or manually configure `~/.config/polymarket/config.json` with your private key. See the [CLI docs](https://github.com/Polymarket/polymarket-cli) for details. The CLI also provides an interactive REPL: ```bash polymarket shell ``` Use `--output json` on any CLI command for machine-readable output suitable for scripting and piping. ## Commands ### Browse Markets (no CLI needed) ```bash # Trending/active markets (sorted by 24h volume) python3 {baseDir}/scripts/polymarket.py trending # Trending with more results python3 {baseDir}/scripts/polymarket.py trending --limit 20 # Search markets by keyword python3 {baseDir}/scripts/polymarket.py search "trump" # Get specific event by slug python3 {baseDir}/scripts/polymarket.py event "fed-decision-in-october" # Get markets by category python3 {baseDir}/scripts/polymarket.py category politics python3 {baseDir}/scripts/polymarket.py category crypto python3 {baseDir}/scripts/polymarket.py category sports python3 {baseDir}/scripts/polymarket.py category tech python3 {baseDir}/scripts/polymarket.py category entertainment python3 {baseDir}/scripts/polymarket.py category science python3 {baseDir}/scripts/polymarket.py category business ``` ### Trending Markets Dashboard (no CLI needed) Show a categorized dashboard of the hottest markets across Polymarket. Combine trending with category filters to build a full overview. ```bash # Full trending dashboard - run these in sequence to build a picture: python3 {baseDir}/scripts/polymarket.py trending --limit 10 python3 {baseDir}/scripts/polymarket.py category politics --limit 5 python3 {baseDir}/scripts/polymarket.py category crypto --limit 5 python3 {baseDir}/scripts/polymarket.py category sports --limit 5 python3 {baseDir}/scripts/polymarket.py category tech --limit 5 ``` When the user asks for a "dashboard" or "overview," run all category queries and present the results grouped by section with clear headings. Include volume and current odds for each market. ### Market Research Mode (no CLI needed) Market research combines Polymarket odds with contextual analysis. When the user asks to "research" a market or wants deeper analysis beyond just odds: 1. **Fetch the market data** using search or event commands 2. **Analyze the odds** - what does the market imply? Is there an edge? 3. **Provide context** - use your knowledge to explain what drives the odds 4. **Show historical movement** - if CLI is available, pull price history 5. **Compare to consensus** - how do Polymarket odds compare to polls, expert opinion, or other prediction markets? ```bash # Step 1: Find the market python3 {baseDir}/scripts/polymarket.py search "fed rate cut" # Step 2: Get detailed event data python3 {baseDir}/scripts/polymarket.py event "fed-rate-decision-march-2026" # Step 3: If CLI available, get price history to show trend python3 {baseDir}/scripts/polymarket.py price-history TOKEN_ID --interval 1d # Step 4: Check order book depth for liquidity assessment python3 {baseDir}/scripts/polymarket.py book TOKEN_ID ``` After gathering data, synthesize the research into a structured report: - **Current Odds**: Yes/No percentages and what they imply - **Volume & Liquidity**: How much money is in this market, is it liquid enough to trade? - **Trend**: Are odds moving up or down? Any recent spikes? - **Context**: What real-world events or data points are driving the odds? - **Key Dates**: When does the market resolve? Any upcoming catalysts? - **Risk Factors**: What could cause a sudden move? ### Market Comparison Mode (no CLI needed) Compare related markets side-by-side. Useful for finding arbitrage, understanding conditional probabilities, or just seeing how different outcomes relate. ```bash # Compare two or more related markets by searching for each python3 {baseDir}/scripts/polymarket.py search "trump 2028" python3 {baseDir}/scripts/polymarket.py search "desantis 2028" python3 {baseDir}/scripts/polymarket.py search "newsom 2028" ``` When the user asks to "compare markets" or "side-by-side odds": 1. Search for each market the user mentions 2. Present odds in a comparison table format 3. Note volume differences (higher volume = more reliable odds) 4. Flag any apparent inconsistencies (e.g., probabilities that should sum to ~100% but don't) 5. Highlight the spread between related outcomes Format the comparison as a table: ``` Market Comparison: 2028 Presidential Election | Candidate | Yes | Volume | Liquidity | |---------------|---------|---------|-----------| | Trump | 32.5% | $4.2M | High | | DeSantis | 18.1% | $1.8M | Medium | | Newsom | 12.4% | $890K | Medium | | Harris | 8.7% | $2.1M | Medium | ``` ### Portfolio Dashboard (CLI + wallet required) View your complete portfolio with positions, P&L, and open orders in one view. ```bash # View all open positions python3 {baseDir}/scripts/polymarket.py positions # View positions for a specific wallet python3 {baseDir}/scripts/polymarket.py positions --address 0xYOUR_WALLET # Check USDC balance python3 {baseDir}/scripts/polymarket.py wallet-balance # Check balance for a specific token python3 {baseDir}/scripts/polymarket.py wallet-balance --token TOKEN_ID # List all open orders python3 {baseDir}/scripts/polymarket.py orders ``` When the user asks for a "portfolio dashboard" or "how am I doing," run all three commands (positions, wallet-balance, orders) and present a unified view: - **Positions**: Each position with current market price, your entry price (if available), and unrealized P&L - **USDC Balance**: Available cash for new trades - **Open Orders**: Pending limit orders with price and size - **Total Portfolio Value**: Sum of positions + USDC balance ### Order Book & Prices (CLI required, no wallet) ```bash # Order book for a token python3 {baseDir}/scripts/polymarket.py book TOKEN_ID # Price history (intervals: 1m, 1h, 6h, 1d, 1w, max) python3 {baseDir}/scripts/polymarket.py price-history TOKEN_ID --interval 1d # Price history with specific number of data points python3 {baseDir}/scripts/polymarket.py price-history TOKEN_ID --interval 1h --fidelity 48 ``` ### Wallet (CLI required) ```bash polymarket wallet create polymarket wallet show polymarket wallet balance polymarket wallet balance --token TOKEN_ID ``` ### Trading (CLI + wallet required) All trades require `--confirm` to execute. Without it, the order is previewed only. This is a safety feature - you always see what will happen before it happens. #### Cost & Fee Transparency Before executing any trade, the skill displays: - **Order type**: Limit or Market - **Side**: Buy or Sell - **Price**: Your limit price (or "market" for market orders) - **Size**: Number of shares - **Estimated cost**: Price x Size for limit orders, or dollar amount for market orders - **Polymarket fee**: Polymarket charges no trading fees on the CLOB (Central Limit Order Book) - **Gas fees**: On-chain operations (approvals, splits, redeems) require MATIC for gas on Polygon. Typical gas: $0.01-0.05 ```bash # Preview a limit order (no --confirm = preview only) python3 {baseDir}/scripts/polymarket.py trade buy --token TOKEN_ID --price 0.50 --size 10 # Execute a limit order python3 {baseDir}/scripts/polymarket.py --confirm trade buy --token TOKEN_ID --price 0.50 --size 10 # Sell limit order python3 {baseDir}/scripts/polymarket.py --confirm trade sell --token TOKEN_ID --price 0.70 --size 10 # Market order: buy $5 worth at current price python3 {baseDir}/scripts/polymarket.py --confirm trade buy --token TOKEN_ID --market-order --amount 5 # Post-only limit order (rests on book only, never takes liquidity - Jan 2026+) python3 {baseDir}/scripts/polymarket.py --confirm trade buy --token TOKEN_ID --price 0.45 --size 20 --post-only ``` ### Orders & Positions (CLI + wallet required) ```bash # List open orders python3 {baseDir}/scripts/polymarket.py orders # Cancel a specific order python3 {baseDir}/scripts/polymarket.py --confirm orders --cancel ORDER_ID # Cancel all orders python3 {baseDir}/scripts/polymarket.py --confirm orders --cancel all # View positions python3 {baseDir}/scripts/polymarket.py positions python3 {baseDir}/scripts/polymarket.py positions --address 0xYOUR_WALLET ``` --- ## API Reference Polymarket exposes 4 distinct APIs plus the Gamma convenience layer. Each serves a different purpose. ### 1. Gamma API (gamma-api.polymarket.com) - Public, no auth The high-level convenience API for browsing and searching markets. Used by all read-only commands. - **Base URL**: `https://gamma-api.polymarket.com` - `GET /events` - List events (params: `order`, `ascending`, `closed`, `limit`, `tag_slug`) - `GET /search` - Search markets (params: `query`, `limit`) - `GET /events/slug/{slug}` - Event by slug - `GET /comments` - List and filter comments on markets - `GET /profiles/{address}` - Public user profiles - `GET /series` - Grouped event collections (e.g., "2028 Election" series) - `GET /sports` - Sports metadata including teams, matches, and resolution criteria - **GraphQL**: `POST /query` - Full GraphQL endpoint with subscription support ### 2. CLOB API (clob.polymarket.com) - Trading The Central Limit Order Book API for all trading operations. Wrapped by the Polymarket CLI. - **Base URL**: `https://clob.polymarket.com` - `GET /prices-history` - Historical prices (intervals: `1m`, `1h`, `6h`, `1d`, `1w`, `max`) - `GET /spread` - Bid-ask spread for a token - `GET /fee-rate` - Fee structure details - `GET /rewards` - Daily maker/taker earnings - `POST /order` - Place an order - `POST /orders` - Batch orders (up to 15 per request) - `DELETE /order/{id}` - Cancel an order - **Order scoring** - Check maker rebate eligibility before placing orders - **Post-Only orders** (Jan 2026) - Orders that rest on the book only, never cross the spread - **Heartbeat API** (Jan 2026): - `POST /heartbeat` - Must send within 10 seconds or all open orders auto-cancel - Used by market makers to maintain order presence - If heartbeat lapses, all resting orders for that API key are cancelled ### 3. Data API (data-api.polymarket.com) - Portfolio & Analytics The dedicated API for portfolio tracking, trade history, and market analytics. No auth needed for public endpoints. - **Base URL**: `https://data-api.polymarket.com` - `GET /positions?user={address}` - Current open positions - Sort by: `TOKENS`, `CURRENT`, `INITIAL`, `CASHPNL`, `PERCENTPNL` - `GET /closed-positions?user={address}` - Historical closed positions - `GET /activity?user={address}` - Activity feed - Types: `TRADE`, `SPLIT`, `MERGE`, `REDEEM`, `REWARD` - `GET /value?user={address}` - Portfolio valuation in USD - `GET /trades` - Trade history - Filter by: `user`, `market`, `side` - Max 500 results per page - `GET /holders?market={conditionId}` - Top token holders for a market - `GET /oi` - Open interest across markets - `GET /volume` - Trading volume across markets - `GET /leaderboard` - Trader rankings (configurable time period) Use the Data API for portfolio dashboards and analytics. It provides richer position data than the CLOB API, including P&L calculations and activity history. ### 4. RTDS WebSocket (wss://ws-live-data.polymarket.com) - Real-time Streaming Real-time data streaming via WebSocket. Subscribe to topics for live updates without polling. - **URL**: `wss://ws-live-data.polymarket.com` - **Protocol**: JSON messages over WebSocket - **Topics**: - `comments` - Real-time comment activity - Events: `comment_created`, `comment_removed`, `reaction_created`, `reaction_removed` - `crypto_prices` - Real-time cryptocurrency prices - Assets: BTC, ETH, SOL, XRP - Sources: Binance + Chainlink oracles - **Dynamic subscription management** - Subscribe and unsubscribe to topics on the fly within a single connection - Useful for building live dashboards, monitoring comment sentiment, or tracking crypto prices that feed into 5-minute crypto markets ### 5. Bridge API (bridge.polymarket.com) - Cross-chain Deposits & Withdrawals Bridge funds into and out of Polymarket across multiple chains. - **Base URL**: `https://bridge.polymarket.com` - `POST /deposit` - Generate deposit addresses - Supported chains: EVM (Ethereum, Polygon, Arbitrum, etc.), Solana, Bitcoin - Returns a unique deposit address for the selected chain - `POST /withdraw` (Jan 2026) - Bridge USDC.e to any supported chain - `GET /supported-assets` - List all supported assets and chains - `GET /quote` - Get cross-chain bridging quotes (fees, estimated time) Use the Bridge API when a user needs to move funds in or out of Polymarket without leaving the terminal. --- ## New Market Types - **5-minute crypto markets** (Feb 2026) - Ultra-short-duration markets on BTC/ETH/SOL price movements. Fed by RTDS crypto_prices data. - **Sports markets** - Dedicated sports metadata via Gamma `/sports` endpoint with team info, match schedules, and resolution criteria. ## Error Recovery ### API Errors (Gamma API) If the Gamma API returns an error or is unreachable: - **HTTP 429 (Rate Limited)**: Wait 5-10 seconds and retry. The Gamma API has generous rate limits but can throttle during high-traffic events. - **HTTP 500/502/503**: The API is temporarily down. Inform the user and suggest trying again in a minute. - **Connection Error**: Check internet connectivity. The API endpoint is `https://gamma-api.polymarket.com`. - **Empty Results**: The search might be too specific. Suggest broader search terms or browse by category instead. ### Data API Errors - **HTTP 400 (Bad Request)**: Check the `user` address format (must be a valid Ethereum address) or sort parameter spelling. - **Empty positions**: The address may have no open positions, or the address format may be wrong. Try with and without checksum casing. - **Pagination**: Trades endpoint maxes at 500 per page. Use cursor-based pagination for full history. ### CLOB API Errors - **Heartbeat timeout**: If using the Heartbeat API and the connection lapses for >10 seconds, all orders auto-cancel. Reconnect and re-place orders. - **Post-Only rejection**: A post-only order that would cross the spread is rejected instead of filling. Adjust price to rest on the book.