Pinnacle Odds API Tutorial: First Live Response Fast

A copy-paste Pinnacle odds API tutorial: go from no account to a parsed live odds response in minutes, on a free key, with sub-second pushed pricing.

Here is the number that matters before you write a line of code: from the moment Pinnacle emits an odds frame to the moment it lands in your client, pinnapi runs about 15–40 ms end to end. Prices are pushed sub-second over MQTT/WebSocket and SSE — we do not poll and hope. For comparison, polled aggregators are seconds-stale by design, and even other push feeds we've measured tend to sit around ~200 ms before the update reaches you.

That latency budget is the whole reason this guide exists. If you're going to act on Pinnacle prices, the feed has to be close to real time, or you're trading on history. So let's get a live response into your terminal, then into Python — no card, no email verification, on the free trial key.

What you actually need

A terminal with curl, or Python 3.8+ for the scripted version. That's it. No SDK to install, no OAuth handshake, no billing form.

The free trial covers every REST endpoint at 100 requests per day. The one thing it leaves out is the SSE drop stream — I'll come back to that, because it's the feature you'll eventually want most.

Step 1 — Grab a trial key

Go to the pinnapi homepage and generate a key. The key is your login. There's no separate account, no password, no confirmation email sitting in a spam folder. Copy it somewhere you can reach it, because every request carries it.

Two ways to authenticate:

• Header (use this): x-portal-apikey: YOUR_KEY
• Query string (fine for a one-off test): ?key=YOUR_KEY

Prefer the header in real code. Keys in query strings have a habit of ending up in access logs, shell history, and browser caches.

Step 2 — Prove you're connected before you debug a phantom

It's tempting to skip straight to odds. Don't. Two lightweight calls tell you whether the problem is your network or your key, which saves you from staring at a 401 later wondering which half is broken.

curl -s "https://pinnapi.com/ping"
curl -s -H "x-portal-apikey: YOUR_KEY" "https://pinnapi.com/health"

/ping says the service is reachable. /health says the service is up and your key is being accepted. Clean response from /health means you're authenticated. Move on.

Step 3 — Pull your first live board

This is the line you came for. Live markets sit behind GET /kit/v1/markets. Pass event_type=live for in-play:

curl -s -H "x-portal-apikey: YOUR_KEY" \
  "https://pinnapi.com/kit/v1/markets?event_type=live"

One call returns the live board — events, their markets, current prices, straight off the Pinnacle live odds feed. Because the pipe is sub-second, what you're reading is what the sharp market is pricing now, not a snapshot a poller scraped a minute ago and cached.

Need pre-game instead? Flip one parameter:

curl -s -H "x-portal-apikey: YOUR_KEY" \
  "https://pinnapi.com/kit/v1/markets?event_type=prematch"

Step 4 — Parse it in Python

Same flow, scripted. This odds API Python example fetches the live board and prints enough to see the shape of the data before you build anything on top of it.

import requests

API_KEY = "YOUR_KEY"
BASE = "https://pinnapi.com"
HEADERS = {"x-portal-apikey": API_KEY}

def get_live_markets():
    resp = requests.get(
        f"{BASE}/kit/v1/markets",
        headers=HEADERS,
        params={"event_type": "live"},
        timeout=10,
    )
    resp.raise_for_status()
    return resp.json()

data = get_live_markets()

for event in data[:5]:
    print(event)

Run it twice, a few seconds apart, on a live event. The prices move. That movement is the signal that you're on a real-time feed and not a stale mirror.

A couple of things will trip you up the first time:

• A 401 is almost always the header — check x-portal-apikey for a typo or trailing space.
• An empty list usually means nothing is in play for that filter right now, not that something's broken. Re-run with event_type=prematch to confirm the pipe is flowing.

And if you've already written a Pinnacle-style client? You can skip most of this. pinnapi is drop-in compatible: point your base URL at https://pinnapi.com, set x-portal-apikey, and your existing code keeps working. The fastest production integration I've seen is genuinely a two-line diff.

Step 5 — Drill into one event efficiently

/kit/v1/markets is the wide-angle view. For depth on a single event, use /kit/v1/details. For prematch work, there's a deliberate fixtures → markets → lines split:

• GET /kit/v1/prematch/fixtures — upcoming events
• GET /kit/v1/prematch/markets — markets for those fixtures
• GET /kit/v1/prematch/lines — the priced lines

curl -s -H "x-portal-apikey: YOUR_KEY" \
  "https://pinnapi.com/kit/v1/prematch/fixtures"

That separation is not bureaucracy — it's how you stay efficient. Poll fixtures occasionally, since the slate doesn't change minute to minute. Fetch lines frequently, but only for the handful of events you actually care about. You keep prices fresh and stay well inside the trial's daily cap. The endpoint reference in the docs lists every field and parameter if you need the full schema.

A word on big tournaments

Marquee events are exactly where latency and line movement earn their place in your stack. The 2026 FIFA World Cup, co-hosted by the USA, Canada, and Mexico across June and July, will throw heavy, fast-moving markets at you around the biggest fixtures.

Resist the urge to hard-code a match, a date, or a scoreline. Tournaments are live, draws shift, and a wrong constant is worse than no constant. Let the API tell you what's happening:

# whatever is in play right now, across sports
curl -s -H "x-portal-apikey: YOUR_KEY" \
  "https://pinnapi.com/kit/v1/markets?event_type=live"

Your code reflects reality as it happens instead of a guess baked in at build time.

The capability worth graduating to: odds drops

Once you're reading prices comfortably, the next thing to learn is odds-drop detection — catching when a market's price falls sharply against its recent history. That's often where money is moving, and catching it late is the same as missing it.

Two ways to consume drops, and they're not equivalent:

REST polling via GET /api/drops?mode=live (or mode=prematch) returns recent drops on demand and is available on the trial. It's fine for building and understanding the data.

The SSE stream is the real tool. It pushes drop alerts the instant they fire — same sub-second discipline as the rest of the feed — so you react when the move happens rather than on your next poll cycle. It's a paid feature, not in the trial.

curl -s -H "x-portal-apikey: YOUR_KEY" \
  "https://pinnapi.com/api/drops?mode=live"

The 100-request daily trial cap is plenty for wiring this up and testing your parsing. When you want the live SSE stream and real throughput, paid plans start at $99/mo — see the pricing page for what each tier includes.

Troubleshooting, quickly

• 401 Unauthorized: header name is exactly x-portal-apikey. Watch for stray whitespace.
• Empty array: nothing matches your filter right now. Switch event_type or hit a prematch endpoint.
• 429 Too Many Requests: you've hit the 100/day trial cap. Cache during development and poll only what you need.

Takeaway

The path to a live Pinnacle odds feed in your code is short: key, health check, GET /kit/v1/markets?event_type=live, parse, drill down. Build against the live endpoint first so you're testing against the real sub-second feed, lean on the prematch fixtures/markets/lines split to stay efficient, and move to drop detection once your parsing is solid. If you already run a Pinnacle-style client, the smartest first move is the smallest one — swap the base URL and the header, and measure the latency yourself.