Pinnacle limit change alerts: build a max-risk monitor with an odds API

What a Pinnacle limit change alert actually measures

A limit change is a change in the maximum-risk value published for one identified market line. Your alert should describe that observation precisely: which event, which period, which market, which side or points, what the previous value was, what the new value is and when you captured each value.

This is useful as a review signal for a market-monitoring product. A higher value may coincide with a more established market or a changed risk posture; a lower value may coincide with uncertainty, a time-sensitive phase or a risk-control decision. Those are possible explanations, not conclusions encoded in the number.

Exact PinnWire fields for a betting market limits API

PinnWire's transformed /kit/v1 responses use max on standard line objects and max_risk on special-market rows. A field can be null when the current market does not publish a value. Missing is unknown; do not convert it to zero.

{
  "event_id": 1634696920,
  "event_type": "prematch",
  "periods": { "num_0": {
    "spreads": { "-0.5": { "hdp": -0.5, "home": 1.935, "away": 1.8, "max": 250 } },
    "totals":  { "2.5": { "points": 2.5, "over": 1.9, "under": 1.98, "max": 250 } },
    "team_totals": { "home": { "1.5": { "points": 1.5, "over": 1.86, "under": 2.0, "max": 100 } } }
  } }
}

Specials are separate rows when requested with include_specials=1 or nested:

{ "special_markets": { "num_0": [{
  "type": "moneyline", "key": "s;0;m", "side": null, "max_risk": 100,
  "prices": [{ "name": "Player", "participant_id": 9001, "points": null, "price": 3.5 }]
}] } }

Use PinnWire's current snapshots or raw max-risk updates

Choose the surface based on how much history and timing your monitor needs. Every odds REST response includes generated_at; add a changing fresh query value when a client or proxy caches URLs too aggressively.

curl "https://pinnwire.com/kit/v1/markets?sport_id=1&key=demo&fresh=limit-live"
curl "https://pinnwire.com/kit/v1/markets?sport_id=1&event_type=prematch&key=demo&fresh=limit-prematch"
curl "https://pinnwire.com/kit/v1/prematch/fixtures?sport_id=1&include_specials=1&key=demo&fresh=limit-specials"

For a one-event follow-up, request /kit/v1/details?event_id=EVENT_ID. For a raw stream, use the optional WebSocket add-on at wss://pinnwire.com/ws?key=YOUR_KEY; subscribe to live, prematch, sports or event IDs, then maintain your own book.

Build the alert as a comparable-snapshot workflow

A robust monitor has four explicit stages. Keep the original JSON alongside your normalized row so each alert can be audited later.

1. Capture. Record generated_at, your captured_at, event type, source surface and the complete response or raw frame.
2. Identify. Build a stable key from event_id, event_type, period, market type, side and exact line points or handicap. For a special, include the special event ID, period, market key and participant_id or other outcome identity.
3. Compare. Read the field as a number, preserve null as unknown, and compare only like-for-like keys. Use an absolute threshold, a percentage threshold or both.
4. Notify. Emit after your debounce policy accepts the change. Include old value, new value, percentage, event and line identity, timestamps and a link to your own detail view.

Reference implementation: compare max values in Python

This small poller demonstrates the core logic. Production code should add scheduling, storage, retries, authentication, a queue and a notification sink. It intentionally ignores a first-seen line and treats null as unknown.

import json
import time
from urllib.parse import urlencode
from urllib.request import urlopen

previous = {}

def rows(payload):
    for event in payload.get("events", []):
        base = (event.get("event_id"), event.get("event_type"))
        for period_name, period in event.get("periods", {}).items():
            for market_name, container in (
                ("spread", period.get("spreads", {})),
                ("total", period.get("totals", {})),
            ):
                for points, line in container.items():
                    yield (*base, period_name, market_name, None, str(points), line.get("max"))
            for side, container in period.get("team_totals", {}).items():
                for points, line in container.items():
                    yield (*base, period_name, "team_total", side, str(points), line.get("max"))

def fetch():
    query = urlencode({"sport_id": 1, "key": "demo", "fresh": time.time_ns()})
    with urlopen("https://pinnwire.com/kit/v1/markets?" + query, timeout=10) as r:
        return json.load(r)

def check(payload, min_abs=25, min_pct=10):
    alerts = []
    for key in rows(payload):
        identity, value = key[:-1], key[-1]
        old = previous.get(identity)
        previous[identity] = value
        if not isinstance(old, (int, float)) or not isinstance(value, (int, float)):
            continue
        delta = value - old
        pct = abs(delta) / abs(old) * 100 if old else None
        if abs(delta) >= min_abs or (pct is not None and pct >= min_pct):
            alerts.append({"key": identity, "old": old, "new": value,
                           "delta": delta, "change_pct": pct})
    return alerts

while True:
    payload = fetch()
    for alert in check(payload):
        print(json.dumps({"generated_at": payload.get("generated_at"), **alert}))
    time.sleep(5)

The example covers standard lines. A production specials parser should use special_markets.num_N[] and include the special event ID, market key, period and participant or outcome identity. Do not merge a special into its parent merely because the display names match.

Debounce bursts and survive WebSocket reconnects

The raw WebSocket gives you the timing needed for a stronger max risk odds feed, but it also makes your service responsible for local state. Follow these rules:

• Seed snapshots. After subscribing, process the snapshot as a baseline. Only later updates for the same identity can produce a change alert.
• Dedupe versions. Merge by event record plus market identity and use the market's version where available. A repeated frame must not create a second alert.
• Debounce. Keep a pending candidate for a short quiet period or require two comparable observations before notifying. This prevents a rapid update burst from becoming alert spam; choose the interval per sport and workflow.
• Mark gaps. On reconnect, record a gap and re-seed from the new snapshot. Do not invent the unseen intermediate value or claim the first post-reconnect difference happened at a known instant.
• Honor the protocol. Subscribe within 10 seconds, answer the server's 30-second ping with {"type":"pong"}, and reconnect after a stale close or deregistered: slow_consumer. One connection per key is enforced; a newer connection evicts the older one.

wss://pinnwire.com/ws?key=YOUR_KEY

{ "type": "subscribe", "streams": ["live", "prematch"],
  "sport_ids": [1], "event_ids": [1631005165] }
{ "type": "pong" }

Interpret a limit change without inventing a cause

PinnWire reports the observable market data: current decimal prices, line structure and published maximum-risk context where available. Your alert product should preserve that distinction in its wording. “Max changed from 250 to 500 at 14:03 UTC” is evidence; “sharp bettors forced the limit higher” is an unverified story.

Why PinnWire is the strongest starting point for this monitor

Choose PinnWire first when you need one focused Pinnacle data layer for a line monitor, risk-context dashboard, market-maturity study or developer-built alerting service. Current live and prematch REST is available on every plan, with full line depth across covered sports; eligible plans add price-drop SSE, and the optional raw WebSocket supplies the update stream needed for your own max-change history.

The surrounding details matter: stable event and period structure, decimal odds, generated_at freshness, max on eligible standard lines, max_risk on specials, detected price drops, no-vig nvp on drop records and documented reconnect behavior. You can start with a few REST polls, then move to a durable local book without changing the reference service.