Player Management

Use Case

Use these endpoints to look up and monitor players registered under your Brands. Players are created by the platform when they first authenticate through a game provider — you do not create players directly via this API. The player management endpoints let you:

• Browse all players across your team or filter by Brand or username.
• Retrieve a specific player's profile and current wallet balance.
• Review a player's complete transaction history (debits, credits, rollbacks).

---

Complete Flow

Step 1 — List Players

GET /api/player/list

Returns a paginated list of players. You can filter by Brand or search by username.

Query parameters:

Parameter	Type	Default	Constraints	Description
page	integer	1	≥ 1	Page number
size	integer	20	1–100	Items per page
brand_id	integer	—	Optional	Filter to a specific Brand
username	string	—	Optional	Case-insensitive partial match on username

Example request — all players in brand 42:

GET /api/player/list?page=1&size=20&brand_id=42

Example request — search by username:

GET /api/player/list?page=1&size=50&username=john

Response:

{
  "total": 1250,
  "page": 1,
  "page_size": 20,
  "items": [
    {
      "id": 8801,
      "team_id": 7,
      "brand_id": 42,
      "username": "johndoe",
      "nickname": "John",
      "currency": "KRW",
      "status": 1,
      "created_at": "2026-03-15T12:00:00Z",
      "updated_at": "2026-03-15T12:00:00Z"
    },
    {
      "id": 8802,
      "team_id": 7,
      "brand_id": 42,
      "username": "johnsmith",
      "nickname": null,
      "currency": "KRW",
      "status": 1,
      "created_at": "2026-03-16T08:30:00Z",
      "updated_at": "2026-03-16T08:30:00Z"
    }
  ]
}

Note: The response envelope field is named page_size, but the query parameter to control it is size. This is consistent across all player and bet endpoints.

---

Step 2 — Get Player Detail

GET /api/player/{player_id}

Returns full profile information for a single player, including current wallet balance.

Path parameter: player_id — the numeric ID of the player.

Response:

{
  "id": 8801,
  "team_id": 7,
  "brand_id": 42,
  "username": "johndoe",
  "nickname": "John",
  "currency": "KRW",
  "status": 1,
  "created_at": "2026-03-15T12:00:00Z",
  "updated_at": "2026-04-01T18:22:00Z",
  "wallet_balance": "45200.00",
  "wallet_frozen": "0.00"
}

Field	Description
wallet_balance	Current available balance. null if the player has no wallet record yet.
wallet_frozen	Amount currently held in active game rounds. null if no wallet record.
status	1 = active, 0 = disabled

404 Not Found is returned if the player does not exist or belongs to a different team.

---

Step 3 — List Player Transactions

GET /api/player/{player_id}/transactions

Returns the paginated transaction history for a player. Each transaction represents a wallet event — a debit (bet placed), credit (win paid out), or rollback (bet cancelled).

Path parameter: player_id — the numeric ID of the player.

Query parameters:

Parameter	Type	Default	Constraints	Description
page	integer	1	≥ 1	Page number
size	integer	20	1–100	Items per page

Example request:

GET /api/player/8801/transactions?page=1&size=20

Response:

{
  "total": 342,
  "page": 1,
  "page_size": 20,
  "items": [
    {
      "id": 55001,
      "team_id": 7,
      "brand_id": 42,
      "player_id": 8801,
      "type": "debit",
      "amount": "10000.00",
      "balance_before": "55200.00",
      "balance_after": "45200.00",
      "ref_id": "txn_abc123",
      "memo": "Bet placed - round_id: rnd_9988",
      "created_at": "2026-04-06T10:15:00Z"
    },
    {
      "id": 55000,
      "team_id": 7,
      "brand_id": 42,
      "player_id": 8801,
      "type": "credit",
      "amount": "25000.00",
      "balance_before": "30200.00",
      "balance_after": "55200.00",
      "ref_id": "txn_xyz789",
      "memo": null,
      "created_at": "2026-04-06T10:12:00Z"
    }
  ]
}

Field	Description
type	Transaction type: "debit", "credit", or "rollback"
amount	Transaction amount (always positive)
balance_before	Wallet balance immediately before this transaction
balance_after	Wallet balance immediately after this transaction
ref_id	External reference ID provided by the game provider, if any
memo	Free-text note attached to the transaction, if any

Results are ordered by most recent first (descending by id).

---

Important Notes

• Players cannot be created via this API. Players are registered automatically when they first connect through a game provider using a Brand's credentials.
• size parameter (not page_size) is used for pagination on all player and transaction list endpoints. Maximum value is 100.
• wallet_balance and wallet_frozen may be null for players who registered but have never performed a wallet transaction.
• Cross-team isolation is enforced. You can only access players belonging to your own Team. Attempting to access another team's player ID returns 404 Not Found.
• Transaction history is append-only and ordered by most recent first. Use page and size to iterate through older records.