# Leaderboard & Stats

Base URL: `https://service.leverup.xyz`

## Leaderboard

```http
GET /v1/leaderboard
```

| Parameter | Default | Notes |
| :--- | :--- | :--- |
| `timeframe` | all time | `ONE_DAY`, `SEVEN_DAY`, `THIRTY_DAY`, `ALL` |
| `sort_field` | `PNL` | `PNL`, `WIN_RATE`, `BIGGEST_WIN`, `TOTAL_VOL_USD` |
| `sort_direction` | `DESC` | `ASC` or `DESC` |
| `page` | `0` | |
| `size` | `50` | |
| `search` | — | Filter by address |
| `block_chain` | `MONAD` | |

### Response

```json
{
  "content": [
    {
      "rank": 1,
      "userAddress": "0x…",
      "pnl": 125430.55,
      "totalVolUsd": 8900000.00,
      "winCount": 210,
      "loseCount": 96,
      "biggestWin": 24500.00,
      "winRate": 0.686,
      "totalCount": 1523,
      "highLeverageVolUsd": 4500000.00,
      "lowLeverageVolUsd": 4400000.00
    }
  ],
  "pageNumber": 0,
  "pageSize": 50,
  "totalPages": 31,
  "totalElements": 1523
}
```

| Field | Notes |
| :--- | :--- |
| `pnl`, `totalVolUsd`, `biggestWin` | USD, decimal |
| `winRate` | Fraction, not percentage |
| `totalCount` | Total ranked traders, not this trader's trade count |
| `highLeverageVolUsd` / `lowLeverageVolUsd` | Volume split by leverage band |

## Team leaderboard

Same shape, scoped to one team.

```http
GET /v1/leaderboard/team/{team_code}
```

Accepts the same parameters as `/v1/leaderboard`.

## My rank

One trader's standing without paging through the board.

```http
GET /v1/leaderboard/my-rank?user_address=0x…
```

| Parameter | Required | Notes |
| :--- | :--- | :--- |
| `user_address` | yes | |
| `timeframe` | no | |
| `sort_field` | no | `PNL` by default — rank depends on it |
| `sort_direction` | no | |
| `block_chain` | no | |

Returns a single `LeaderboardDataResponse`. A trader outside the ranked set gets their stats back
with `rank: 0`; a trader with no history gets an all-zero record.

```ts
const res = await fetch(`${API}/v1/leaderboard/my-rank?user_address=${address}`)
const me = await res.json()

console.log(me.rank === 0 ? 'unranked' : `#${me.rank}`, 'pnl', me.pnl)
```

## Trading stats

Aggregate stats for an arbitrary time window — useful for campaign scoring.

```http
GET /v1/leaderboard/{user_address}/trading-stats?start_time=1785225600&end_time=1785312000
```

| Parameter | Required | Notes |
| :--- | :--- | :--- |
| `start_time` | yes | Unix seconds |
| `end_time` | yes | Unix seconds |
| `block_chain` | no | |

Returns a `LeaderboardDataResponse` with `rank: 0` — it is a stats query, not a ranking. A trader
with no activity in the window returns an all-zero record rather than a 404.

## sLVMON

Staked LVMON.

```http
GET /v1/slvmon/apy?days=7
```

| Parameter | Default |
| :--- | :--- |
| `days` | `7` |
| `blockChain` | `MONAD` |

Returns a bare decimal, e.g. `12.34`.

```http
GET /v1/slvmon/{user_address}/portfolio
```

```json
{
  "shares": "1000000000000000000",
  "principal": "1000000000000000000",
  "cumulativeRealizedPnl": "45000000000000000"
}
```

All values are 18-decimal strings.