← Docs

POST /v1/weather-probability

A daily-high temperature probability for Kalshi & Polymarket weather markets — the flagship verified specialist. Returns the YES probability for the bracket, the forecast mean and standard deviation (mean_f / std_f), and the agent's rolling 30-day hit rate. The settled track record is free; reading an upcoming probability costs 1 credit (anonymous callers get a teaser).

Hello world

Three steps, about 90 seconds: mint a key, paste the curl, see the probability.

# 1. Mint a trader key through the device-flow helper
npx licium-cli@latest key weather-bot
export LICIUM_API_KEY=ak_...

# 2. Paste it and curl
curl -X POST https://www.licium.ai/v1/weather-probability \
  -H "Authorization: Bearer $LICIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kalshi_ticker": "KXHIGHNY-26MAY16-T70"}'

Expected response (200):

{
  "success": true,
  "data": {
    "probability": 0.41,
    "confidence": 0.7,
    "confidence_tier": "MEDIUM",
    "bracket": { "kind": "binary_above", "thresholdF": 70 },
    "bracket_key": "T70",
    "mean_f": 70.4,
    "std_f": 1.3,
    "rationale": "41% probability for the T70 outcome (moderate confidence). Central estimate ~70.4°F.",
    "rationale_pending": false,
    "sources": [
      { "type": "kalshi_ticker", "value": "KXHIGHNY-26MAY16-T70" },
      { "type": "station", "value": "KLGA|nyc|2026-05-16" }
    ],
    "asof": "2026-05-16T03:30:00Z",
    "signal_as_of": "2026-05-16T03:30:00Z",
    "freshness": {
      "status": "active",
      "as_of": "2026-05-16T03:30:00.000Z",
      "expires_at": "2026-05-16T04:30:00.000Z",
      "age_minutes": 0,
      "max_age_minutes": 60,
      "recommendation": "enter_now_ok",
      "reason": "Signal is inside the public entry window."
    },
    "agent": {
      "name": "Weather Agent v1",
      "recent_days": 30,
      "recent_hit_rate": 0.78,
      "recent_n": 87
    }
  },
  "quota": { "tier": "free", "used": 7, "limit": 100, "resets_at": null }
}

Input shapes

Pick one. The endpoint resolves all three to the same resolved inputs (station_id, target_date, bracket).

1. Kalshi ticker (primary path)

{ "kalshi_ticker": "KXHIGHNY-26MAY16-T70" }

Supported series: KXHIGHNY, KXHIGHCHI, KXHIGHAUS, KXHIGHLAX. Format: KXHIGH{CITY}-{YYMMM-DD}-T{F}. Range-bracket tickers (-B{F}.5) aren't supported in v1.

2. Polymarket slug + token id

{
  "polymarket_slug": "0x7f4961114efc6b...",
  "polymarket_token_id": "115460934613582062..."
}

slug accepts a conditionId (0x...) or url-slug. Adds 1 Gamma fetch (~200ms).

3. Raw station + date + bracket

{
  "station_id": "KLGA",
  "target_date": "2026-05-16",
  "low_f": 70,
  "high_f": 71
}

Stations: KLGA, KNYC, KMDW, KORD, KLAX, KAUS, KSEA, KHOU, KDAL, KATL. Omit low_f/high_f to get the raw forecast distribution (mean/std with probability: null).

Errors

Every failure returns the standard envelope { success: false, error, code? }. This endpoint emits the code as errorType and adds a docs URL.

Versioning

v1 is stable. Breaking changes go to /v2 with a 90-day deprecation notice on v1. Every response carries an X-API-Version header.

Pricing & rate limits

A live read with a 0 balance returns 402 Payment Required with a machine-readable top-up pointer. 4xx and 5xx responses don't count toward your daily quota. Enterprise pricing: email hello@licium.ai.

Latency & caching

Cache lookup spans the last 6h, but public entry freshness is 1h. A cache row older than the entry window is recomputed inline before returning a tradable probability. Every full response includes freshness; only use rows whose recommendation is enter_now_ok. A plain-language narrative is always returned in rationale; rationale_pending is always false.

Coverage: supported cities globally across Kalshi and Polymarket weather markets. See the Weather Agent profile for the rolling 30-day hit rate (the same number this endpoint returns).