FairDealPlus API Docs

🎮 Player Test Access

📋 Overview

🔐 Authentication

{ "success": true, "token": "eyJhbGci..." }

{ "success": true, "token": "eyJhbGci..." }

{ "success": true, "message": "Password updated" }

👤 Player APIs

All routes under /api/player/* require JWT token. Send as: Authorization: Bearer TOKEN

{
  "success": true,
  "data": {
    "id": "035e2653-50a1-4c68-977b-ffc25badcede",
    "userName": "player01",
    "role": "player",
    "creditPoint": 1500,
    "isActive": true,
    "isLogin": true,
    "type": "RV"
  }
}

{
  "bets": [
    { "id": "uuid", "game": "rouletteTimer40", "betAmount": 100,
      "wonAmount": 3600, "winPosition": "7", "createdAt": "..." }
  ],
  "page": 1, "limit": 20
}

{
  "game": "rouletteTimer40",
  "results": ["26", "3", "11", "0", "36"],
  "x": [1, 1, 1, 1, 1]
}

{ "message": "Point request submitted", "requestId": "uuid" }

{ "success": true, "message": "Logged out" }

🛡️ Admin APIs

Requires admin/agent/distributor/superAdmin JWT token.

{ "count": 5, "players": [{ "id":"...", "userName":"player01", "creditPoint": 1500 }] }

{
  "gameName": "spinToWin",
  "totalCollection": 50000,
  "totalPayment": 43200,
  "lastResults": ["3","7","1"],
  "xs": [1,1,1]
}

{ "isActive": false }

⚡ WebSocket Connection

Unity Connection Code Example

// 1. Connect
WebSocket ws = new WebSocket("ws://SERVER_IP:5018/ws");
await ws.Connect();

// 2. Send event
string msg = JsonConvert.SerializeObject(new {
    @event = "join",
    data = new { token = playerToken, gameName = "rouletteTimer40" }
});
await ws.SendText(msg);

// 3. Receive
ws.OnMessage += (bytes) => {
    var text = System.Text.Encoding.UTF8.GetString(bytes);
    var msg = JsonConvert.DeserializeObject<SocketMsg>(text);
    Debug.Log($"Event: {msg.@event}, Data: {msg.data}");
};

📤 Client → Server Events

// Send:
{ "event": "join", "data": { "token": "eyJ...", "gameName": "rouletteTimer40" } }

// Response event: "join"
{
  "event": "join",
  "data": {
    "creditPoint": 1500,
    "gameName": "rouletteTimer40",
    "gamelastdata": ["26","3","11","7","0"],
    "x": [1,1,1,1,1],
    "gameState": { "positions": {}, "adminBalance": 0 }
  },
  "status": 1
}

// Request
{ "event": "checkLogin", "data": { "token": "eyJ..." } }

{ "event": "state_snapshot", "data": {
    "room": "rouletteTimer40", "resumed": true,
    "creditPoint": 1500.0,
    "state": { /* current round state from GameEngine */ },
    "gamelastdata": ["7","26","11"], "x": [1,1,1]
} }
{ "event": "session_status", "data": { "resumed": true, "room": "rouletteTimer40" } }

{ "event": "session_status", "data": { "resumed": false, "room": "" } }

{ "event": "error", "data": { "message": "Invalid token" } }

{ "event": "logout", "data": { "message": "Another device login" } }

// Send:
{
  "event": "placeBet",
  "data": {
    "playerId": "035e2653-50a1-4c68-977b-ffc25badcede",
    "gameName": "rouletteTimer40",
    "betPoint": 150,
    "position": { "7": 100, "red": 50 }
  }
}

// Response event: "placeBet"
{ "event": "placeBet", "data": { "handId": "bet-uuid", "gameName": "rouletteTimer40", "result": "Bet placed successfully" }, "status": 1 }

{ "event": "placeBetAB", "data": { "playerId": "...", "gameName": "andarBahar", "betPoint": 100, "position": { "side": "A" }, "round": 1 } }

// Send:
{ "event": "placeBetRoulette", "data": { "playerId": "...", "betPoint": 200, "position": { "7": 100, "red": 50, "even": 50 } } }

// Instant Response:
{ "event": "result", "data": { "handId": "uuid", "gameName": "roulette", "data": "7", "winAmount": 3600 } }

{ "event": "placeBetManualSpin", "data": { "playerId": "...", "betPoint": 100, "position": { "5": 100 } } }

// Instant:
{ "event": "result", "data": { "handId": "uuid", "gameName": "manualSpin", "data": "5", "winAmount": 900 } }

{ "event": "joinAdmin", "data": { "adminId": "admin-uuid", "gameName": "rouletteTimer40" } }

