# Real-time Underdog line alerts, in one file.

> Copy a working Python or Node.js consumer for recorded Underdog line alerts: Server-Sent Events, Last-Event-ID resume and line-move filters. Underdog API (https://underdogapi.com) is an independent Underdog Fantasy pick'em data API: Higher/Lower lines with separate payout multipliers per side, line history, changes and graded results as JSON, CSV, MCP and streams.

Canonical page: https://underdogapi.com/tools/alert-consumer

## Free offer

**Free API key, no card: 100 credits a month** on the live board, every league, separate Higher/Lower prices, and the last 24 hours of line history. Sign up: https://underdogapi.com/sign-up?ref=ai-claudebot

## Quickstart

1. Get a free key at https://underdogapi.com/sign-up?ref=ai-claudebot (no card), or let your agent request one: `POST https://underdogapi.com/api/v1/agent/signup` with `data_wanted` and `use_case`, then show your user the returned approval_url.
2. Export it: `export UNDERDOG_API_KEY=ud_...`
3. First call with curl:

```bash
curl --fail-with-body 'https://underdogapi.com/api/v1/projections?league=NBA&view=compact&limit=5' \
  -H "Authorization: Bearer $UNDERDOG_API_KEY" \
  -H 'X-User-Request: NBA dashboard integration check'
```

4. Same call in Python:

```python
import os, requests

r = requests.get(
    "https://underdogapi.com/api/v1/projections",
    params={"league": "NBA", "view": "compact", "limit": 5},
    headers={"Authorization": f"Bearer {os.environ['UNDERDOG_API_KEY']}"},
)
r.raise_for_status()
for line in r.json()["data"]:
    print(line["player"]["name"], line["market"]["stat"], line["line"])
```

## Use it from Claude (MCP)

Claude Code, one command:

```bash
claude mcp add --transport http underdog https://underdogapi.com/api/mcp --header "Authorization: Bearer $UNDERDOG_API_KEY"
```

Or add this server to your Claude MCP configuration (the key stays in the environment):

```json
{
  "mcpServers": {
    "underdog": {
      "type": "http",
      "url": "https://underdogapi.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${UNDERDOG_API_KEY}"
      }
    }
  }
}
```

Guide: https://underdogapi.com/use-with-claude

## Pricing

| Plan | Price | Credits / month | Notes |
| --- | --- | --- | --- |
| Free | $0 | 100 | No card. Live feed 5 minutes behind; last 24 hours of line history |
| Developer | $49/month | 10,000 | For models that need full training pages and loaded game-log seasons. Live feed, no added plan delay |
| Production | $149/month | 50,000 | For apps with real users and push delivery. Everything in Developer, signed webhooks for every change |
| Scale | $499/month | 250,000 | For apps whose traffic has outgrown Production. Everything in Production, 15 live-feed connections at once |

Full pricing: https://underdogapi.com/pricing

## On this page

Code



Copy a consumer for the line-change stream, set your key, and run it. It prints every line move you care about and picks up exactly where it left off after any disconnect.

[Python consumer](https://underdogapi.com/tools/alert-consumer#python) [Node.js consumer](https://underdogapi.com/tools/alert-consumer#node)

Transport **Server-Sent Events**

Resume **Last-Event-ID**

Delay on Production **Instant**

Dependencies **None**

Endpoint: [GET /api/v1/stream](https://underdogapi.com/docs#stream). Both files were run against the stream's exact wire format: resume after reconnect, a 429 with Retry-After, a server error frame, and a restart from a saved cursor.

## Python

Standard library only. Save as line_alerts.py.

line_alerts.py

```
#!/usr/bin/env python3
"""Line-move alerts from the underdogapi.com change stream (SSE).

Standard library only. Resumes from the last applied event with Last-Event-ID,
so a restart or a dropped connection never skips or repeats an alert.
Run:  UNDERDOG_API_KEY=ud_... python3 line_alerts.py
"""
import json
import os
import sys
import time
from urllib.error import HTTPError, URLError
from urllib.parse import urlencode
from urllib.request import Request, urlopen

BASE = os.environ.get("UNDERDOG_BASE", "https://underdogapi.com")
KEY = os.environ["UNDERDOG_API_KEY"]
STATE_FILE = os.environ.get("STREAM_STATE", "last_event_id.txt")
FILTERS = {"league": "NBA", "type": "line.moved"}
MIN_MOVE = 0.5  # alert only when the line moves at least this much

def load_cursor():
    try:
        with open(STATE_FILE) as f:
            return f.read().strip() or None
    except FileNotFoundError:
        return None

def save_cursor(cursor):
    tmp = STATE_FILE + ".tmp"
    with open(tmp, "w") as f:
        f.write(cursor)
    os.replace(tmp, STATE_FILE)  # atomic: never a half-written cursor

def on_event(kind, event):
    prev, line = event.get("previous_line"), event.get("line")
    if kind != "line.moved" or not isinstance(prev, (int, float)) or not isinstance(line, (int, float)):
        return
    if abs(line - prev) >= MIN_MOVE:
        print(f"{event['observed_at']}  {event['league']}  {event['player_name']}  "
              f"{event['stat']}: {prev} -> {line}", flush=True)

def stream_once(cursor):
    """Read one connection until the server asks for a reconnect. Returns (cursor, retry_seconds)."""
    headers = {"Authorization": "Bearer " + KEY, "Accept": "text/event-stream"}
    if cursor:
        headers["Last-Event-ID"] = cursor
    request = Request(BASE + "/api/v1/stream?" + urlencode(FILTERS), headers=headers)
    retry = 2.0
    # Heartbeats arrive every 15 s, so a 60 s read timeout only fires on a dead connection.
    with urlopen(request, timeout=60) as response:
        event_id, kind, data = None, None, []
        for raw in response:
            text = raw.decode("utf-8").rstrip("\r\n")
            if text == "":  # blank line: dispatch the event
                if data:
                    payload = "\n".join(data)
                    if kind == "reconnect":
                        return cursor, retry
                    if kind == "error":
                        raise ConnectionError(payload)
                    on_event(kind, json.loads(payload))
                    if event_id:
                        cursor = event_id
                        save_cursor(cursor)  # after handling: at-least-once delivery
                event_id, kind, data = None, None, []
                continue
            if text.startswith(":"):  # comment: connected banner or heartbeat
                continue
            field, _, value = text.partition(":")
            value = value[1:] if value.startswith(" ") else value
            if field == "id":
                event_id = value
            elif field == "event":
                kind = value
            elif field == "data":
                data.append(value)
            elif field == "retry" and value.isdigit():
                retry = int(value) / 1000
    return cursor, retry

def main():
    cursor, backoff = load_cursor(), 2
    print("Resuming after", cursor or "the newest event", file=sys.stderr)
    while True:
        try:
            cursor, retry = stream_once(cursor)
            backoff = 2
            time.sleep(retry)
        except HTTPError as error:
            body = error.read().decode("utf-8", errors="replace")
            if error.code in (400, 401, 403):
                sys.exit(f"HTTP {error.code}: {body}")  # bad key or query: retrying will not help
            wait = int(error.headers.get("Retry-After") or backoff)
            print(f"HTTP {error.code}, retrying in {wait}s", file=sys.stderr)
            time.sleep(wait)
            backoff = min(backoff * 2, 60)
        except (URLError, ConnectionError, TimeoutError, OSError) as error:
            print(f"Connection lost ({error}), retrying in {backoff}s", file=sys.stderr)
            time.sleep(backoff)
            backoff = min(backoff * 2, 60)

if __name__ == "__main__":
    try:
        main()
    except KeyboardInterrupt:
        pass
```

## Node.js

Node 18 or later, no dependencies. Save as line-alerts.mjs.

line-alerts.mjs

```
// Line-move alerts from the underdogapi.com change stream (SSE). Node 18+, no dependencies.
// Resumes with Last-Event-ID, so a restart or dropped connection never skips or repeats an alert.
// Run:  UNDERDOG_API_KEY=ud_... node line-alerts.mjs
import { readFile, rename, writeFile } from "node:fs/promises";

const BASE = process.env.UNDERDOG_BASE ?? "https://underdogapi.com";
const KEY = process.env.UNDERDOG_API_KEY;
const STATE_FILE = process.env.STREAM_STATE ?? "last_event_id.txt";
const FILTERS = new URLSearchParams({ league: "NBA", type: "line.moved" });
const MIN_MOVE = 0.5;
const sleep = (s) => new Promise((r) => setTimeout(r, s * 1000));

async function loadCursor() {
  try { return (await readFile(STATE_FILE, "utf8")).trim() || null; } catch { return null; }
}
async function saveCursor(cursor) {
  await writeFile(STATE_FILE + ".tmp", cursor);
  await rename(STATE_FILE + ".tmp", STATE_FILE); // atomic
}

function onEvent(kind, e) {
  if (kind !== "line.moved" || typeof e.previous_line !== "number" || typeof e.line !== "number") return;
  if (Math.abs(e.line - e.previous_line) >= MIN_MOVE) {
    console.log(`${e.observed_at}  ${e.league}  ${e.player_name}  ${e.stat}: ${e.previous_line} -> ${e.line}`);
  }
}

class HttpError extends Error {
  constructor(status, body, retryAfter) { super(`HTTP ${status}: ${body}`); Object.assign(this, { status, retryAfter }); }
}

// Reads one connection until the server sends "reconnect". Returns { cursor, retry }.
async function streamOnce(cursor) {
  const headers = { Authorization: `Bearer ${KEY}`, Accept: "text/event-stream" };
  if (cursor) headers["Last-Event-ID"] = cursor;
  const res = await fetch(`${BASE}/api/v1/stream?${FILTERS}`, { headers });
  if (!res.ok) throw new HttpError(res.status, await res.text(), Number(res.headers.get("retry-after")) || null);

  const decoder = new TextDecoder();
  let buffer = "", retry = 2, id = null, kind = null, data = [];
  for await (const chunk of res.body) {
    buffer += decoder.decode(chunk, { stream: true });
    let newline;
    while ((newline = buffer.indexOf("\n")) >= 0) {
      const line = buffer.slice(0, newline).replace(/\r$/, "");
      buffer = buffer.slice(newline + 1);
      if (line === "") { // blank line: dispatch
        if (data.length) {
          const payload = data.join("\n");
          if (kind === "reconnect") return { cursor, retry };
          if (kind === "error") throw new Error(`stream error: ${payload}`);
          onEvent(kind, JSON.parse(payload));
          if (id) { cursor = id; await saveCursor(cursor); } // after handling: at-least-once
        }
        id = null; kind = null; data = [];
        continue;
      }
      if (line.startsWith(":")) continue; // connected banner or heartbeat
      const colon = line.indexOf(":");
      const field = colon < 0 ? line : line.slice(0, colon);
      let value = colon < 0 ? "" : line.slice(colon + 1);
      if (value.startsWith(" ")) value = value.slice(1);
      if (field === "id") id = value;
      else if (field === "event") kind = value;
      else if (field === "data") data.push(value);
      else if (field === "retry" && /^\d+$/.test(value)) retry = Number(value) / 1000;
    }
  }
  return { cursor, retry }; // connection closed without a reconnect event
}

if (!KEY) throw new Error("Set UNDERDOG_API_KEY");
let cursor = await loadCursor(), backoff = 2;
console.error("Resuming after", cursor ?? "the newest event");
for (;;) {
  try {
    const next = await streamOnce(cursor);
    cursor = next.cursor; backoff = 2;
    await sleep(next.retry);
  } catch (error) {
    if (error instanceof HttpError && [400, 401, 403].includes(error.status)) throw error; // bad key or query
    const wait = error.retryAfter ?? backoff;
    console.error(`${error.message}, retrying in ${wait}s`);
    await sleep(wait);
    backoff = Math.min(backoff * 2, 60);
  }
}
```

## How resume works

1. **Every event has an id.** It is the change cursor, the same value as `id` in [/api/v1/changes](https://underdogapi.com/docs#changes).
2. **Save it after you act.** The consumers write the id to a file only after handling the event, so a crash replays at most one event and never skips one.
3. **Send it back.** On reconnect, `Last-Event-ID` tells the server where to continue. Without it, the stream starts at the newest event.
4. **Reconnect on cue.** Each connection ends after about 285 seconds with `event: reconnect`. Comment heartbeats every 15 seconds keep proxies from closing an idle stream.
5. **Back off on errors.** 400 and 401 stop the consumer, since retrying cannot fix a bad key. 429 waits for `Retry-After`; anything else retries with exponential backoff up to a minute.

On the wire

```
retry: 2000
: connected plan=developer delay=0s cursor=48211

id: 48212
event: line.moved
data: {"id":"48212","type":"line.moved","projection_id":"ud_…","league":"NBA","player_name":"…","stat":"Points","previous_line":24.5,"line":25.5,"observed_at":"…","cursor":"48212"}

: heartbeat 2026-10-28T20:15:00.000Z

event: reconnect
data: {"cursor":"48212"}
```

## Delay and connections by plan

| Plan | Stream delay | Concurrent streams | Requests a month |
| --- | --- | --- | --- |
| Free | 300s | 1 | 100 |
| Developer | No added plan delay | 3 | 10,000 |
| Production | No added plan delay | 10 | 50,000 |
| Scale | No added plan delay | 15 | 250,000 |

A connection counts as one request. Prefer push to your server instead of holding a connection open? [Signed webhooks](https://underdogapi.com/underdog-api-webhooks) deliver the same events on Production and Scale.

## Questions

Does the Underdog API have a websocket?

It streams over Server-Sent Events instead: a plain HTTPS response that stays open and pushes each change as it is recorded. SSE works through proxies, resumes natively with Last-Event-ID, and needs no client library in Python or Node.

What happens if my consumer disconnects?

Nothing is lost. Both consumers save the id of the last event they handled and send it as Last-Event-ID when they reconnect; the stream continues right after it. A cursor saved before a restart works the same way.

How recorded is the stream on each plan?

Free runs 5 minutes behind. Developer, Production and Scale have no added plan delay. Line moves arrive from the source's own push, typically within about a second. New offers need a board read, so they usually arrive later than moves.

How many requests does a stream use?

One per connection. A connection lasts about 285 seconds, so a consumer left running uses about 9,031 requests a month. That fits the Developer plan; on Free, run it for a slate rather than around the clock.

## Keep going

[Endpoint **GET /api/v1/stream** *Filters, headers and limits.*](https://underdogapi.com/docs#stream) [Guide **Line movement from the change feed** *The polling version, on every plan.*](https://underdogapi.com/underdog-line-movement-api) [Guide **Signed webhooks** *Verify signatures and handle retries.*](https://underdogapi.com/underdog-api-webhooks) [Tool **Line and payout explorer** *Current board lines with official multipliers and derived break-evens.*](https://underdogapi.com/tools/line-explorer) [Dataset **Recorded history sample (CSV)** *One completed day of change events, with a coverage calendar.*](https://underdogapi.com/data/history-sample) [Pricing **Plans and request limits** *Free 100 credits a month. Paid plans from $49.*](https://underdogapi.com/pricing)

[Get free API key](https://underdogapi.com/sign-up)

## References

- [API reference: stream](https://underdogapi.com/docs#stream)
- [WHATWG HTML: server-sent events](https://html.spec.whatwg.org/multipage/server-sent-events.html)
- [MDN: Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After)

## FAQ

### Is there a free Underdog API?

Yes. The Free plan is a real API key on the live board, not a sample: 100 credits a month, every league, separate Higher/Lower prices and the last 24 hours of line history. No card is needed.

### Is this the official Underdog Fantasy API?

No. Underdog API is an independent data service. It is not affiliated with, endorsed by or sponsored by Underdog Fantasy or Underdog Sports.

### What data does it return?

Underdog Higher/Lower lines with separate payout multipliers and availability for each side, stable market ids through line moves, alternate rungs, recorded line history, changes, graded results and coverage/status endpoints.

### How do I use it from Claude or another AI agent?

Connect the MCP server at https://underdogapi.com/api/mcp with a bearer key, or call the REST API. Agents can request a key for their user with POST /api/v1/agent/signup.

### How much does it cost after the free tier?

Developer is $49/month for 10,000 credits, Production $149/month for 50,000, Scale $499/month for 250,000. Errors and unchanged 304 responses cost zero credits.

### How fresh is the data?

Each row carries its observation time. Check /api/v1/status and /api/v1/coverage before relying on a sport or window; missing collection is reported as unavailable, never filled in.

### Does it place entries or give picks?

No. It is data only: no entries, account operations, guaranteed outcomes or betting advice.

---
Independent data service, not affiliated with Underdog Fantasy or Underdog Sports. Docs: https://underdogapi.com/docs · OpenAPI: https://underdogapi.com/openapi.json · llms.txt: https://underdogapi.com/llms.txt
