> For the complete documentation index, see [llms.txt](https://rock-odds.gitbook.io/rock-odds-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rock-odds.gitbook.io/rock-odds-docs/sse-quickstart.md).

# SSE quickstart

Connect to the real-time stream, receive the initial snapshot, and observe incremental odds events.

## Before you begin

You need:

* Your RockOdds API key
* A terminal with `curl`
* The production base URL: `https://rockodds.live/api/v2`

The stream is a long-lived HTTP response. It defaults to pregame odds, can include both pregame and live odds, and sends a heartbeat approximately every 30 seconds.

## 1. Store your API key

```bash
export ODDS_API_KEY="YOUR_API_KEY"
```

Do not commit API keys to source control or expose them in public browser code.

## 2. Connect with curl

Open an NBA stream containing both pregame and live games:

```bash
curl --no-buffer \
  --url "https://rockodds.live/api/v2/stream?sport=NBA&game_status=all" \
  --header "X-API-Key: ${ODDS_API_KEY}"
```

`--no-buffer` prints each event as soon as it arrives. The first frame is a `snapshot`:

```
event: snapshot
data: {"count":1,"games":[...]}
```

Leave the command running to see updates and heartbeats. Press `Ctrl+C` to disconnect.

## 3. Understand the event flow

Use the snapshot to initialize your local state, then apply each event in order:

| Event                      | Action                                                               |
| -------------------------- | -------------------------------------------------------------------- |
| `snapshot`                 | Replace all local state for this connection.                         |
| `update`                   | Merge the market metadata and replace the identified market's lines. |
| `locked`                   | Mark the identified market unavailable.                              |
| `game_add` or `market_add` | Add or replace the supplied game.                                    |
| `game_remove`              | Delete the game.                                                     |
| `live_update`              | Update the game's `live` value.                                      |
| `heartbeat`                | No state change. Use it to monitor the connection.                   |

Store games by `game_id` and markets by `market_id`. Treat both IDs as opaque strings.

## 4. Connect with Python

Install `httpx`:

```bash
pip install httpx
```

Then run:

```python
import json
import os

import httpx


url = "https://rockodds.live/api/v2/stream"
headers = {"X-API-Key": os.environ["ODDS_API_KEY"]}
params = {"sport": "NBA", "game_status": "all"}
timeout = httpx.Timeout(65.0, connect=10.0)

with httpx.stream(
    "GET",
    url,
    headers=headers,
    params=params,
    timeout=timeout,
) as response:
    response.raise_for_status()
    event_type = None

    for line in response.iter_lines():
        if line.startswith("event:"):
            event_type = line.removeprefix("event:").strip()
        elif line.startswith("data:") and event_type:
            data = json.loads(line.removeprefix("data:").strip())
            print(event_type, data)
            event_type = None
```

This example prints events to confirm the connection. For production, apply them to local state and reconnect with backoff after disconnection.

## 5. Connect with JavaScript

Browser `EventSource` cannot set an `X-API-Key` header, so it uses the query parameter:

```javascript
const url = new URL("https://rockodds.live/api/v2/stream");
url.searchParams.set("api_key", "YOUR_API_KEY");
url.searchParams.set("sport", "NBA");
url.searchParams.set("game_status", "all");

const stream = new EventSource(url);

stream.addEventListener("snapshot", (event) => {
  const snapshot = JSON.parse(event.data);
  console.log("Initial games:", snapshot.games);
});

stream.addEventListener("update", (event) => {
  const update = JSON.parse(event.data);
  console.log("Market updated:", update);
});

stream.addEventListener("heartbeat", () => {
  console.log("Stream connected");
});

stream.onerror = () => {
  console.log("Stream interrupted; EventSource will reconnect");
};
```

{% hint style="warning" %}
Do not expose an API key in a public website. Proxy the stream through your backend when browser users must consume it.
{% endhint %}

## Next steps

* Use the complete [streaming reference](/rock-odds-docs/endpoints/streaming.md) to implement every event type.
* Follow the [reconnection and recovery guidance](/rock-odds-docs/endpoints/streaming.md#reconnection-and-recovery).
* Review [stream errors and connection limits](/rock-odds-docs/errors-and-limits.md).
