Isocast — Polymarket Weather-Signal API for AI Agents

API at https://api.isocast.dev. Isocast watches 37 cities and, when a city's observed daily-high temperature crosses out of one Polymarket temperature bucket and into another, emits exactly one signal for that (city, day, transition). Every signal carries the Polymarket market URL, the old and new {reading, unit, bucket}, and live YES/NO/midpoint odds for every bucket (with dead: true on buckets the day can no longer reach). Browsing is free and needs no auth; deeper signals are per-city bundles bought pay-per-call.

Full API docs: api.isocast.dev/llms.txt | OpenAPI spec: api.isocast.dev/openapi.json

What a signal is

A signal fires when a city's daily-high reading moves into a new Polymarket bucket. It includes the market URL, the old/new bucket readings, and current odds for every bucket, plus bucketsAsOf (odds freshness, ~10s) and observedAt. Delivery is at-most-once per (city, day, bucket), and seq is a monotonic per-city counter so you can track what you've seen.

Free endpoints (no auth, no payment)

| Method | Path | Description | |--------|------|-------------| | GET | /health | Liveness + configured payment mode (live|mock) | | GET | /v1/cities | All active cities (slug, unit, bucketWidth, timezone, latestSeq). 30s cache | | GET | /v1/cities/:slug | One city + today's target date + Polymarket market URL | | GET | /v1/sample?city=SLUG | A promo signal (fixed, never the latest) so you can see the shape before paying. sample: true | | GET | /v1/signals/meta?city=SLUG | Pricing + bundle tiers for a city (never returns signal rows) | | GET | /terms.txt · /terms.json | Terms of Service (also sets X-Terms-URL) |

Every JSON response also carries a disclaimer string.

Quick Start — Browse a City (free)

// All free, no auth, no setup
const BASE = "https://api.isocast.dev";

// 1. List active cities
const cities = await (await fetch(`${BASE}/v1/cities`)).json();
// cities: [{ slug, unit, bucketWidth, timezone, latestSeq }, ...]

// 2. Inspect today's market for one city
const city = await (await fetch(`${BASE}/v1/cities/istanbul`)).json();
// city: { slug, targetDate, marketUrl, ... }

// 3. See a sample signal shape before paying
const sample = await (await fetch(`${BASE}/v1/sample?city=istanbul`)).json();
// sample.signal: { marketUrl, old, new, buckets, observedAt, ... }, sample: true

Paid signals

Live signals are bought as prepaid per-city bundles (from $0.01), pay-per-call via x402 — the effective unit price drops with bundle size. Agents can use the isocast-mcp npm package (an MCP server) which handles payment for you, or read the full flow at api.isocast.dev/llms.txt. Entitled signals can also be pushed to a Telegram chat (free — the delivery registration route never charges).

Error Handling

402 — Payment required for a paid signal route. See the docs above for the payment flow.
429 — Rate limited. Respect the Retry-After header (seconds to wait).
404 — Unknown or inactive city.

Machine discovery

| Path | What | |------|------| | /llms.txt | This doc (concise) | | /openapi.json | OpenAPI 3.1 spec | | /discovery | Discovery JSON (free/paid endpoint listing) |

Disclaimer

Informational data only — not financial or betting advice. No guarantee of accuracy or outcome; prediction markets are restricted in some jurisdictions. Terms: https://isocast.dev/terms