Leaderboard

Returns the epoch cumulative points leaderboard. Data is read from a cached table refreshed periodically by the backend.

GET /points/leaderboard

No authentication required.

Query Parameters

Parameter	Type	Required	Default	Description
epoch	integer	No	1	Epoch number. Defaults to epoch 1 — pass explicitly to query other epochs
type_	string	No	total	Ranking type (see below)
limit	integer	No	100	Number of entries to return

The parameter name is type_ (with trailing underscore) because type is a reserved keyword in Rust.

Ranking Types

Value	Ranked By
total	Total points (default)
trading	Trading Points (TP)
pnl	PnL Points (PP)
holding	Holding Points (HP)
referral	Referral Points (RP)
staking	Staking Points (SP)

Response

{
  "epoch_number": 3,
  "rank_type": "total",
  "entries": [
    {
      "rank": 1,
      "user_address": "0xAbCd...1234",
      "username": "TradingKing",
      "points": "125680.50",
      "tier": "T3"
    },
    {
      "rank": 2,
      "user_address": "0xEfGh...5678",
      "username": null,
      "points": "98450.20",
      "tier": "T2"
    }
  ],
  "total": 1842,
  "updated_at": "2026-04-15T12:00:00Z"
}

Response Fields

Field	Type	Description
epoch_number	int	Epoch the leaderboard covers
rank_type	string	Ranking type used
entries	array	Ranked entries
total	int	Total number of ranked users (not capped by limit)
updated_at	string	Last cache refresh time (ISO 8601)

entries[]

Field	Type	Description
rank	int	Rank position
user_address	string	User's wallet address
username	string | null	Display name; null if not set
points	Decimal	Points total for the ranked type
tier	string	User's tier (T1 / T2 / T3)

Code Examples

Python

import requests

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

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

print(f"Top {len(data['entries'])} of {data['total']} users (Epoch {data['epoch_number']})")
for e in data["entries"]:
    name = e["username"] or e["user_address"][:10] + "..."
    print(f"  #{e['rank']} {name}: {e['points']} pts [{e['tier']}]")