Skip to main content

Practice Arena API Documentation

Overview​

Practice arenas allow users to play games for free, compete with others, and practice their skills on a weekly cycle basis. There are NO seat limits - unlimited players can join and play throughout the week. Winners are declared at the end of each week (Sunday night), and the arena automatically resets for a new week starting Monday.

Public Endpoints (No Auth Required)​

1. List All Practice Arenas​

GET /api/v1/practice-arenas

Query Parameters:

  • game (optional): Game ID to get arena for specific game

Headers (Optional):

  • Authorization: Bearer <token> - If provided, includes myScore field with user's current week score

Response:

[
  {
    "_id": "arena123",
    "name": "Thunder Dome",
    "game": "game123",
    "status": "ACTIVE",
    "currentWeekStartDate": "2025-01-27T00:00:00.000Z",
    "currentWeekEndDate": "2025-02-02T23:59:59.999Z",
    "isWeeklyCycle": true,
    "rules": "Best score wins!",
    "myScore": 10,
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-01-01T00:00:00.000Z"
  }
]

Notes:

  • myScore: User's score for the current week in this arena. Returns null if:
    • User is not authenticated (no Authorization header)
    • User has not submitted a score for the current week
  • The endpoint works without authentication, but myScore will always be null for unauthenticated requests

2. Get Arena by ID​

GET /api/v1/practice-arenas/:id

Headers (Optional):

  • Authorization: Bearer <token> - If provided, includes myScore field with user's current week score

Response:

{
  "_id": "arena123",
  "name": "Thunder Dome",
  "game": "game123",
  "status": "ACTIVE",
  "currentWeekStartDate": "2025-01-27T00:00:00.000Z",
  "currentWeekEndDate": "2025-02-02T23:59:59.999Z",
  "isWeeklyCycle": true,
  "rules": "Best score wins!",
  "myScore": 10
}

Notes:

  • myScore: User's score for the current week in this arena. Returns null if user is not authenticated or has no score for the current week

3. Get Arena Leaderboard​

GET /api/v1/practice-arenas/:id/leaderboard

Response:

{
  "game": "game123",
  "leaderboard": [
    {
      "_id": "lb123",
      "arena": "arena123",
      "user": {
        "_id": "user123",
        "username": "player1",
        "avatar": "https://..."
      },
      "score": 10,
      "type": "spend",
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-01T00:00:00.000Z"
    }
  ]
}

Authenticated Endpoints (Require Bearer Token)​

4. Join Practice Arena​

POST /api/v1/practice-arenas/:id/join

Headers:

Authorization: Bearer <token>

Response:

{
  "ok": true,
  "arena": {
    "_id": "arena123"
  }
}

Notes:

  • NO seat limits - unlimited players can join
  • Creates a participation entry for tracking played arenas
  • Arena runs continuously throughout the week

5. Submit Score​

POST /api/v1/practice-arenas/:id/score

Headers:

Authorization: Bearer <token>

Request Body:

{
  "score": 10
}

Response:

{
  "ok": true
}

Notes:

  • Score must be a positive number (greater than 0)
  • Updates user's score in weekly leaderboard (keeps best/lowest score)
  • Score submission does NOT immediately declare winner
  • Winner is determined at the end of the week by cron job

6. Get Played Arenas​

GET /api/v1/practice-arenas/played

Headers:

Authorization: Bearer <token>

Response:

[
  {
    "arenaId": "arena123",
    "joinedAt": "2025-01-01T00:00:00.000Z",
    "arena": {
      "_id": "arena123",
      "name": "Thunder Dome",
      "status": "ACTIVE",
      "game": {
        "_id": "game123",
        "name": "Flappy Bird",
        "thumbnail": "https://..."
      },
      "currentWeekStartDate": "2025-01-27T00:00:00.000Z",
      "currentWeekEndDate": "2025-02-02T23:59:59.999Z",
      "isWeeklyCycle": true
    }
  }
]

Notes:

  • Shows unique arenas (no duplicates even if joined multiple times)
  • Shows first join date for each arena

Admin Endpoints​

7. Create Practice Arena​

POST /api/admin/practice-arenas

Request Body:

{
  "game": "game123",
  "name": "Thunder Dome",
  "rules": "Custom rules here"
}

Required Fields:

  • game: Game ID

Optional Fields:

  • name: Funky arena name (e.g., "Thunder Dome", "Speed Demons")
  • rules: Custom rules text

Response:

{
  "_id": "arena123",
  "game": "game123",
  "name": "Thunder Dome",
  "status": "ACTIVE",
  "currentWeekStartDate": "2025-01-27T00:00:00.000Z",
  "currentWeekEndDate": "2025-02-02T23:59:59.999Z",
  "isWeeklyCycle": true,
  "rules": "Custom rules here"
}

Notes:

  • Weekly cycle dates are automatically initialized (Monday-Sunday)
  • No seat limits or entry fees for practice arenas

8. List All Arenas (Admin)​

GET /api/admin/practice-arenas

Response:

[
  {
    "_id": "arena123",
    "name": "Thunder Dome",
    "game": {
      "_id": "game123",
      "name": "Flappy Bird",
      "thumbnail": "https://..."
    },
    "status": "ACTIVE",
    "currentWeekStartDate": "2025-01-27T00:00:00.000Z",
    "currentWeekEndDate": "2025-02-02T23:59:59.999Z",
    "isWeeklyCycle": true
  }
]

Arena Status Flow​

  1. ACTIVE: Arena is open and running weekly cycles
  2. INACTIVE: Arena is disabled (no longer accepting players)

Note: Unlike tournaments, practice arenas don't have "OVER" status. They run continuously in weekly cycles.

Important Notes​

Weekly Cycle System​

  • Week runs Monday 00:00 → Sunday 23:59:59
  • NO seat limits - unlimited players can join
  • NO entry fees - completely free to play
  • Winners declared automatically at end of week (Sunday night)
  • Arena resets for new week on Monday morning

Scoring​

  • Lower score is better (golf-style scoring)
  • Each user can submit multiple scores throughout the week
  • Only the best (lowest) score is kept
  • Zero scores are excluded (considered invalid)
  • Winner has the lowest non-zero score

Joining​

  • Users can join unlimited times throughout the week
  • No seat restrictions or player limits
  • Free to play (no points required)

Weekly Winner Declaration​

  • Automated cron job runs every hour checking for ended weeks
  • At week end (Sunday 23:59:59), system finds winner (lowest score > 0)
  • Winner marked in historical weekly leaderboard
  • Reward distribution created (requires admin approval)
  • Arena automatically resets for next week (new Monday-Sunday cycle)

Reward Distribution​

  • Winners may receive rewards (configured by admin per arena)
  • Rewards require admin approval before distribution
  • Reward amounts are country-specific
  • Approved rewards automatically credit user wallets

Leaderboard​

  • Each week has its own leaderboard
  • Historical leaderboards preserved for past weeks
  • Current week leaderboard shows real-time rankings
  • Only non-zero scores appear on leaderboard