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

# Get Leaderboard Placement

`GET /api/v1/user/leaderboard/placement`

## Request

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

Placement(s) for the authenticated user. When sub_account is omitted, returns one entry per user trading subaccount; otherwise exactly one entry. When the user has no trading subaccounts, data is an empty array. If the account is not ranked, ranked is false and place is "0".

## Query parameters

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

## Response `200`

Placements (ranked false when not on board)

- LeaderboardPlacementResponse: Response for the current user's placement(s) on the leaderboard.
  - `data` LeaderboardData[], required: One row per subaccount (or single row when sub_account query is set).
    - `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.

## Other responses

- `400`: Bad Request (invalid sub_account or address)
- `401`: Unauthorized

## 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`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ekidenfi/apis/ekiden-gateway/changes/api/v1/user/leaderboard/placement/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)