Leaderboard

Public points-ranked competition board. Live while a round is ACTIVE; otherwise the last round’s frozen snapshot (when one exists). For real-time updates, subscribe to the WebSocket leaderboard channel. See WebSocket.

Endpoints

Method	Path	Description
`GET`	`/api/leaderboard`	Competition leaderboard
`GET`	`/api/leaderboard/card`	Leaderboard share card (JPEG)

Competition leaderboard

GET /api/leaderboard

Public, unauthenticated. Returns ranked entries (points, plus volume / pnl breakdown), round metadata, volume-multiplier tiers, and optional headline property.

Cached briefly (Cache-Control: public, max-age=0, s-maxage=5).

Request


import axios from 'axios';
 
const response = await axios.get('https://api.loafmarkets.com/api/leaderboard');
console.log(response.data);

Response

Type: LeaderboardResponse


interface LeaderboardResponse {
  roundNumber: number;
  roundName: string;
  roundRules: string;
  roundStatus: CompetitionRoundStatus;
  bottomCullPercent: number;
  volumeMultiplierTiers: VolumeMultiplierTier[];
  entries: LeaderboardEntry[];
  newAssetProperty: TradePropertyItem | null;
}
 
interface LeaderboardEntry {
  rank: number;
  handle: string | null;
  walletAddress: string;
  points: number;
  volume: number; // whole USDC
  pnl: number; // whole USDC
}
 
interface VolumeMultiplierTier {
  minVolume: number;
  multiplier: number;
}

Example response:


{
  "roundNumber": 1,
  "roundName": "League of Loaf — Round 1",
  "roundRules": "Ranked by competition score…",
  "roundStatus": "ACTIVE",
  "bottomCullPercent": 30,
  "volumeMultiplierTiers": [{ "minVolume": 0, "multiplier": 1 }],
  "entries": [
    {
      "rank": 1,
      "handle": "trader",
      "walletAddress": "0xabc…",
      "points": 12840.5,
      "volume": 52000,
      "pnl": 1800
    }
  ],
  "newAssetProperty": null
}

Errors

Status	Code	Description
`404`	`not_found`	No live round and no frozen board available.
`500`	`internal_error`	Unexpected server error.

Don’t poll this in a loop. Repeated automated requests get blocked by our bot protection, and non-browser clients can’t recover. For live updates, use the WebSocket instead → leaderboard.

Leaderboard card

GET /api/leaderboard/card

Authenticated. Returns a JPEG share image for your standing on the current board.

Response headers include Content-Type: image/jpeg and Cache-Control: private, no-store.

Request


curl -X GET 'https://api.loafmarkets.com/api/leaderboard/card' \
  -H "Authorization: Bearer $LOAF_API_KEY" \
  --output leaderboard-card.jpg

Errors

Status	Code	Description
`401`	`unauthorized`	Missing or invalid authentication.
`404`	`not_found`	No board / not on the board (depending on server state).
`409`	—	Card cannot be generated for the current round state.
`500`	`internal_error`	Unexpected server error.