Polymarket Prediction Market Data Skill for Hermes Agent
Query Polymarket: markets, prices, orderbooks, history.
Written by Neura Market from the official Hermes Agent documentation for Polymarket. Commands, paths, and version numbers are reproduced from the source unchanged.
Read the official documentationThe Polymarket skill bundled with Hermes Agent lets you query prediction market data from Polymarket's public REST APIs. It is read-only and requires no authentication. Use it when you need to answer questions about betting odds, event probabilities, market prices, orderbooks, or price history.
What it does
This skill gives Hermes Agent the ability to search and browse Polymarket events and markets, retrieve real-time prices and orderbook data, and pull price history. All data comes from three public APIs: Gamma (discovery and search), CLOB (real-time prices and orderbooks), and Data (trades and open interest). The skill parses Polymarket's double-encoded JSON fields and formats prices as readable percentages.
Before you start
The skill is bundled with Hermes Agent and installed by default. It works on Linux, macOS, and Windows. No API keys or authentication are needed because all endpoints are public and read-only. The skill path is skills/research/polymarket.
Searching markets with the Gamma API
When a user asks about prediction market odds, the typical workflow starts with a search using the Gamma API public-search endpoint. The response contains events, each of which may have one or more markets. You extract the market question, current prices, and volume.
GET https://gamma-api.polymarket.com/events?tag=polymarket&closed=false&limit=5
Parsing double-encoded fields
The Gamma API returns outcomePrices, outcomes, and clobTokenIds as JSON strings inside JSON responses. In Python, parse them with:
import json
prices = json.loads(market['outcomePrices'])
Presenting results
Format prices as percentages for readability. For example, outcomePrices ["0.652", "0.348"] becomes "Yes: 65.2%, No: 34.8%". Always show the market question and probability, and include volume when available.
Example output: "Will X happen?", 65.2% Yes ($1.2M volume)
Getting real-time prices and orderbooks
Use the CLOB API with the clobTokenIds from a market to fetch current prices or the full orderbook.
GET https://clob.polymarket.com/price?token_id=YOUR_TOKEN_ID
GET https://clob.polymarket.com/book?token_id=YOUR_TOKEN_ID&side=BUY
Retrieving price history
Use the Data API with the conditionId from a market to get historical price data.
GET https://data-api.polymarket.com/price-history?conditionId=YOUR_CONDITION_ID&interval=max&fidelity=60
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
outcomePricesfield: JSON-encoded array like["0.80", "0.20"]clobTokenIdsfield: JSON-encoded array of two token IDs [Yes, No] for price/book queriesconditionIdfield: hex string used for price history queries- Volume is in USDC (US dollars)
Rate limits
Rate limits are generous and unlikely to be hit during 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)
When not to use it
Do not use this skill if the user wants to place trades. This skill is read-only and does not support trading. Trading requires wallet-based crypto authentication (EIP-712 signatures) which is outside the scope of this skill.
Limits and gotchas
- Some new markets may have empty price history.
- Geographic restrictions apply to trading, but read-only data is globally accessible.
- The Gamma API returns
outcomePrices,outcomes, andclobTokenIdsas double-encoded JSON strings. You must parse them withjson.loads()to get the actual array.
Related resources
See references/api-endpoints.md for the full endpoint reference with curl examples.