Fantasy

The Fantasy API turns a RaceHooks race weekend into fantasy points. It gives you an estimated points breakdown per driver for any completed Grand Prix or Sprint, a running score while a session is on track, and a pit-lane leaderboard — all keyed to the same canonical driver identity (TLA and team) as every other RaceHooks surface. Pair it with the drop-in fantasy scorer and you have a live leaderboard from race-event webhooks.

# Grand Prix scoring (default)
curl "https://api.racehooks.io/v1/fantasy/races/2026-italy-r16/scores" \
  -H "Authorization: Bearer ${TOKEN}"

# Sprint scoring — compressed points table
curl "https://api.racehooks.io/v1/fantasy/races/2026-italy-r16/scores?session=sprint" \
  -H "Authorization: Bearer ${TOKEN}"

# Response
{
  "data": {
    "raceId": "2026-italy-r16",
    "sessionType": "grand_prix",
    "scores": [
      {
        "driver": "verstappen-max",
        "tla": "VER",
        "team": "Red Bull Racing",
        "breakdown": {
          "racePosPoints": 25,
          "qualiPosPoints": 10,
          "q3Bonus": 3,
          "positionsGained": 0,
          "positionsGainedPoints": 0,
          "fastestLapPoints": 5,
          "beatTeammateRace": 3,
          "beatTeammateQuali": 2,
          "dnfPenalty": 0,
          "total": 48
        }
      }
    ]
  }
}

# Running score while a session is on track
curl "https://api.racehooks.io/v1/fantasy/session/2026-italy_r/scores" \
  -H "Authorization: Bearer ${TOKEN}"

# Response — provisional; grid-derived + fastest-lap components stay null until the flag
{
  "data": {
    "sessionId": "2026-italy_r",
    "live": true,
    "provisional": true,
    "sessionType": "grand_prix",
    "currentLap": 34,
    "totalLaps": 53,
    "scores": [
      {
        "driver": "LEC", "tla": "LEC", "team": "Ferrari",
        "breakdown": {
          "racePosPoints": 25, "beatTeammateRace": 3, "dnfPenalty": 0,
          "qualiPosPoints": null, "q3Bonus": null,
          "positionsGained": null, "positionsGainedPoints": 0,
          "fastestLapPoints": null, "beatTeammateQuali": null,
          "total": 28
        }
      }
    ]
  }
}

# When nothing is live for this id:
# { "data": { ..., "live": false, "scores": [] },
#   "message": "No live session is currently active for this id. ..." }

# Subscribe your endpoint to the feed
curl -X POST "https://api.racehooks.io/v1/webhooks" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "webhookUrl": "https://your-app.com/hook", "feedId": "fantasy.scores" }'

# ...or read it on the SSE stream
curl -N "https://api.racehooks.io/v1/stream?feeds=fantasy.scores" \
  -H "Authorization: Bearer ${TOKEN}"

# Delivered payload — fires when a score moves, not every tick
{
  "feed": "fantasy.scores",
  "sessionId": "2026-italy_r",
  "utc": "2026-09-06T13:41:02.118Z",
  "live": true,
  "provisional": true,
  "sessionType": "grand_prix",
  "currentLap": 34,
  "totalLaps": 53,
  "scores": [
    {
      "driver": {
        "driverId": "leclerc-charles", "constructorId": "ferrari", "number": "16",
        "tla": "LEC", "name": "Charles Leclerc", "team": "Scuderia Ferrari"
      },
      "breakdown": {
        "racePosPoints": 25, "beatTeammateRace": 3, "dnfPenalty": 0,
        "qualiPosPoints": null, "q3Bonus": null,
        "positionsGained": null, "positionsGainedPoints": 0,
        "fastestLapPoints": null, "beatTeammateQuali": null,
        "total": 28
      }
    }
  ]
}

curl "https://api.racehooks.io/v1/fantasy/session/2026-italy_r/pit-times" \
  -H "Authorization: Bearer ${TOKEN}"

# Response — ranked fastest → slowest, plus the fastest stop of the session
{
  "data": {
    "sessionId": "2026-italy_r",
    "source": "historical",
    "fastestStop": { "driver": "norris-lando", "tla": "NOR", "team": "McLaren", "pitStopTimeSec": 2.104, "lap": 21 },
    "stops": [
      { "driver": "norris-lando", "tla": "NOR", "team": "McLaren", "pitStopTimeSec": 2.104, "lap": 21 },
      { "driver": "verstappen-max", "tla": "VER", "team": "Red Bull Racing", "pitStopTimeSec": 2.418, "lap": 19 }
    ]
  }
}

npm install racehooks racehooks-f1-fantasy-scorer

import { RaceHooks } from "racehooks";
import { FantasyScorer, OfficialF1ScoringRules } from "racehooks-f1-fantasy-scorer";

const rh = new RaceHooks({
  clientId:     process.env.RACEHOOKS_CLIENT_ID!,
  clientSecret: process.env.RACEHOOKS_CLIENT_SECRET!,
});

// 1. Subscribe to the race-events feed, filtered to your league's roster.
const { webhook, webhookSecret } = await rh.webhooks.create({
  feedId:     "events.race",
  webhookUrl: "https://your-app.com/fantasy-hook",
  filters:    { drivers: ["VER", "NOR", "LEC", "HAM", "RUS"] },
});
console.log("Save this signing secret:", webhookSecret);

// 2. Spin up a scorer for the same roster.
const scorer = new FantasyScorer({
  rules:  OfficialF1ScoringRules,
  roster: ["VER", "NOR", "LEC", "HAM", "RUS"],
});

// 3. Push a fresh leaderboard whenever a point changes.
scorer.on("scoreUpdate", (scores, event) => {
  console.log(`${event.driver} ${event.points > 0 ? "+" : ""}${event.points} (${event.reason})`);
  renderLeaderboard(scores); // { VER: 35, NOR: 39, LEC: 32, ... }
});

import express from "express";
import { verifySignature } from "racehooks";

const app = express();
app.use("/fantasy-hook", express.raw({ type: "application/json" }));

app.post("/fantasy-hook", (req, res) => {
  const sig = req.headers["x-racehooks-signature"] as string;
  if (!verifySignature(req.body, sig, process.env.WEBHOOK_SECRET!)) {
    return res.status(401).send("Bad signature");
  }

  // ingest() routes any RaceHooks payload to the right handler and
  // auto-finalises the classification when the session completes.
  scorer.ingest(JSON.parse(req.body.toString()));
  res.sendStatus(200);
});