JavaScript SDK - TheRundown API

An official JavaScript/TypeScript SDK is coming soon. In the meantime, this guide shows how to use TheRundown API directly with the native Fetch API and WebSocket class — no dependencies required.

Configuration

const API_KEY = process.env.THERUNDOWN_API_KEY || "YOUR_API_KEY";
const BASE_URL = "https://therundown.io/api/v2";
const WS_URL = "wss://therundown.io/api/v2/ws/markets";

Helper Function

async function apiGet(path, params = {}) {
  const url = new URL(`${BASE_URL}${path}`);
  url.searchParams.set("key", API_KEY);
  for (const [key, value] of Object.entries(params)) {
    url.searchParams.set(key, value);
  }

  const response = await fetch(url.toString());

  if (response.status === 429) {
    throw new Error("Rate limited. Check Retry-After header.");
  }

  if (!response.ok) {
    throw new Error(`API error: ${response.status} ${response.statusText}`);
  }

  return response.json();
}

Getting Sports

const { sports } = await apiGet("/sports");

for (const sport of sports) {
  console.log(`${sport.sport_id}: ${sport.sport_name}`);
}

Getting Events with Odds

const today = new Date().toISOString().split("T")[0];

const data = await apiGet(`/sports/4/events/${today}`, {
  market_ids: "1,2,3",       // Moneyline, Spread, Total
  affiliate_ids: "19,23",    // DraftKings, FanDuel
  main_line: "true",
});

function formatPrice(price) {
  if (price === 0.0001) return "N/A";
  return price > 0 ? `+${Math.round(price)}` : String(Math.round(price));
}

for (const event of data.events) {
  const away = event.teams[0].name;
  const home = event.teams[1].name;
  console.log(`\n${away} @ ${home}`);

  for (const market of event.markets || []) {
    console.log(`  ${market.name}:`);
    for (const participant of market.participants) {
      for (const line of participant.lines) {
        const lineStr = line.value ? ` (${line.value})` : "";
        const prices = Object.entries(line.prices)
          .map(([id, p]) => `${formatPrice(p.price)} @${id}`)
          .join("  ");
        console.log(`    ${participant.name}${lineStr}: ${prices}`);
      }
    }
  }
}

Filtering by Affiliate

// Only FanDuel lines
const data = await apiGet(`/sports/4/events/${today}`, {
  market_ids: "1,2,3",
  affiliate_ids: "23",  // FanDuel only
  main_line: "true",
});

Getting Player Props

const props = await apiGet(`/sports/4/events/${today}`, {
  market_ids: "29,35,38,39",  // Points, Rebounds, 3PT, Assists
  affiliate_ids: "19",
});

for (const event of props.events) {
  console.log(`\n${event.teams[0].name} @ ${event.teams[1].name}`);
  for (const market of event.markets || []) {
    console.log(`  ${market.name}:`);
    for (const participant of market.participants) {
      for (const line of participant.lines) {
        const price = line.prices["19"]?.price ?? "N/A";
        console.log(`    ${participant.name}: ${line.value} (${price})`);
      }
    }
  }
}

Historical Odds

const eventId = "abc123";

// Full market history
const data = await apiGet(`/events/${eventId}/markets/history`, {
  affiliate_ids: "19",
});

for (const entry of data.history) {
  console.log(
    `${entry.updated_at}: line=${entry.line} price=${entry.price} (${entry.change_type})`
  );
}

// Opening lines
const openers = await apiGet(`/events/${eventId}/openers`, {
  market_ids: "1,2,3",
});

// Closing lines
const closing = await apiGet(`/events/${eventId}/closing`, {
  market_ids: "1,2,3",
});

WebSocket Streaming

function connectWebSocket(options = {}) {
  const { sportIds = "4", marketIds = "1,2,3", onUpdate } = options;

  const url = `${WS_URL}?key=${API_KEY}&sport_ids=${sportIds}&market_ids=${marketIds}`;
  const ws = new WebSocket(url);

  ws.onopen = () => {
    console.log("WebSocket connected");
  };

  ws.onmessage = (event) => {
    const msg = JSON.parse(event.data);

    // Skip heartbeats
    if (msg.meta?.type === "heartbeat") return;

    if (onUpdate) {
      onUpdate(msg.data);
    } else {
      const d = msg.data;
      console.log(`Update: event=${d.event_id} market=${d.market_id} price=${d.price}`);
    }
  };

  ws.onerror = (error) => {
    console.error("WebSocket error:", error);
  };

  ws.onclose = (event) => {
    console.log(`WebSocket closed: ${event.code}`);
  };

  return ws;
}

// Usage
const ws = connectWebSocket({
  sportIds: "4",
  marketIds: "1,2,3",
  onUpdate: (update) => {
    console.log(
      `Event ${update.event_id}: market=${update.market_id} ` +
      `aff=${update.affiliate_id} price=${update.price}`
    );
  },
});

