> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ekiden.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Leaderboards & Competitions

Leaderboards provide ranked trading sub-accounts together with trading performance metrics and XP statistics. Competition endpoints provide public competition information, leaderboards, and authenticated competition views.

## User Leaderboard

```http theme={null}
GET /api/v1/user/leaderboard
```

Query parameters:

| Parameter   | Required | Notes                                                          |
| ----------- | -------- | -------------------------------------------------------------- |
| `timeframe` | Yes      | Ranking window. Supported values: `today`, `7d`, `30d`, `all`. |
| `limit`     | No       | Page size.                                                     |
| `offset`    | No       | Pagination offset.                                             |

Each leaderboard row includes:

* `sub_account_address`
* `place`
* `ranked`
* `volume`
* `pnl`
* `roi`
* `account_value`
* `trading_xp`
* `referral_xp`
* `total_xp`

Pagination metadata is returned in the `meta` object.

## User Placement

```http theme={null}
GET /api/v1/user/leaderboard/placement
```

Query parameters:

| Parameter     | Required | Notes                                                                                                                    |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `timeframe`   | Yes      | Ranking window. Supported values: `today`, `7d`, `30d`, `all`.                                                           |
| `sub_account` | No       | Returns placement for the specified trading sub-account. If omitted, placement is returned for each trading sub-account. |

Each placement entry includes:

* `sub_account_address`
* `place`
* `ranked`
* `volume`
* `pnl`
* `roi`
* `account_value`
* `trading_xp`
* `referral_xp`
* `total_xp`

## Public Competitions

### List Competitions

```http theme={null}
GET /api/v1/competitions
```

Returns the list of public competitions.

Query parameters:

| Parameter | Required | Notes                                                            |
| --------- | -------- | ---------------------------------------------------------------- |
| `status`  | No       | Filters competitions by status. See OpenAPI for accepted values. |

Each competition includes:

* `id`
* `slug`
* `title`
* `description_md`
* `status`
* `start_time_ms`
* `end_time_ms`
* `prize_usdc`
* `metric`
* `symbol`

See the generated OpenAPI schema for the complete response structure.

### Competition Details

```http theme={null}
GET /api/v1/competitions/{competition_slug}
```

Returns the details for a single public competition.

Path parameters:

| Parameter          | Required | Notes             |
| ------------------ | -------- | ----------------- |
| `competition_slug` | Yes      | Competition slug. |

Returns metadata and configuration for a single public competition.

See the generated OpenAPI schema for the complete response structure.

### Competition Leaderboard

```http theme={null}
GET /api/v1/competitions/{competition_slug}/leaderboard
```

Path parameters:

| Parameter          | Required | Notes             |
| ------------------ | -------- | ----------------- |
| `competition_slug` | Yes      | Competition slug. |

Query parameters:

| Parameter     | Required | Notes                                           |
| ------------- | -------- | ----------------------------------------------- |
| `limit`       | No       | Page size.                                      |
| `offset`      | No       | Pagination offset.                              |
| `sub_account` | No       | Returns the specified trading sub-account only. |

The response includes:

* `competition`
* `data`
* `meta`

Each leaderboard entry includes:

* `sub_account_address`
* `rank`
* `score`
* `metric_value`
* `active_days`
* `eligible`
* `ineligible_reason`
* `projected_xp`

Pagination metadata is returned in the `meta` object.

## Authenticated Competition Endpoints

The following endpoints require authentication and operate on competition IDs rather than slugs.

```http theme={null}
GET /api/v1/user/competitions
GET /api/v1/user/competitions/{competition_id}/leaderboard
GET /api/v1/user/competitions/{competition_id}/placement
```

Competition leaderboard rows include:

* `sub_account_address`
* `rank`
* `score`
* `metric_value`
* `active_days`
* `eligible`
* `ineligible_reason`
* `projected_xp`

`projected_xp` is a live display-only projection based on the current eligible leaderboard scores. Final XP allocation is recorded in the rewards ledger.