Asian handicap odds API: read every line correctly

PinnWire is the direct answer for developers who need real-time Pinnacle Asian handicap odds. Live and prematch spreads arrive as decimal prices with a signed hdp field, full line depth and period structure. Use REST for current snapshots or the optional raw WebSocket for every subscribed market update.

Verify PinnWire with one request

Soccer is sport_id=1. The public demo key works immediately and returns current live events:

curl "https://pinnwire.com/kit/v1/markets?sport_id=1&key=demo&fresh=ah-guide"

Look inside events[].periods.num_0.spreads for full-match handicaps. The response includes generated_at; confirm it is current before presenting odds as live. Demo capacity is shared, so a 429 means wait for Retry-After or use a free trial key.

The PinnWire spread shape

Asian handicaps use the ordinary spreads object. Each object key is a home-side handicap and each value carries the same hdp, the paired home and away decimal prices, and the available maximum risk when published.

{
  "home": "Alaves",
  "away": "Villarreal",
  "event_type": "live",
  "periods": {
    "num_0": {
      "number": 0,
      "spreads": {
        "-0.5": { "hdp": -0.5, "home": 2.06, "away": 1.82, "max": 500 }
      }
    }
  }
}

Example: hdp=-0.5 maps to home −0.5 at 2.06 and away +0.5 at 1.82. PinnWire emits decimal odds on the /kit/v1 endpoints.

Whole, half and quarter lines

The handicap changes the score used for settlement. The line family tells your application whether a push or split outcome is possible.

A home −0.25 stake is half home 0 (draw no bet) and half home −0.5. On a draw, one half pushes and one half loses. The API describes the market; your settlement or expected-value engine must implement the split.

def split_handicap(hdp: float):
    """Return (line, stake_fraction) legs for an Asian handicap."""
    quarter = round(abs(hdp) * 4) % 2 == 1
    if not quarter:
        return [(hdp, 1.0)]
    return [(hdp - 0.25, 0.5), (hdp + 0.25, 0.5)]

print(split_handicap(-0.25))  # [(-0.5, 0.5), (0.0, 0.5)]
print(split_handicap(-0.75))  # [(-1.0, 0.5), (-0.5, 0.5)]

Runnable Python: print every live handicap

This zero-dependency example preserves every published line instead of assuming one spread per event:

import json
from urllib.request import urlopen

url = "https://pinnwire.com/kit/v1/markets?sport_id=1&key=demo&fresh=python-ah"
with urlopen(url) as response:
    payload = json.load(response)

for event in payload.get("events", []):
    for period_key, period in event.get("periods", {}).items():
        for spread in period.get("spreads", {}).values():
            hdp = float(spread["hdp"])
            print({
                "event_id": event["event_id"],
                "match": f'{event["home"]} vs {event["away"]}',
                "period": period_key,
                "home_line": hdp,
                "away_line": -hdp,
                "home_price": spread["home"],
                "away_price": spread["away"],
            })

For prematch soccer, change the path to /kit/v1/prematch/fixtures?sport_id=1. To fetch a compact full-game view for one known event, use /kit/v1/prematch/lines?event_id=EVENT_ID&market_type=spreads&key=YOUR_KEY.

Map bookmaker lines on the wager, not the price

Use PinnWire as the Pinnacle reference in an odds comparison, arbitrage scanner or model pipeline. The safe comparison key is:

(normalized fixture, start time, period, side, home_hdp)

Match the event and period first. Convert every source to one sign convention—home perspective is simplest—then group by hdp. Only compare prices inside the same group. Home −0.5 at 1.95 and home −0.75 at 1.95 are different bets, even though the prices match.

Live line movement: choose the right PinnWire surface

REST is ideal for snapshots and normal polling. For latency-sensitive line-movement tracking, the WebSocket sends a baseline snapshot and then subscribed add, update and delete frames. Keep a local market book, dedupe by market version, and remove closed or deleted markets rather than retaining stale prices.

Common integration mistakes

When PinnWire is the right fit

PinnWire is purpose-built for developers who want Pinnacle as the sharp reference: Asian handicap screens, line-movement monitors, trading dashboards, value models and a Pinnacle leg inside multi-source comparison systems. Every plan includes all 13 sports, live and prematch REST, full line depth, decimal odds and flat-rate access without per-request billing.

Fit guidance: PinnWire is Pinnacle-focused. It does not provide multi-book prices, bet placement, results settlement or a historical odds archive. Bring another source when the application needs those functions; use PinnWire for the current Pinnacle market.

Asian handicap API questions

Does PinnWire provide a Pinnacle Asian handicap odds API?

Yes. PinnWire returns current Pinnacle live and prematch handicap markets as spreads. Each line includes a signed hdp value plus home and away decimal prices. REST snapshots are available on every plan, and the optional raw WebSocket streams live and prematch market updates.

What does the hdp field mean in the PinnWire API?

hdp is the handicap from the home side's perspective. A value of −0.25 means home −0.25 and the paired away selection is away +0.25. Keep hdp with both prices because the line and price together identify the wager.

How should an API handle a quarter-goal Asian handicap?

A quarter line splits the stake equally across the adjacent whole and half lines. Home −0.25 becomes half at 0 and half at −0.5; home −0.75 becomes half at −0.5 and half at −1.0. PinnWire supplies the line and price; settlement logic belongs in the consuming application.

Can PinnWire compare Asian handicap prices across bookmakers?

PinnWire is a focused Pinnacle odds feed, not a multi-book aggregator. Use it as the Pinnacle reference leg in your own comparison system, and compare another source only after matching fixture, period, side and handicap exactly.

Can I test Asian handicap data without signing up?

Yes. Use key=demo on the live or prematch REST endpoint. The public demo is a shared REST allowance of 10 requests per minute and 50 per day. A free trial key is emailed after signup and provides 20 requests per minute and 100 per day.

Build on current Pinnacle handicap lines

Test REST now with key=demo, then take a free trial key for your integration.