> ## Documentation Index
> Fetch the complete documentation index at: https://oddsstream.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Make your first API call in under 2 minutes.

<Steps>
  <Step title="Get your API key">
    Create a free account at [oddsstream.io/signup](https://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:

    ```bash theme={null}
    export ODDSSTREAM_API_KEY=os_live_YOUR_KEY
    ```

    ```bash theme={null}
    # Or add it to your .env file
    echo "ODDSSTREAM_API_KEY=os_live_YOUR_KEY" >> .env
    ```
  </Step>

  <Step title="Verify it works">
    Call the sports endpoint — it requires no parameters and returns a list of sports with active odds right now.

    ```bash theme={null}
    curl "https://api.oddsstream.io/api/sports" \
      -H "X-Api-Key: $ODDSSTREAM_API_KEY"
    ```

    You should see something like:

    ```json theme={null}
    {
      "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).

    <Tip>
      Use competition codes like `EPL` and `NBA` to filter other endpoints — they're more precise and stable than sport names.
    </Tip>
  </Step>

  <Step title="Fetch odds for a specific league">
    Get all EPL moneyline odds in one call:

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

    ```python theme={null}
    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:

    ```json theme={null}
    {
      "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"
    }
    ```
  </Step>

  <Step title="Get value bets (Pro plan)">
    <Note>Value Bets require a **Pro plan** or higher.</Note>

    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.

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

    ```json theme={null}
    {
      "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.

    <Warning>
      Always verify the current price on the bookmaker's site before placing. Odds can move between detection and placement.
    </Warning>
  </Step>

  <Step title="Stream real-time changes (Free, Pro+ RT, or Pro+ Live)">
    <Note>WebSocket requires a **Free, Pro+ RT, or Pro+ Live** plan. Free plan: 30 connections/day. Pro plan does not include WebSocket.</Note>

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

    ```javascript theme={null}
    // 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](/guides/websocket-setup) for keepalive, reconnection, and a complete production-ready client.
  </Step>
</Steps>

***

## What's next

<CardGroup cols={2}>
  <Card title="WebSocket Setup Guide" icon="plug" href="/guides/websocket-setup">
    Build a production live odds feed with reconnection and keepalive.
  </Card>

  <Card title="Value Bets Reference" icon="chart-line" href="/api-reference/value-bets">
    Full docs for the /api/value-bets endpoint.
  </Card>

  <Card title="Best Practices" icon="shield-check" href="/guides/best-practices">
    Polling cadence, EV interpretation, production patterns.
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Full endpoint reference with all parameters.
  </Card>
</CardGroup>