---
title: "Get Leaderboard"
method: GET
path: "/api/v1/user/leaderboard"
tags: ["Leaderboard"]
---

# Get Leaderboard

`GET /api/v1/user/leaderboard`

## Request

- Base URL: `https://api.ekiden.fi`
- URL: `https://api.ekiden.fi/api/v1/user/leaderboard`
- Auth: none declared
- TypeScript: <https://skmtc.dev/ekidenfi/apis/ekiden-gateway/docs/api/v1/user/leaderboard/get.ts> (a function with typed inputs; its response is checked against the schema)

Paginated subaccount leaderboard ranked by PnL. Realized + unrealized (mark-to-market). Timeframe required: today, 7d, 30d, all. Default limit 10, max 100.

## Query parameters

- `offset` integer, nullable
- `limit` integer, nullable
- `timeframe` 'today' | '7d' | '30d' | 'all', required: Leaderboard ranking window: today, last 7 days, last 30 days, or all time.

## Response `200`

Leaderboard

- LeaderboardResponse: Paginated leaderboard list response.
  - `data` LeaderboardData[], required: Leaderboard rows.
    - `account_value` string, required: Equity in quote units (e.g. USDC).
    - `other_xp` integer, required: XP that is neither — quests today, plus admin adjustments. Reported separately so it cannot inflate `trading_xp`, which is what it used to do.
    - `place` string, required: Rank position (1-based), or "0" when not ranked.
    - `pnl` string, required: PnL for the selected timeframe. Realized + unrealized (mark-to-market).
    - `ranked` boolean, required: Whether this entry is on the board (false when not ranked).
    - `referral_xp` integer, required: XP earned from referral bonuses.
    - `roi` string, required: Return on investment as a decimal string (e.g. "0.05" for 5%).
    - `sub_account_address` string, required: Subaccount address.
    - `total_xp` integer, required: Total XP balance. Equals `trading_xp + referral_xp + other_xp`.
    - `trading_xp` integer, required: XP earned from trading activity: taker/maker fees and position holding.
    - `volume` string, required: Cumulative volume in quote units.
  - `meta` LeaderboardMeta, required: Pagination metadata for a leaderboard list response.
    - `limit` integer, required: Applied limit.
    - `offset` integer, required: Applied offset.
    - `total` integer, required: Total number of entries in the window.

## Changes

- **2026-09-10** `fad9eecaba2e`: 1 info
  - added the required property `data/items/other_xp` to the response with the `200` status
- **2026-05-28** `75ffe546b73a`: 2 breaking, 16 info
  - the `query` request parameter `timeframe` was restricted to a list of enum values
  - removed the required property `data/items/wallet` from the response with the `200` status
  - api tag `Leaderboard` added
  - api tag `User` removed
  - …14 more
- **2026-01-29** `16fe50636aa5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ekidenfi/apis/ekiden-gateway/changes/api/v1/user/leaderboard/get.md)

---

[API](https://skmtc.dev/ekidenfi/apis/ekiden-gateway.md) - [All operations](https://skmtc.dev/ekidenfi/apis/ekiden-gateway/llms.txt) - [OpenAPI document](https://skmtc.dev/ekidenfi/apis/ekiden-gateway/revisions/fad9eecaba2e?raw)