Polymarket Prediction Market Data: Query Odds, Prices, and Orderbooks

Polymarket is a decentralized prediction market where users trade on the outcome of future events. This skill gives Hermes Agent read-only access to Polymarket's public REST APIs, so you can answer questions like "What are the odds of X happening?" without any authentication. It is ideal for anyone who needs current market prices, orderbook depth, or historical price data for research, monitoring, or analysis.

What it does

This skill queries three public Polymarket APIs to retrieve prediction market data. You can search for markets by keyword, get real-time prices and orderbooks, and pull price history. All endpoints are read-only and require zero authentication, making it straightforward to integrate into any workflow that needs up-to-date probability estimates.

The core relationship to understand: an event contains one or more markets. Each market is a binary outcome with Yes/No prices between 0.00 and 1.00. Prices are probabilities: a price of 0.65 means the market implies a 65% likelihood. Volume is denominated in USDC (US dollars).

Before you start

This is an optional skill, installed on demand. It is part of the optional-skills/finance/polymarket path, version 1.0.0, authored by Hermes Agent + Teknium. It runs on Linux, macOS, and Windows. There are no special permissions or API keys needed because the APIs are public and read-only.

Searching for markets

The typical workflow starts with a user asking about prediction market odds. You search using the Gamma API's public-search endpoint, parse the response to extract events and their nested markets, then present the market question, current prices as percentages, and volume. If the user wants more detail, you can use clobTokenIds for orderbook queries and conditionId for price history.

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. A typical presentation looks like:

"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). When processing with Python, parse them with json.loads(market['outcomePrices']) to get the actual array.

The 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

Each serves a different purpose. Use Gamma for finding markets, CLOB for live trading data, and Data for historical trade and interest information.

Rate limits

Rate limits are generous and unlikely to be 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)

When not to use it

This skill is strictly read-only. It does not support placing trades. If a user wants to buy or sell positions on Polymarket, this skill cannot do that. 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, so be prepared for that when querying.
• Geographic restrictions apply to trading, but read-only data is globally accessible.
• Remember that outcomePrices and clobTokenIds are double-encoded; forgetting to parse them will lead to errors.

Related resources

For a full endpoint reference with curl examples, see references/api-endpoints.md in the skill's documentation.