Reading the race

Everything the track shows comes from public reads and one live stream. Quantities are whole tokens, positions run from 0 to 1, speeds are signed SOL per minute and times are milliseconds.

Reads

/api/derby/track: the current heat, earlier heats still racing, the next gate
/api/derby/results?before=&limit=: posted heats, newest first, paged by heat
/api/derby/heats/[heat]: one heat with its winner and order
/api/derby/heats/[heat]/replay: every curve trade of a heat in chain order, with the reserve after it
/api/derby/records?window=day|week|all: the fastest finishes
/api/derby/launches/[mint]: one launch's lane, heat and race
/api/derby/traders/[address]: the coins a wallet backed and where they finished
/api/derby/entry: the heat a create would join now
/api/derby/terms: the race and launch terms

A heat is addressed by the ISO time of its start, for example 2026-10-26T07:00:00.000Z. Every failure answers { error: { code, message } }.

The live stream

/api/launch/stream sends server-sent events. Open it with ?after= the eventId of the read you started from, and the browser reconnects from the last event on its own. Derby sends three race events beside the engine's own:

race: a curve trade landed: the lane after it and the replay point
finish: a curve reached 85 SOL: place and finish time
heat: a heat opened or its results changed

A race event

{
  "kind": "race",
  "heatId": "2026-10-26T07:00:00.000Z",
  "at": 1792999572000,
  "lane": { "mint": "…", "position": 0.0809, "speed": 6.88, "raised": 6.8775, "place": 3, "finish": null, "launch": { "name": "…", "symbol": "…" } },
  "point": { "side": "buy", "netQuote": 4.9125, "raised": 6.8775, "raisedAfterAtoms": "6877500000", "position": 0.0809 }
}

Following the track from a page

const track = await fetch("/api/derby/track").then((r) => r.json());
// The current heat, earlier heats still racing, every lane's position and speed.
console.log(track.currentHeat.label, track.currentHeat.lanes.length);

// Open the stream after the event the read included.
const stream = new EventSource(`/api/launch/stream?after=${track.eventId}`);
stream.onmessage = ({ data }) => {
  const event = JSON.parse(data);
  if (event.kind === "race") console.log(event.lane.launch.symbol, event.lane.position, event.lane.speed);
  if (event.kind === "finish") console.log(event.lane.launch.symbol, "finished", event.finish.place, event.finish.elapsedMs);
  if (event.kind === "heat" || event.kind === "reset") { /* read the track again */ }
};