Daily Leaderboard

Returns each user's points increment since UTC 00:00 today. The cache is refreshed every 5 minutes by a background worker.

GET /points/leaderboard/daily

No authentication required.

Query Parameters

Parameter	Type	Required	Default	Description
epoch	integer	No	Current active epoch	Epoch number
limit	integer	No	100	Number of entries, max 500
offset	integer	No	0	Pagination offset

Response

{
  "date": "2026-04-16",
  "epoch_number": 3,
  "refreshed_at": "2026-04-16T08:35:00Z",
  "total": 2840,
  "entries": [
    {
      "rank": 1,
      "user_address": "0xAbCd...1234",
      "points_today": "4230.50",
      "tier": "T3"
    },
    {
      "rank": 2,
      "user_address": "0xEfGh...5678",
      "points_today": "3810.20",
      "tier": "T2"
    }
  ]
}

Response Fields

Field	Type	Description
date	string	UTC date (YYYY-MM-DD)
epoch_number	int	Epoch the data belongs to
refreshed_at	string	Last cache refresh time (minute-level precision)
total	int	Total users with points today (not capped by limit)
entries	array	Ranked entries

entries[]

Field	Type	Description
rank	int	Rank position for today
user_address	string	User's wallet address
points_today	Decimal	Points earned since UTC 00:00 today
tier	string | null	User's current tier; null if not set

Refresh Mechanism

Layer	Interval	Notes
Redis cache	330 seconds TTL	Written on first request; invalidated on refresh
DB cache table (daily_points_leaderboard)	Every 5 minutes	Background worker UPSERT
Daily reset	UTC 00:00	Data rebuilt from zero on first refresh each day

• This leaderboard shows today's increment only, not epoch cumulative totals. See Leaderboard for epoch totals.
• If the background worker has not completed its first run after service start (≈10 seconds), the endpoint may return an empty list.
• Use offset + limit for pagination, e.g., page 2: ?limit=100&offset=100.

Code Examples

Python

import requests

BASE_URL = "https://api.primit.io/api/v1"

resp = requests.get(
    f"{BASE_URL}/points/leaderboard/daily",
    params={"limit": 10},
)
data = resp.json()

print(f"Daily leaderboard {data['date']} (refreshed {data['refreshed_at']})")
for e in data["entries"]:
    print(f"  #{e['rank']} {e['user_address'][:10]}...: {e['points_today']} pts today")