WebSocket with Auto-Reconnect

function createReconnectingSocket(options = {}) {
  const {
    sportIds = "4",
    marketIds = "1,2,3",
    onUpdate,
    onConnect,
    maxDelay = 30000,
  } = options;

  let ws;
  let reconnectDelay = 1000;
  let closed = false;

  function connect() {
    if (closed) return;

    const url = `${WS_URL}?key=${API_KEY}&sport_ids=${sportIds}&market_ids=${marketIds}`;
    ws = new WebSocket(url);

    ws.onopen = () => {
      console.log("WebSocket connected");
      reconnectDelay = 1000;
      if (onConnect) onConnect();
    };

    ws.onmessage = (event) => {
      const msg = JSON.parse(event.data);
      if (msg.meta?.type === "heartbeat") return;
      if (onUpdate) onUpdate(msg.data);
    };

    ws.onclose = () => {
      if (closed) return;
      const jitter = Math.random() * 1000;
      const delay = Math.min(reconnectDelay + jitter, maxDelay);
      console.log(`Reconnecting in ${Math.round(delay)}ms...`);
      setTimeout(() => {
        reconnectDelay = Math.min(reconnectDelay * 2, maxDelay);
        connect();
      }, delay);
    };

    ws.onerror = () => {
      ws.close();
    };
  }

  connect();

  return {
    close() {
      closed = true;
      ws?.close();
    },
  };
}

// Usage
const connection = createReconnectingSocket({
  sportIds: "4",
  marketIds: "1,2,3",
  onUpdate: (update) => {
    console.log(`Update: event=${update.event_id} market=${update.market_id} price=${update.price}`);
  },
  onConnect: () => {
    console.log("Ready to receive updates");
  },
});

// Later: connection.close();

Error Handling with Retry

async function apiGetWithRetry(path, params = {}, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const url = new URL(`${BASE_URL}${path}`);
    url.searchParams.set("key", API_KEY);
    for (const [key, value] of Object.entries(params)) {
      url.searchParams.set(key, value);
    }

    const response = await fetch(url.toString());

    if (response.ok) {
      return response.json();
    }

    if (response.status === 429) {
      const retryAfter = Number(response.headers.get("Retry-After") || "0");
      const wait =
        retryAfter > 0
          ? retryAfter * 1000
          : Math.pow(2, attempt) * 1000 + Math.random() * 1000;
      console.log(`Rate limited. Retrying in ${Math.round(wait)}ms...`);
      await new Promise((resolve) => setTimeout(resolve, wait));
      continue;
    }

    throw new Error(`API error: ${response.status} ${response.statusText}`);
  }

  throw new Error("Max retries exceeded");
}

TypeScript Types

If you are using TypeScript, here are type definitions for the core response objects:

interface Sport {
  sport_id: number;
  sport_name: string;
}

interface Team {
  team_id: number;
  name: string;
}

interface Price {
  price: number;
  is_main_line: boolean;
  updated_at: string;
}

interface Line {
  value: string;
  prices: Record<string, Price>;
}

interface Participant {
  id: number;
  type: string;
  name: string;
  lines: Line[];
}

interface Market {
  market_id: number;
  name: string;
  period_id: number;
  participants: Participant[];
}

interface Event {
  event_id: string;
  sport_id: number;
  teams: Team[];
  markets: Market[];
}

interface EventsResponse {
  events: Event[];
}

interface WebSocketMeta {
  type: "market_price" | "heartbeat";
  version: string;
  timestamp: number;
}

interface MarketPriceUpdate {
  id: number;
  event_id: string;
  affiliate_id: number;
  market_participant_id: number;
  market_id: number;
  line: string;
  price: string;
  previous_price: string;
  price_delta: number;
  is_main_line: boolean;
  normalized_market_participant_id: number;
  normalized_market_participant_type: number;
  sport_id: number;
  updated_at: string;
}

interface WebSocketMessage {
  meta: WebSocketMeta;
  data: MarketPriceUpdate;
}

Next Steps

Getting Live Odds

Detailed guide on fetching odds

WebSocket Streaming

Real-time data streaming guide

Authentication

All authentication methods

Rate Limits

Rate limit details and best practices

​Configuration

​Helper Function

​Getting Sports

​Getting Events with Odds

​Filtering by Affiliate

​Getting Player Props

​Historical Odds

​WebSocket Streaming

​WebSocket with Auto-Reconnect

​Error Handling with Retry

​TypeScript Types

​Next Steps

Getting Live Odds

WebSocket Streaming

Authentication

Rate Limits

Configuration

Helper Function

Getting Sports

Getting Events with Odds

Filtering by Affiliate

Getting Player Props

Historical Odds

WebSocket Streaming

WebSocket with Auto-Reconnect

Error Handling with Retry

TypeScript Types

Next Steps