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 of it is 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.

# Find the race id first: it is events[].raceId from GET /v1/events (slugs are not guessable)
curl "https://api.racehooks.io/v1/events?season=2026" \
  -H "Authorization: Bearer ${TOKEN}"      # -> "raceId": "2026-monza-r13"

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

# Sprint scoring: compressed points table (sprint weekends only, e.g. 2026-miami-r4)
curl "https://api.racehooks.io/v1/fantasy/races/2026-miami-r4/scores?session=sprint" \
  -H "Authorization: Bearer ${TOKEN}"

# Response (abridged to one driver; values illustrative, field set is the live schema)
{
  "data": {
    "raceId": "2026-monza-r13",
    "sessionType": "grand_prix",
    "scores": [
      {
        "driver": "leclerc-charles",
        "tla": "LEC",
        "team": "Ferrari",
        "breakdown": {
          "racePosPoints": 25,
          "qualiPosPoints": 10,
          "q3Bonus": null,
          "positionsGained": 0,
          "positionsGainedPoints": 0,
          "positionsLostPoints": 0,
          "fastestLapPoints": 10,
          "overtakes": 3,
          "overtakePoints": 3,
          "driverOfTheDayPoints": 0,
          "beatTeammateRace": 0,
          "beatTeammateQuali": 0,
          "dnfPenalty": 0,
          "total": 51
        }
      }
    ],
    "constructors": [
      { "team": "Ferrari", "qualifyingBonus": 0, "pitPoints": 4, "points": 61 }
    ],
    "pitSource": "dhl"
  }
}

# An id that is not a race (404), and a sprint asked of a round with none (404)
{ "error": "Unknown race id 2026-japan_r. Race ids come from GET /v1/events (events[].raceId); they are not guessable slugs.", "code": "RACE_NOT_FOUND", "statusCode": 404 }
{ "error": "Race 2026-monza-r13 has no sprint. Only sprint weekends can be scored with ?session=sprint.", "code": "SPRINT_NOT_AT_ROUND", "statusCode": 404 }

# A season with no scoring ruleset is refused (400), not scored with another season's rules
curl "https://api.racehooks.io/v1/fantasy/races/2019-monza-r14/scores" -H "Authorization: Bearer ${TOKEN}"
{ "error": "No fantasy scores for season 2019. Supported: 2026.", "code": "SEASON_NOT_SUPPORTED", "statusCode": 400 }

# 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": 0, "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": 0, "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 github: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);
});