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

# Contests

> API endpoints for building trading contests and leaderboards on Gains data.

### Base URL

```
https://backend-global.gains.trade/api
```

### Endpoints

#### 1. List All Contests

```
GET /contests
```

**Response:**

```json theme={null}
[
  {
    "id": "trickortrade",
    "start": 1729608000000,
    "end": 1732026000000,
    "chains": ["arbitrum"],
    "isActive": true
  }
]
```

***

#### 2. Get Contest Details

```
GET /contests/:id
```

**Response:**

```json theme={null}
{
  "id": "trickortrade",
  "start": 1729608000000,
  "end": 1732026000000,
  "chains": ["arbitrum"],
  "isActive": true,
  "stats": {
    "totalTraders": 1247,
    "totalTrades": 8931,
    "totalPnl": 125430.5,
    "totalVolumePoints": 9847231.25,
    "top300VolumePoints": 8234192.1
  },
  "rewards": {
    "pnlAbsolute": {
      "1": 40000,
      "2": 20000,
      "3": 15000
      // ... ranks 1-50
    },
    "volume": {
      "proportional": true,
      "pool": 200000,
      "topN": 300
    }
  }
}
```

***

#### 3. Get Leaderboard

```
GET /contests/:id/leaderboard
```

**Query Parameters:**

* `sortBy` (optional): `"pnl"` or `"volume"` (default: `"pnl"`)
* `limit` (optional): Number of results to return (default: all)
* `offset` (optional): Pagination offset (default: 0)

**Example Request:**

```
GET /contests/trickortrade/leaderboard?sortBy=volume&limit=50&offset=0
```

**Response:**

```json theme={null}
{
  "contestId": "trickortrade",
  "sortBy": "volume",
  "pagination": {
    "total": 1247,
    "offset": 0,
    "limit": 50,
    "count": 50,
    "hasMore": true
  },
  "leaderboard": [
    {
      "traderAddress": "0x1234...5678",
      "pnlUsd": 12450.75,
      "volumeUsd": 2450000.0,
      "volumePoints": 984532.5,
      "tradeCount": 127,
      "lastUpdated": 1729123456789,
      "rank": 1
    }
    // ... more traders
  ]
}
```

***

#### 4. Get Trader Stats

```
GET /contests/:id/leaderboard/:trader
```

**Example Request:**

```
GET /contests/trickortrade/leaderboard/0x1234567890abcdef
```

**Response:**

```json theme={null}
{
  "contestId": "trickortrade",
  "trader": "0x1234567890abcdef",
  "stats": {
    "pnlUsd": 12450.75,
    "volumeUsd": 2450000.0,
    "volumePoints": 984532.5,
    "tradeCount": 127,
    "lastUpdated": 1729123456789
  },
  "rankings": {
    "pnl": 5,
    "volume": 1
  },
  "rewards": {
    "pnl": 8500,
    "volume": 23894.5,
    "total": 32394.5
  }
}
```

***

### Data Refresh Rates

60-90 seconds

### Notes

* All timestamps are in Unix milliseconds (UTC)
* Trader addresses are case-insensitive
* Volume rewards are proportionally distributed among top 300 traders
* PnL rewards are fixed amounts for top 50 traders
* `volumePoints` represents time-weighted volume (used for rankings)
* `volumeUsd` represents raw dollar volume (all opens/increases/decreases/closes)