Quickstart

Make your first API call in under 2 minutes.

1. Get your API key

   Create a free account at oddsstream.io/signup, then go to Dashboard → Keys and copy your key.

   Your key looks like this: os_live_a1b2c3d4e5f6... (32 hex characters after the prefix).

   Store it in an environment variable — never paste it directly into your code:

   export ODDSSTREAM_API_KEY=os_live_YOUR_KEY
   

   # Or add it to your .env file
   echo "ODDSSTREAM_API_KEY=os_live_YOUR_KEY" >> .env
   
2. Verify it works

   Call the sports endpoint — it requires no parameters and returns a list of sports with active odds right now.

   curl "https://api.oddsstream.io/api/sports" \
     -H "X-Api-Key: $ODDSSTREAM_API_KEY"
   

   You should see something like:

   {
     "data": [
       {
         "name": "Football",
         "competition_codes": ["EPL", "LIG1", "BUND", "SERA"],
         "event_count": 142
       },
       {
         "name": "Basketball",
         "competition_codes": ["NBA"],
         "event_count": 38
       }
     ],
     "meta": { "rate_limit_remaining": 199 }
   }
   

   • competition_codes — short codes for each league. You’ll use these to filter other endpoints.
   • event_count — how many matches have active odds right now.
   • rate_limit_remaining — how many requests you have left today (free plan: 200/day).

   Use competition codes like EPL and NBA to filter other endpoints — they’re more precise and stable than sport names.

3. Fetch odds for a specific league

   Get all EPL moneyline odds in one call:

   curl "https://api.oddsstream.io/api/odds?competition=EPL&market_type=moneyline" \
     -H "X-Api-Key: $ODDSSTREAM_API_KEY"
   

   import os, requests
   
   resp = requests.get(
       "https://api.oddsstream.io/api/odds",
       params={"competition": "EPL", "market_type": "moneyline", "limit": 50},
       headers={"X-Api-Key": os.environ["ODDSSTREAM_API_KEY"]}
   )
   for row in resp.json()["data"]:
       print(f"{row['match_name']} @ {row['bookmaker']}: {row['odds']}")
   

   Each row in data is one bookmaker’s odds for one market:

   {
     "bookmaker": "Betsson",
     "match_name": "Arsenal - Chelsea",
     "competition": "EPL",
     "market_type": "moneyline",
     "period": 0,
     "odds": {
       "Arsenal": 2.10,
       "Draw": 3.40,
       "Chelsea": 3.50
     },
     "scraped_at": "2026-04-20T14:11:09Z"
   }
   
4. Get value bets (Pro plan)

   Value Bets require a Pro plan or higher.

   Value bets are pre-calculated opportunities where a bookmaker offers higher-than-fair odds vs. Pinnacle’s sharp line. A +5% EV bet means you expect to profit $5 per$100 wagered long-run.

   curl "https://api.oddsstream.io/api/value-bets?sport=Football&min_ev=2" \
     -H "X-Api-Key: $ODDSSTREAM_API_KEY"
   

   {
     "data": [
       {
         "match_name": "PSG - Lyon",
         "selection": "Over 2.5",
         "bookmaker": "Betsson",
         "odds": 2.10,
         "fair_odds": 1.98,
         "ev_pct": 5.8,
         "detected_at": "2026-04-20T14:30:00Z"
       }
     ]
   }
   

   • fair_odds — Pinnacle’s price after removing their margin (the true probability).
   • ev_pct — your edge. 5.8 means +5.8% over fair value.

   Always verify the current price on the bookmaker’s site before placing. Odds can move between detection and placement.

5. Stream real-time changes (Free, Pro+ RT, or Pro+ Live)

   WebSocket requires a Free, Pro+ RT, or Pro+ Live plan. Free plan: 30 connections/day. Pro plan does not include WebSocket.

   WebSocket requires a two-step flow: first get a short-lived token, then connect.

   // Node.js — npm install ws
   import WebSocket from "ws";
   
   // Step 1: get a 5-minute token
   const { token } = await fetch("https://oddsstream.io/api/stream/token", {
     method: "POST",
     headers: { "X-Api-Key": process.env.ODDSSTREAM_API_KEY },
   }).then(r => r.json());
   
   // Step 2: connect with the token
   const ws = new WebSocket(
     `wss://api.oddsstream.io/api/stream?token=${token}&sport=Football`
   );
   
   ws.on("open", () => console.log("Connected"));
   ws.on("message", (raw) => {
     const msg = raw.toString();
     if (msg !== "pong")
       console.log(JSON.parse(msg));
   });
   

   Each message is one selection’s new price — typically 1–3 seconds after the scraper detects a change.

   See the WebSocket Setup Guide for keepalive, reconnection, and a complete production-ready client.

---

What’s next

WebSocket Setup Guide

Build a production live odds feed with reconnection and keepalive.

Value Bets Reference

Full docs for the /api/value-bets endpoint.

Best Practices

Polling cadence, EV interpretation, production patterns.

API Reference

Full endpoint reference with all parameters.