ledger-api

Ledger API

• Base Path: /api/v1/ledger
• Auth: Bearer required

Model

• user: string (User ID)
• tournament: string | object
  • On /me, populated with the full Tournament document (all standard fields).
  • Nested population: tournament.product and tournament.game are fully populated to their respective models.
  • Not populated: tournament.leaderboard stays as an ID (no document expansion).
• type: SPEND | REFUND | TOPUP | SUBSCRIPTION
• amount: number (points, positive)
• note: string (optional)
• country: string (ISO2 country code, e.g., 'IN', 'AE', 'US') — tracks which country wallet this transaction belongs to
• createdAt / updatedAt: ISO strings

Get My Ledger

• Method: GET
• Path: /api/v1/ledger/me
• Query:
  • tournament: string (optional) — filter entries for a specific tournament
• Response 200: array of ledger entries for the authenticated user (automatically filtered by user's current country from their address), newest first.
• Note: Ledger entries are automatically filtered by the user's current country from address.country. Only transactions for the current country are returned.
• Population details:
  • tournament: full Tournament document
  • tournament.product: full Product document
  • tournament.game: full Game document
  • tournament.leaderboard: not populated (remains an ID)
• Errors:
  • 401: \{ "error": "UNAUTHORIZED" \}
  • 500: \{ "error": "Failed to fetch ledger" \}

Example

Request: GET /api/v1/ledger/me

Response: [

  {
    "_id": "66f...a1",
    "user": "0192059b-...",
    "tournament": {
      "_id": "66f...t9",
      "status": "OPEN",
      "product": {
        "_id": "66e...p3",
        "name": "Wireless Controller",
        "description": "Pro-grade wireless controller",
        "price": 5999,
        "category": "ACCESSORY",
        "images": ["https://.../ctrl-1.jpg"],
        "createdAt": "2025-09-05T10:00:00.000Z",
        "updatedAt": "2025-09-05T10:00:00.000Z"
      },
      "game": {
        "_id": "66d...g1",
        "name": "Space Dash",
        "description": "Dodge and sprint in space!",
        "tabcode": "spacedash",
        "thumbnail": "https://.../games/spacedash.png",
        "status": "PUBLISHED"
      },
      "leaderboard": "66f...lb1", // not populated
      "totalSeats": 100,
      "numberOfPlayers": 12,
      "startAt": "2025-09-06T10:00:00.000Z",
      "endedAt": null
    },
    "type": "SPEND",
    "amount": 10,
    "createdAt": "2025-09-06T10:00:00.000Z"
  },

  {
    "_id": "66f...b2",
    "user": "0192059b-...",
    "tournament": { "_id": "66f...t9", "product": { "_id": "66e...p3", "name": "Wireless Controller" }, "game": { "_id": "66d...g1", "name": "Space Dash" }, "leaderboard": "66f...lb1" },
    "type": "REFUND",
    "amount": 10,
    "createdAt": "2025-09-06T11:00:00.000Z"
  }

]