// Response:
{ "event": "resAdmin", "data": { "numbers": [...], "totalCollection": 5000, "totalPayment": 4200 } }

{ "event": "winByAdmin", "data": { "gameName": "rouletteTimer40", "cardNumber": 7, "y": 1.0 } }

{ "event": "balanceupdate", "data": { "userid": "player-uuid" } }

// Response: "UPDATED_WALLET" event with new balance number

📥 Server → Client Events

These events are pushed by the server. Unity should listen for all of them.

Timer Game Round Flow (rouletteTimer40 example)

  [0s]    Server → "newRound"   { gameName, gamelastdata, state }
  [0-45s] Player  → "placeBet"   { position, betPoint }
  [45s]   Server → "betClosed"  { gameName }
  [53s]   Server → "result"     { data: "7", x: 1, gamelastdata: ["7","26",...] }
          Server → "UPDATED_WALLET"  1400   (only to winner)
  [53s]   Next round begins → "newRound" again

Andar Bahar Round Flow

  [0s]    Server → "newRound"   { gameName: "andarBahar", round: 1 }
  [0-30s] Player → "placeBetAB" { side: "A", betPoint: 100 }
  [30s]   Server → "betClosed"  { round: 1 }
  [30s]   Server → "round2"     { gameName, round: 2 }
  [30-45s] Player → "placeBetAB" { side: "B", betPoint: 50 }
  [45s]   Server → "betClosed"  { round: 2 }
  [45s]   Server → "result"     { data: "A" or "B" }   pays 2x

🔁 Reconnect & Grace Period

When a mobile app goes to background the OS freezes / kills the WebSocket within ~30s. To avoid kicking the player out of an in-progress round, the server holds disconnected players in a 45-second reconnect-grace buffer before running the real cleanup. If the player reconnects within that window, the previous game room and session are restored seamlessly.

Server-side behavior on disconnect

Unity reconnect flow

  [App background]
       ↓ (close socket explicitly on OnApplicationPause(true))
  Server: buffer player → 45s grace timer started

  [App foreground, 30s later]
       ↓ open new WebSocket
       ↓ Send: { "event": "checkLogin", "data": { "token": "..." } }
       ↓
  Server matches userID against pending buffer:
       ├── Found       → emit "state_snapshot" + "session_status" {resumed:true}
       ├── Not found   → emit "session_status" {resumed:false}
       ├── Bad token   → emit "error" {message:"Invalid token"}
       └── Hijacked    → emit "logout" {message:"Another device login"}

  [Unity reads session_status]
       ├── resumed:true  → restore game UI from state_snapshot — DONE
       ├── resumed:false → go to lobby, send "join" event
       └── error/logout  → clear token, return to login

Unity SocketManager pseudocode

void OnApplicationPause(bool paused) {
    if (paused) {
        socket?.Close();  // clean signal to server
    } else {
        StartCoroutine(ReconnectWithBackoff());  // 1s, 2s, 4s, 8s, 15s
    }
}

void OnMessage(SocketMsg msg) {
    switch (msg.@event) {
        case "state_snapshot":
            GameUI.RestoreFromSnapshot(msg.data); break;
        case "session_status":
            if (!msg.data.resumed && wasInGame) GoToLobby(); break;
        case "error":
            if (msg.data.message == "Invalid token") ClearTokenAndGoToLogin(); break;
        case "logout":
            ClearTokenAndGoToLogin(msg.data.message); break;
        case "maintenance":
            ShowMaintenanceScreen(msg.data.message); break;
        // ... game events: newRound, betClosed, result, win, UPDATED_WALLET ...
    }
}

Server log signatures (for debugging)

// Disconnect → buffered:
Client disconnected (buffered 45s): <userID> room=rouletteTimer40

// Reconnect within grace:
Reconnect within grace: user=<userID> prev_room=rouletteTimer40

// Grace expired (no reconnect within 45s):
Reconnect grace expired: user=<userID> — full cleanup done

Live monitor: journalctl -u fairdealplus-go -f | grep -E "buffered|grace|Reconnect"

🧪 WebSocket Live Tester

🎲 Game List

💰 Roulette Position Reference

Example Multi-position Bet

{
  "event": "placeBet",
  "data": {
    "playerId": "035e2653-50a1-4c68-977b-ffc25badcede",
    "gameName": "rouletteTimer40",
    "betPoint": 350,
    "position": {
      "7":    100,   // 100 on number 7 → wins 3600 if 7 hits
      "red":  100,   // 100 on red → wins 200 if red hits
      "odd":  100,   // 100 on odd → wins 200 if odd hits
      "dozen1": 50   // 50 on 1-12 → wins 150 if 1-12 hits
    }
  }
}