# Isocast — Weather-Signal Semantics

A single-topic deep-dive on what an Isocast signal *means*. For the API surface see
/llms.txt (compact) and /llms-full.txt (full, with JSON examples). Base: https://api.isocast.dev

## The market these signals track
Polymarket runs a daily "highest temperature in <city> on <date>" market for each covered city.
The outcomes are contiguous temperature **buckets** of width `bucketWidth` (e.g. 1°C: "28-29°C",
"29-30°C", …, plus an open-ended top bucket like "31°C or higher"). Exactly one bucket resolves
YES — the one containing the city's official daily-high reading at resolution. Isocast covers 37
cities; each city carries its own `unit` (C/F), `bucketWidth`, `timezone`, and `resolutionSource`.

## What triggers a signal: a bucket transition
Isocast watches each city's observed daily-high temperature through the market day. A signal is
emitted the instant the running daily-high crosses OUT of the bucket it was in and INTO a new
bucket — i.e. a new intraday maximum lands in a higher bucket than the previous maximum. Because
a daily *high* only ratchets upward within a day, transitions move monotonically up the bucket
ladder; the reading never re-enters a lower bucket on the same day.

Each signal records the crossing explicitly:
- `old` = { reading, unit, bucket } — the daily-high and its bucket just before the crossing
- `new` = { reading, unit, bucket } — the daily-high and its bucket just after the crossing
The physically meaningful event is `old.bucket → new.bucket`: the market's most-likely outcome
has shifted, and the odds on every bucket reprice.

## The bucket odds snapshot
Every signal carries `buckets[]` — live YES/NO/midpoint prices for EVERY bucket in the market at
`bucketsAsOf`, not just the new one. This lets an agent see the full repricing: the vacated
bucket collapsing, the new bucket firming, and the still-reachable higher buckets. `midpoint` is
the order-book midpoint (0–1). `bucketsAsOf` trails `observedAt` by ≤ ~10s — treat it as a
near-real-time snapshot, not a live quote.

## The `dead` bucket flag
A bucket carries `dead: true` when the day's reading can no longer land in it — i.e. the running
daily-high has already exceeded that bucket's ceiling, so it is now unreachable (its YES is
effectively 0). The just-vacated `old.bucket` and every bucket below it become dead once passed.
`dead` is only present (and true) on such buckets; reachable buckets omit the field. This is a
convenience flag on top of the odds, not a separate resolution.

## `seq` monotonicity
`seq` is a per-city, 1-based, strictly increasing counter over that city's signals across all
days. It never resets per day — it is the global ordering for the city. Use it as your cursor:
`GET /v1/signals?since=S` returns `since < seq ≤ paidThroughSeq` ascending. `latestSeq` (free, on
/v1/cities and /v1/signals/meta) is the highest published seq; `paidThroughSeq` is how far your
entitlement reaches. `/v1/sample` always returns `seq: 1` for shape inspection.

## Dedupe guarantee: at-most-once per (city, day, bucket)
Isocast emits AT MOST ONE signal per (city, market-day, destination bucket). Once a signal has
fired for the crossing into a given bucket on a given day, no further signal fires for that same
bucket that day — even if the reading wobbles or the odds keep moving. Consequences for agents:
- You will not be double-charged or double-notified for the same bucket crossing.
- The count of signals for a city on a day equals the number of DISTINCT higher buckets its
  daily-high climbed into that day (never more than the number of buckets above the day's open).
- Across days the same bucket *label* can recur (a fresh market each day) — dedupe is scoped to
  (city, day, bucket), and `seq` still increments globally per city.

## How agents typically use it
1. Poll free `/v1/cities` (or `/v1/signals/meta?city=`) for `latestSeq` to see new signals exist.
2. Buy a bundle via `POST /v1/subscribe?city=&count=` (x402) to extend `paidThroughSeq`.
3. Pull with `GET /v1/signals?city=&since=` (Bearer receipt), or register `POST /v1/delivery/telegram`
   to have entitled signals pushed to a chat the moment they fire.
Each signal hands you everything to act: `marketUrl` + `conditionId` to find the market, the
`old→new` bucket crossing, and full-book odds at `bucketsAsOf`.

Informational data only; not financial or betting advice. Terms: https://isocast.dev/terms