PolyWeather/MARKET_DISCOVERY.md

Polymarket Weather Market Discovery Technical Documentation

This document explains the technical implementation of how PolyWeather identifies and tracks weather markets on Polymarket.

1. Data Sources

We bypass high-level SDKs and interact directly with the Polymarket Gamma API, which is the primary metadata layer for Discovery.

• Base URL: https://gamma-api.polymarket.com
• Endpoint: /markets

2. Discovery Strategy

The system uses a multi-layered search approach to ensure no city segments are missed.

2.1 Keyword Triple-Search

Instead of one query, we execute three concurrent search patterns:

1. "highest temperature": Targets the primary question text.
2. "temperature in": Broad search for regional markets.
3. "daily weather": Fallback for markets with different naming conventions.

2.2 Prioritization

We apply specific sorting to find the latest available contracts (e.g., February 9th, 2026):

• order=id & ascending=false: Scans the newest created markets first.
• active=true & closed=false: Filters out resolved or expired contracts.

3. Filtering & Parsing Logic

Since Polymarket hosts thousands of events, we apply a strict "Weather Filter" in the code:

3.1 Text Validation

We inspect both the question and the slug:

• Pattern Match: Must contain "highest temperature in" or "highest-temperature-in".
• Exclusion: (Implicitly handled by keyword search) filtered from sports or politics.

3.2 Negative Risk Market Handling

Weather markets on Polymarket are often structured as Negative Risk groups (where multiple outcomes like "70°F or higher" and "68-69°F" belong to one event).

Technical Challenge: In the API's list view, the activeTokenId field is often null for these complex markets. Our Solution:

1. Check clobTokenIds.
2. If it's a JSON string (common in Gamma), parse it into a Python list.
3. If activeTokenId is missing, we treat the first token ID in the list as the "YES" Token.
4. This allows us to fetch the real-time orderbook/price even for markets that haven't fully "activated" in the front-end metadata.

4. Market Data Structure

Every market found is normalized into this structure for the Decision Engine:

• condition_id: The UMA condition ID for resolution.
• active_token_id: The specific ERC1155 token ID we want to buy/monitor.
• group_id: The negRiskMarketID, which allows the bot to understand that specific temperature ranges (e.g., 70°F vs 72°F) are related to the same city.
• slug: Used for generating direct dashboard links.

5. Frequency & Caching

• Discovery Frequency: The system rescans for new cities/dates every 5 minutes.
• Caching: Found markets are stored in an internal memory cache (_weather_markets_cache) to reduce API pressure and avoid rate limits.

---

Created on: 2026-02-07 PolyWeather System Documentation