/polymarket

name: polymarket
description: Query Polymarket prediction markets for probability data and research insights on real-world events.
version: 1.0.0
author: hermes-CCC (ported from Hermes Agent by NousResearch)
license: MIT
metadata:
  hermes:
    tags: [Research, Polymarket, Prediction-Markets, Probability, Events]
    related_skills: []

Polymarket

Purpose

• Use this skill to pull live prediction market data for research and forecasting workflows.
• Polymarket is useful for probability-oriented views of current events, elections, macro themes, and sports or policy questions.
• Treat the market price as a crowd-implied probability signal, not ground truth.

API Surface

• Base reference: `https://clob.polymarket.com/`
• Public market discovery is commonly accessed through the gamma API.
• Start with active markets and then filter by topic or keyword.

Request Discipline and Rate Limits

• Send a timeout on every request and fail fast instead of hanging a long-running research pass.
• Start with at most 1 request per second when iterating on the gamma API and slow down further if responses get unstable.
• Back off and retry once on `429` or transient `5xx` responses with a short sleep before the second request.
• Cache raw JSON snapshots by timestamp when polling the same topic so you do not hit the API repeatedly for the same view.
• Keep `limit` small during discovery, then widen only after you confirm the endpoint shape and the filter logic you need.
• Record the exact URL you used in notes or logs so later analysis can reproduce the same market slice.

Fetch Active Markets

curl "https://gamma-api.polymarket.com/markets?active=true&limit=20"

• This returns a JSON list of market objects.
• Use small limits during exploration and larger limits when building a topic watcher.

Important Market Fields

• `question`
• `outcomes`
• `outcomePrices`
• `volume`

These are usually enough for first-pass research.

Additional Fields to Inspect

• Inspect `slug` when you need a stable human-readable identifier for later lookups or reporting.
• Inspect `endDate` or other settlement timing fields when the timing of resolution matters more than the headline probability.
• Inspect `liquidity` when present to separate tradeable markets from thin markets that move on little size.
• Inspect `active` and `closed` to keep live monitoring separate from post-resolution analysis.
• Inspect `category`, `tags`, or related event metadata when you need to group markets into a watcher by theme.
• Inspect `conditionId` or token identifiers when you need to correlate market data across downstream systems.

Interpret the Data

• `question` is the market prompt.
• `outcomes` lists the named outcomes, often `Yes` and `No`.
• `outcomePrices` represents the current market-implied probabilities.
• `volume` helps indicate liquidity and how much weight to assign the price signal.

Probability Interpretation

• Interpret a price like `0.65` as roughly a 65 percent implied chance.
• Lower-liquidity markets may be noisier.
• High probability is not certainty.
• Large probability moves over time can matter more than a single point estimate.

Python Example

import requests

url = "https://gamma-api.polymarket.com/markets?active=true&limit=20"
markets = requests.get(url, timeout=20).json()

for market in markets:
    question = market.get("question")
    prices = market.get("outcomePrices")
    print(question, prices)

• This is the minimum useful fetch loop.
• Add defensive parsing because API field presence can vary.

Error Handling and Parsing Rules

• Call `response.raise_for_status()` before parsing JSON so transport failures are not mistaken for empty market sets.
• Normalize the response into a list even if the endpoint returns a single object or a wrapped payload.
• Parse `outcomes` and `outcomePrices` defensively because some clients expose them as serialized JSON strings.
• Skip a market if the number of outcomes does not match the number of prices, and log the `question` for review.
• Treat missing `volume` or `liquidity` as a low-confidence signal instead of silently trusting the quoted price.
• Drop closed or inactive markets from live-monitoring runs unless the task is explicitly about settlement or historical analysis.
• Return the raw market object when the schema changes and your parser no longer finds the expected keys.

Filter by Category or Keyword

• Filter by category when tracking a domain like politics, crypto, or macro.
• Filter by keyword when you care about a specific topic such as `tariffs`, `Fed`, or `OpenAI`.
• Keep the raw result set if you want to backtest or compare price movement later.

Simple pattern:

keyword = "election"
filtered = [
    m for m in markets
    if keyword.lower() in (m.get("question", "")).lower()
]

Concrete Workflows

1. Track a single topic with `curl` and `jq`.

curl -s "https://gamma-api.polymarket.com/markets?active=true&limit=100" \
  | jq -r '.[] | select((.question // "") | ascii_downcase | contains("fed")) | [.question, .outcomePrices, .volume] | @tsv'

2. Save a reproducible snapshot before doing interpretation.

mkdir -p data/polymarket
curl -s "https://gamma-api.polymarket.com/markets?active=true&limit=100" \
  -o "data/polymarket/markets_$(date +%Y%m%d_%H%M%S).json"

3. Filter to liquid markets in Python before ranking.

import requests

markets = requests.get(
    "https://gamma-api.polymarket.com/markets?active=true&limit=100",
    timeout=20,
).json()

liquid = [
    m for m in markets
    if float(m.get("volume") or 0) >= 10000
]

Use these workflows for headline watchers, event-specific dashboards, and daily probability snapshots that need to be comparable over time.

Research Use Cases

• calibration research
• current event probabilities
• forecasting support
• comparing market odds to analyst narratives
• monitoring how expectati