---
# System prepended metadata

title: Multiplayer API

---

# Multiplayer API

[wss://games-dev.casinogate.dev/ws/BigPanda?session={{session}}](https://)

[wss://games-stage.casinogate.dev/ws/BigPanda?session={{session}}](https://)

[wss://games.casinogate.io/ws/BigPanda?session={{session}}](https://)

### Data sent by server
This subsection will be describe all messages sent by the server to the connected players, explaining what happens during the entire cycle of a round. Default values can be set.

Before the round starts, the server sends a message to all connected players with the current provably fair information and the previous result.
This message is sent only once per round, before the round starts:
```javascript
{
    "messageType": "provablyFair",  // Specifies the type of message being sent
    "provablyFair": { // Object that contains information about the provably fair system.
        "currentResult": null, // The current result used for the fairness calculation (optional if round not finished).
        "hash": "50c40e421f424f06df01eb53512884fe80bddf5c00d8cebd0da5164def24bdb5", // The hash value used to verify the fairness.
        "previousResult": 1750, // The previous result used for the fairness calculation.
        "salt": null // The salt used for generating the hash (optional if round not finished).
    }
}
```

Before the round start and the multiplier increse the server will send to the player one start message.
```javascript
{
    "messageType": "start" // Specifies the type of message being sent
}
```

After that, as the multiplier increases, the server sends the current value of the multiplier to the player. The multiplier is calculated in the backend (test version). 
The value of the current multiplier increase 1% every 200 miliseconds of the current multiplier. The following message is sent to the connected players:
```javascript
{
    "messageType": "multiplier", // Specifies the type of message being sent
    "multiplier": 245 // Represents the multiplier for the current game round
    "denominator": 2 // Denominator for currency conversion or scaling
}
```

When the bonus is triggered the following message is sent to the client. This happens at maximum once per round

```javascript
{
    "messageType": "bonus", // Specifies the type of message being sent
    "bonus": true // Indicates whether a bonus was applied
}
```    
    
#### end of the round
When the *current_multiplier* achieve the value calculated of the *multiplier_achieve*, the player receives the following message:
```javascript
{
    "messageType": "crash", // Specifies the type of message being sent
    "provablyFair": { // Object that contains information about the provably fair system.
        "hash": "def456uvw", // The hash value used to verify the fairness.
        "salt": "randomSaltValue", // The salt used for generating the hash (optional if round not finished).
        "previousResult": 100, // The previous result used for the fairness calculation.
        "currentResult": 230 // The current result used for the fairness calculation (optional if round not finished).
    }
}
```


A waiting message is sent to inform the user about the time remaining until the next round starts and the multiplier values achieved in the last 10 rounds. The format of the waiting message is as follows:
```javascript
{
    "messageType": "wait", // Specifies the type of message being sent
    "time": 5000, // Represents the waiting time in milliseconds
    "bets": [
        {
            "username": "player1", // The username of the player who placed the bet
            "amount": 100, // The amount of the bet
            "betID": "550e8400-e29b-41d4-a716-446655440000", // Unique identifier for the bet
            "identifier": 1, // Internal identifier for the bet
            "currency": "BRL", // Currency type used for the bet
            "denominator": 2 // Denominator for currency conversion or scaling
        },
        {
            "username": "player2",
            "amount": 200,
            "betID": "550e8400-e29b-41d4-a716-446655440001",
            "identifier": 2,
            "currency": "BRL",
            "denominator": 100
        }
    ]
}
```

Once the message with a time value of 0 is sent, the entire cycle restarts, and a new round starts.


### Data sent by player to interate with the game

#### Error

In the event of an error the response follows the structure bellow:

```javascript
{
  "messageType": "error", // The type of message.
  "error": {
    "message": "Session expired or not found", // Describes the error in detail.
    "code": 1000, // The error code, in this case, 400 signifies a bad request.
    "var": null // The optional variable associated with the error. In case of minimum bet value error the minimum amount will be described here
  }
}
```

Possible error codes:

- **500**  - Internal Server Error
- **1000** - Session expired or not found
- **1001** - Bet does not respect minimum bet amount
- **1002** - Bet does not respect maximum bet amount
- **1003** - Bet not found
- **1004** - Bet already placed
- **1005** - Bet could not be placed
- **1006** - Bet could not be canceled
- **1007** - Bet could not be cashed out
- **1008** - Minimum auto cashout value is not valid


#### Wallet

Used to retrieve the current player and game information and enables the player to receive messages from the websocket server.

Request:
```javascript
{
  "messageType": "wallet" // Describes the type of message.
}
```

Response:
```javascript
{
  "messageType": "wallet", // Indicates the type of message.
  "username": "john_doe", // The username associated with the account.
  "balance": 1000, // The user's current balance.
  "denominator": 100, // The denominator used for fractional calculations.
  "currency": "BRL", // The currency in which the balance is represented.
  "isDemo": false, // Indicates whether this transaction is from a demo account.
  "multiplierHistory": [150, 200, 325], // List of multipliers from previous rounds
  "bonusHistory": [true, false, true], // Indicates if a bonus was applied in each corresponding round
  "currentBets": [ // Array of bets in process.
    {
      "betID": "b79b5e9c-4d87-4b26-a15e-253aba292c3e", // Unique bet ID.
      "createdAt": "2025-02-12T15:30:00Z", // Timestamp of bet placement.
      "amount": 100, // Bet amount.
      "denominator": 100, // Fractional denominator.
      "currency": "BRL", // Bet currency.
      "isDemo": false, // Indicates if bet was in demo mode.
      "identifier": 1, // A unique identifier for this bet.
      "isAutoCashout": true // Indicates if bet is autocashout
    }
  ],
  "provablyFair": {
        "hash": "49385bf10957652abed9ea94734813d249b233e6704333f5cd45650d67866cf7",
        "salt": null,
        "previousResult": 1000,
        "currentResult": null
  },
    "maxBet": 5000, 
    "minBet": 10,
    "defaultBet": 10,
    "rtp": "0.95",
    "volatility": "high", 
    "limitValues": {
        "minMultiplier": 1,
        "maxMultiplier": 1750,
         "minCrashPoint": 100,
         "MaxCrashPoint": 1750000
    }   
}
```

#### Bet

To place a bet, the player needs to send a JSON message in the following format:
```javascript
{
  "messageType": "bet", // Describes the type of message.
  "amount": 500, // The amount for the bet.
  "identifier": 1, // A unique identifier for this bet.
  "autoCashoutMultiplier": 250 // The auto-cashout multiplier, nullable if not needed.
}
```

The response provides the updated bet information after the bet is placed:
```javascript
{
  "messageType": "bet", // Describes the type of message.
  "username": "john_doe", // The username associated with the account.
  "balance": 1000, // The user's current balance.
  "denominator": 100, // Denominator for calculating fractional amounts.
  "identifier": 1, // A unique identifier for this bet.
  "currency": "BRL", // The currency in which the balance is displayed.
  "betID": "a32c9f7b-b7b5-4d1b-b2bc-5b388928ffb4", // Unique identifier for the bet (UUID format).
  "isDemo": false, // Whether the bet is from a demo account (true/false).
}
```

#### Win

After the round starts and a bet being placed, if the player wants to perform a cashout, they need to send a "win" message, even if the player set an autocash value:
```javascript
{
  "messageType": "win", // Describes the type of message, in this case, "request".
  "betID": "b79b5e9c-4d87-4b26-a15e-253aba292c3e", // A unique bet ID (UUID format).
  "cashoutAt": 130 // Multiplier to cashout at, only valid if current multiplier is higher (optional)
}
```


The response provides the updated win information after the cashout:
```javascript
{
  "messageType": "win", // Type of the message, here it's "success".
  "username": "john_doe", // The username associated with the account.
  "balance": 1000, // The user's current balance.
  "denominator": 100, // The denominator used for fractional calculations.
  "currency": "BRL", // The currency in which the balance is represented.
}
```
*NOTE:* If some error occur during the game related to autocash the server do automatically one "general" checkwin, to pay to player the due amount.


#### Bet cancel

The player can also cancel their bet before the round starts. To do that, they need to send the following message:
```javascript
{
    "msgType": "bet_cancel", 
    "betID": "b79b5e9c-4d87-4b26-a15e-253aba292c3e", // A unique bet ID (UUID format).
}
```
The response provides the updated wallet information after the bet is canceled:
```javascript
{
  "messageType": "bet_cancel", // Indicates the type of message.
  "betID": "b79b5e9c-4d87-4b26-a15e-253aba292c3e", // id (UUID format) of the canceled bet
  "username": "john_doe", // The username associated with the account.
  "balance": 1000, // The user's current balance.
  "denominator": 100, // The denominator used for fractional calculations.
  "currency": "BRL", // The currency in which the balance is represented.
}
```

#### Bet History

The player has the ability to retrieve a comprehensive record of their personal wagers placed within the timeframe spanning from the previous day up until the present moment. To accomplish this, the player is required to transmit the following message to the server:
```javascript
{
  "messageType": "bet_history", // Describes the type of message.
}
```
The response confirms the successful sending of the message:
```javascript
{
  "messageType": "bet_history", // Type of the message.
  "username": "john_doe", // The username associated with the account.
  "history": [ // An array of historical bet data.
    {
        "betID": "ffa54eab-a9f0-42a0-8fc6-a52f9c3e8983", // Unique identifier for the bet.
        "createdAt": "2025-10-16 13:45:37", // Timestamp of when the bet was placed.
        "amount": 333, // The amount of the bet.
        "balanceBeforeBet": 100000, // The balance before the bet was placed.
        "balanceAfterBet": 100037, // The balance after the bet was placed.
        "winAmount": 370, // The amount won from the bet.
        "difference": 37, // The difference between the win amount and the bet amount.
        "withdrawMultiplier": "1.11x", // The multiplier at which the bet was cashed out.
        "denominator": 10000, // Denominator for fractional calculations.
        "currency": "ADA", // The currency in which the bet was placed.
        "isDemo": true, // Indicates whether the bet was placed in demo mode.
        "provablyFair": {
            "hash": "d16829715e6", // The hash value used to verify the fairness.
            "salt": "c6c2b091-aa24-4e5d-", // The salt used for generating the hash.
            "previousResult": 2873, // The previous result used for the fairness calculation.
            "currentResult": 267 // The current result used for the fairness calculation.
        }
    }
  ]
}
```
#### Chat

Players can send chat messages to all other connected players. To send a message, use:

```javascript
{
  "messageType": "chat", // Describes the type of message.
  "message": "Hello, everyone!" // The chat message (max 255 characters, no links allowed).
}
```

The server responds with a confirmation:

```javascript
{
  "messageType": "chat", // Type of the message.
  "status": "success", // Status of the operation.
  "statusCode": 200 // HTTP status code.
}
```

**Chat rules:**
- Messages must not be empty and cannot exceed 255 characters.
- Links are not allowed in messages.
- Rate limiting is enforced: each user can send a limited number of messages per time window (configurable).

Chat messages are broadcast to all connected players in real time.

```javascript
{
  "messageType": "chat",
  "username": "testUser",
  "message": "hello world",
  "timestamp": <unix-format>
}
```

#### Top Win

Players can request the leaderboard of the top 20 highest wins for a specific period. To retrieve this information, send the following message to the server:

```javascript
{
  "messageType": "top_win", // Describes the type of message.
  "time": "day" // Time period: "day", "month", or "year".
}
```

The server responds with the top win history for the requested period:

```javascript
{
  "messageType": "top_win", // Type of the message.
  "time": "day", // The requested period.
  "history": [
    {
      "date": "2025-05-25 14:00:00", // Date and time of the win.
      "bet_amount": 500, // Amount of the bet.
      "value_cash_out": 300, // Multiplier at cashout.
      "winning_amount": 1500, // Total amount won.
      "username": "winner123" // Username of the player.
      "denominator": 100, // Denominator for fractional calculations.
      "currency": "BRL" // Currency identifier
    }
  ],
  "statusCode": 200 // HTTP status code.
}
```
- The `time` field must be one of: `"day"`, `"month"`, or `"year"`.
- The `history` array contains the top wins for the specified period.

#### Multiplier History

Show the last 27 crash multipliers for current game.

Request:
```json
{
    "messageType": "multipliers"
}
```

Response:
```json
{
    "messageType": "multipliers",
        "multiplierList": [
        100, ... , 252
    ]
}
```

## Provably fair

How to calculate the hash:

**hash** = sha256(`previousResult` + `salt` + `currentResult`)

The omission of `salt` and `currentResult` makes it so that the `currentResult` is not discoverable

## Denominator

Using denominations avoids senarios where `float` are rounded to the next number with excessive number of decimal cases. 

How to use:

Backend response:
```javascript
{
    amount: 200
    denominator: 100
}
```

Is Equivalent to:

```javascript
{
    amount: 2.00
}
```

# Game Error Documentation

## Error Codes Overview

| Code | Message                                 |
| ---- | --------------------------------------- |
| 1000 | SessionID expired or not found          |
| 1001 | Bet does not respect minimum bet amount |
| 1002 | Bet does not respect maximum bet amount |
| 1003 | Bet not found                           |
| 1004 | Bet already placed                      |
| 1005 | Bet could not be placed                 |
| 1006 | Bet could not be canceled               |
| 1007 | Bet could not be cashed out             |
| 1008 | Minimum auto cashout value is not valid |
| 1009 | Game already started                    |
| 1010 | Game not finished                       |
| 1011 | Game crashed                            |
| 1012 | Ongoing game not found                  |
| 1013 | Invalid message type                    |


## Common Message Types
These message types are used across both game modes:
- `wallet` - Balance operations
- `bet` - Bet placement
- `bet_cancel` - Bet cancellation 
- `win` - Win notifications
- `bet_history` - Game history

## Error Response Format
```json
{
  "messageType": "errorResponse",
  "error": {
    "message": "Invalid bet amount",
    "code": 400,
    "var": 100
  }
}
```
