Game Settlement

All About Game Settlement API

Before utilizing these APIs, it is essential to have a clear understanding of the concept of game settlement and ZooGames user wallets.

Ready

You can utilize this API to verify the eligibility of players who wish to join a game while they are in the lobby or waiting room. The API allows you to perform several checks to ensure that each player meets the necessary requirements. These checks include:

1. Validating the vZOO balance of each player: Ensuring that each player has a sufficient balance of vZOO tokens to participate in the game.

2. Checking if a player has been banned from the platform: Verifying if a player has been restricted from accessing the game due to violations or other reasons.

3. Verifying that the cost of joining the game does not exceed the maximum vZOO spending limit set for the game.

4. Grant access to the user if they pass all the validations of the game settlement.

5. Checking if the number of players exceeds the limit set for the game: Ensuring that the number of players attempting to join does not exceed the specified limit.

6. Verifying if the game owner's mirror address has sufficient vZOO balance: This check is useful if the game owner needs to top-up the reward or provide additional funds.

7. Verifying if the game has been verified by Zoo.Games: This check ensures that the game has undergone the necessary verification process by Zoo.Games.

We recommend that the game server performs these checks for each player upon entry. By calling this API with the relevant player information, the game server can determine if a player meets the criteria. If a player fails to pass any of the checks, the game server should reject their entry and remove them from the lobby or waiting room. This process helps maintain the integrity and fairness of the game environment.

Verify all information of players before starting the game

POST API_END_POINT_URL/API_KEY/game/ready

SDK Preparation

You need to prepare for SignedSignatureFromPayload by

Installing zoo-game-sdk by npm install zoo-game-sdk

Import SDK by import * as ApiKey from 'zoo-game-sdk/src/auth/apikey/index'

Signing by SDK

let bodyMessage =JSON.stringify(payload);

let hmac = ApiKey.signData(bodyMessage, SEC_KEY);

*Use "hmac" as SignedSignatureFromPayload

Query Parameters

Name	Type	Description
API_KEY*	String	API_KEY

Request Body

Name	Type	Description
userJwts*	Array	Array of user's JWT Token list. - Must be arranged by the user entry order
userPrimaryAddresses*	Array	Array of user's primary address. - Must be arranged by the user entry order - Exact same array length as user JWT
userLockAmounts*	Array	Array of user's spending vZOO. - Must be arranged by the user entry order - Exact same array length as user JWT - The value must be less than Game Config "maxVZOO"
gameAddress*	Address	Address of Game/Project registered Primary Address
gameLockAmount*	Number	Game owner top-up amount in this game - Entry 0 for no top-up

200: OK Return of JSON result

First Tab

{
  success: true,
  data: {
    roundId: '0xe3c4937ee22e1f2eb80d2d7a881e7777de9aa547006a145f4dd5bb8ec7b40e31'
  }
}

This roundId doesn't be used on this time.

Second Tab

// Error by API //
{
    success: false;
    message: 'The primary error message',
    data: {
        errors: [
            {
                message: "sub error message #1",
                data: {
                   // requested data//
                }
            },
            {
                message: "sub error message #2",
                data: {
                   // requested data//
                }
            }
        ];
    }
}
// Error by Contract / Reverted by contract //
{
  success: false,
  message: 'Contract Pre-Check Error',
  data: {
    op: '0x95A6010F499005DE33F0DD526ce8f5a36CeA45a3',
    scError: {
        // Reverted reason //
    }
  }
}

List of error messages

Errors	Description
checkApiKey invalid api key (user not in allow list)	Your registered game isn't verified
game_address not match	API Key and game_address doesn't match
jwt malformed	JWT Tokens incorrect
Game round already started	Generated Round ID already started. Please try to call this function again
Game not enabled	Your registered game isn't verrified
Too many players	Number of Players exceeded maxPlayerPerRound in Globl Game config
No players	No players list sent
Player count mismatch	The list doesn't match of length
Game has not enough VZOO	In case you want to top-up a reward. This mean game mirror address doesn't have enough vZOO as a fund
vZOO Balance not enough	Some Players don't have enough vZOO to spend
gameVerify gameAddress not match in user Jwt	gameAddress in JWT payload doesn't match with same as caller gameAddress
gameVerify user Jwt expired	Player's JWT already expired. Need to approve again
gameVerify user allowance not enough	Player didn't approve to spend enough vZOO by requirement
gameVerify user balance not enough	Player don't have enough balance to spend
Player amount too large	vZOO require per use is higher than MAX vZOO LIMIT Global Game Config
Player has no ticket	If game required to purchase a ticket. It means Player dont have a ticket
User was banned	This user was banned from the system

Example of Game Settlement - Ready

Here's a simple example of using the "Ready" API with 2 players in the lobby/waiting room:

Assuming the game developer wants to add an extra reward of 10 vZOO and the entry fee for each user is 10 vZOO, we can calculate that the total reward pool is 30 vZOO.

Please ensure that the list of players is ordered according to their entry into the lobby/waiting room.

import * as ApiKey from 'zoo-game-sdk/src/auth/apikey/index'
import axios from 'axios';

// Initialized API KEY and SECRET KEY
const API_KEY = 'YourApiKey';
const SEC_KEY = 'YourSecretKey';
const GAME_ADDRESS = '0x8Cf0A877E906DEaD748A41aE9EA8c220E4247D35';
// Signing body data with HMAC signing
let body = {
    userJwts: ['Player#1 JWT', 'Player#2 JWT'], // JWTs by ordered of entry
    userPrimaryAddresses: ['0x682A8B3683292442fACa52e9B6537Fabcd0AE568','0x79CA8B3683292442fACa52e9B6537FE58d0AE576'],
    userLockAmounts: [10,10],
    GAME_ADDRESS,
    gameLockAmount: 10,
  };
let bodyMessage = JSON.stringify(body); 
let hmac = ApiKey.signData(bodyMessage, SEC_KEY); // hmac or SignedSignatureFromPayload  

// Request by Post Method //
let ret = await axios.post(`/api/${API_KEY}/game/ready`, body, {headers:{Authorization: `Bearer ${hmac}`}});
console.log('game ready:', ret.data);

Start

After using the "Ready" API to verify the validity of the game settlement, you can proceed to use the "Start" function to initiate the game round. The Start API allows you to lock the specified amounts from the users and the game developer based on your provided parameters.

• When calling the "Start" API, it will internally trigger the "Ready" API again for a final check. This ensures that the game settlement is verified before proceeding. Additionally, it is important to maintain the order of user entries, preserving the index of the array to accurately track and process each player's participation.

• After executing the "Start" function, remember to record the "roundId" provided by the API. This identifier will be required for subsequent API calls such as the "Game Over" API or "Game Cancel" API, enabling proper tracking and management of the game round.

• It is crucial to keep track of the total vZOO spent by the users and the game address during the game round. This information will be necessary for broadcasting the final reward. By accurately recording and storing these values, you can ensure the proper distribution of rewards to the participants.

• Overall, by following these guidelines and maintaining the necessary data and order, you can effectively utilize the "Start" API to initiate the game round and proceed with subsequent actions, including reward distribution and game conclusion.

Start the game round

POST API_END_POINT_URL/API_KEY/game/start

SDK Preparation

You need to prepare for SignedSignatureFromPayload by

Installing zoo-game-sdk by npm install zoo-game-sdk

Import SDK by import * as ApiKey from 'zoo-game-sdk/src/auth/apikey/index'

Signing by SDK

let bodyMessage =JSON.stringify(payload);

let hmac = ApiKey.signData(bodyMessage, SEC_KEY);

*Use "hmac" as SignedSignatureFromPayload

Query Parameters

Name	Type	Description
API_KEY*	String	API_KEY

Request Body

Name	Type	Description
userJwts*	Array	Array of user's JWT Token list. - Must be arranged by the user entry order
userPrimaryAddresses*	Array	Array of user's primary address. - Must be arranged by the user entry order - Exact same array length as user JWT
userLockAmounts*	Array	Array of user's spending vZOO. - Must be arranged by the user entry order - Exact same array length as user JWT - The value must be less than Game Config "maxVZOO"
gameAddress*	Address	Address of Game/Project registered Primary Address
gameLockAmount*	Number	Game owner top-up amount in this game - Entry 0 for no top-up

200: OK Return of JSON result

First Tab

{
  success: true,
  data: {
    roundId: '0xe3c4937ee22e1f2eb80d2d7a881e7777de9aa547006a145f4dd5bb8ec7b40e31',
    txHash: '0xe259f525616f295e877a0da35b59e45f6c2e48c340a16102eb995f0d0c4c36a1'
  }
}

This roundId need to be saved locally to use on futher APIs

Second Tab

// Error by API //
{
    success: false;
    message: 'The primary error message',
    data: {
        errors: [
            {
                message: "sub error message #1",
                data: {
                   // requested data//
                }
            },
            {
                message: "sub error message #2",
                data: {
                   // requested data//
                }
            }
        ];
    }
}
// Error by Contract / Reverted by contract //
{
  success: false,
  message: 'Contract Pre-Check Error',
  data: {
    op: '0x95A6010F499005DE33F0DD526ce8f5a36CeA45a3',
    scError: {
        // Reverted reason //
    }
  }
}

List of error messages

Errors	Description
checkApiKey invalid api key (user not in allow list)	Your registered game isn't verified
game_address not match	API Key and game_address doesn't match
jwt malformed	JWT Tokens incorrect
Game round already started	Generated Round ID already started. Please try to call this function again
Game not enabled	Your registered game isn't verrified
Too many players	Number of Players exceeded maxPlayerPerRound in Global Game config
No players	No players list sent
Player count mismatch	The list doesn't match of length
Game has not enough VZOO	In case you want to top-up a reward. This mean game mirror address doesn't have enough vZOO as a fund
vZOO Balance not enough	Some Players don't have enough vZOO to spend
gameVerify gameAddress not match in user Jwt	gameAddress in JWT payload is not matched to caller gameAddress
gameVerify user Jwt expired	Player's JWT has expired. Need to re-approve it
gameVerify user allowance not enough	Player didn't approve to spend enough vZOO by requirement
gameVerify user balance not enough	Player don't have enough balance to spend
Player amount too large	vZOO require per use is higher than MAX vZOO LIMIT Global Game Config
Player has no ticket	If game required to purchase a ticket. It means Player dont have a ticket
User was banned	This user was banned from the system

Example of Game Settlement - Start

Here's a simple example of using the "Start" API with 2 players in the lobby/waiting room:

Assuming the game developer wants to add an extra reward of 10 vZOO and the entry fee for each user is 10 vZOO, we can calculate that the total reward pool is 30 vZOO.

*Please make sure that the list of players is ordered based on their entry into the lobby/waiting room.

**Note: Please ensure that you have already verified the data from the "Game Ready" API before calling this function.

import * as ApiKey from 'zoo-game-sdk/src/auth/apikey/index'
import axios from 'axios';

// Initialized API KEY and SECRET KEY
const API_KEY = 'YourApiKey';
const SEC_KEY = 'YourSecretKey';
const GAME_ADDRESS = '0x8Cf0A877E906DEaD748A41aE9EA8c220E4247D35';
// Signing body data with HMAC signing
let body = {
    userJwts: ['Player#1 JWT', 'Player#2 JWT'], // JWTs by ordered of entry
    userPrimaryAddresses: ['0x682A8B3683292442fACa52e9B6537Fabcd0AE568','0x79CA8B3683292442fACa52e9B6537FE58d0AE576'],
    userLockAmounts: [10,10],
    GAME_ADDRESS,
    gameLockAmount: 10,
  };
let bodyMessage = JSON.stringify(body); 
let hmac = ApiKey.signData(bodyMessage, SEC_KEY); // hmac or SignedSignatureFromPayload  

// Request by Post Method //
let ret = await axios.post(`/api/${API_KEY}/game/start`, body, {headers:{Authorization: `Bearer ${hmac}`}});
console.log('game ready:', ret.data);

Over

The Over API is used to finalize the game round and broadcast the rewards that each user will receive from the locked vZOO pool of a specific game. The rules for distributing rewards are as follows:

1. The total amount paid by players should not exceed the total locked vZOO in the pool.

2. Assume you have two players with an entry fee of 100 vZOO each, resulting in a locked vZOO pool of 200 vZOO. If the final reward is 190 vZOO for Player A and 10 vZOO for Player B (determined by the game), you need to call the "Game Over" API with adjusted rewards.

3. If the game developer is entitled to receive a fee from the players' rewards, it should be deducted accordingly. This deduction occurs after the platform fee calculation.

4. It's essential to ensure that the total amount paid by players, including the platform fee, does not exceed the locked vZOO pool amount.

5. If the game developer has topped up additional rewards for this round, it is necessary to follow the rule of "Total paid + Platform Fee <= Locked vZOO Pool amount."

By adhering to these rules and providing the adjusted rewards (after deducting the platform fee and game developer's fee, if applicable), the "Game Over" API can be used to distribute the final rewards to the players.

Finalize the game round with broadcast a reward

POST API_END_POINT_URL/API_KEY/game/over

SDK Preparation

You need to prepare for SignedSignatureFromPayload by

Installing zoo-game-sdk by npm install zoo-game-sdk

Import SDK by import * as ApiKey from 'zoo-game-sdk/src/auth/apikey/index'

Signing by SDK

let bodyMessage =JSON.stringify(payload);

let hmac = ApiKey.signData(bodyMessage, SEC_KEY);

*Use "hmac" as SignedSignatureFromPayload

Query Parameters

Name	Type	Description
API_KEY*	String	API_KEY

Request Body

Name	Type	Description
gameResultAmount*	Number	How much reward Game Address wants to takes a reward from the game round. such as Fee or any purposes
usersResultAmount*	Array	Array of user's reward deduct with Platform fee. - Must ordered by entried order of user exactly from Game Start API
roundId*	Hex ID	ID your got from "Game Start" API result. Start with '0x1234....89'
gameAddress*	Address	Address of Game/Project registered Primary Address

200: OK Return of JSON result

First Tab

{
  success: true,
  data: {
    roundId: '0xe3c4937ee22e1f2eb80d2d7a881e7777de9aa547006a145f4dd5bb8ec7b40e31',
    txHash: '0xe259f525616f295e877a0da35b59e45f6c2e48c340a16102eb995f0d0c4c36a1'
  }
}

This roundId need to be saved locally to use on futher APIs

Second Tab

// Error by API //
{
    success: false;
    message: 'The primary error message',
    data: {
        errors: [
            {
                message: "sub error message #1",
                data: {
                   // requested data//
                }
            },
            {
                message: "sub error message #2",
                data: {
                   // requested data//
                }
            }
        ];
    }
}
// Error by Contract / Reverted by contract //
{
  success: false,
  message: 'Contract Pre-Check Error',
  data: {
    op: '0x95A6010F499005DE33F0DD526ce8f5a36CeA45a3',
    scError: {
        // Reverted reason //
    }
  }
}

List of error messages

Errors	Description
Game round not started	Game is not started yet or already overed
Game round not found	Cannot found this game round by roundId
Game round too short	You executed this API too early than Minimum Game round time in Global Game Config
Player count mismatch	Length of users reward not exactly the same with Length of users after you called "Game Start"
Game result amount is too large	Total Paid + Platform fee was more than Total vZOO locked in the pool You need to check gameResultAmount and usersResultAmount parameter

Example of Game Settlement - Over

This is simple example to use "Over" API with the result

• Total Locked is 30 vZOO by 2 usesrs (10 vZOO each) and Game Dev top-up 10 vZOO

• Game Dev don't need any Fee - gameResultAmount = 0

• Users got [18 , 2] but need to substract with 2% Platform Fee then it will be usersResultAmount = [17.64, 1.8]

* Don't forget that this reward list must be ordered by the order of entry to the Lobby / Waiting Room

** If Game Dev want some fee just change gameResultAmount to another number and deduct userResultAmount by each player. But the totalpaid + fee must less than total locked vZOO pool

import * as ApiKey from 'zoo-game-sdk/src/auth/apikey/index'
import axios from 'axios';

// Initialized API KEY and SECRET KEY
const API_KEY = 'YourApiKey';
const SEC_KEY = 'YourSecretKey';
const GAME_ADDRESS = '0x8Cf0A877E906DEaD748A41aE9EA8c220E4247D35';
// Round Id you got from returned value of "Game Start"
const roundId = '0x5a9d48e489bd22ffa627937aec97d2f8e15f0758b3cab9f208f1642450cbb4e6'
// Signing body data with HMAC signing
let body = {
    gameResultAmount: 0,
    usersResultAmount: [17.64, 1.8],
    roundId,
    GAME_ADDRESS ,
  };
let bodyMessage = JSON.stringify(body); 
let hmac = ApiKey.signData(bodyMessage, SEC_KEY); // hmac or SignedSignatureFromPayload  

// Request by Post Method //
let ret = await axios.post(`/api/${API_KEY}/game/over`, body, {headers:{Authorization: `Bearer ${hmac}`}});
console.log('game ready:', ret.data);

Over V2

This is similar to V1, but there’s no need to deduct a fee. You can input the full amount of rewards. The only condition is that the total reward amount must match exactly.

For example, if you startAPI request with 4 players and each player has locked 100 vZOO, then the total locked vZOO is 400 vZOO.

With this Over V2 API, you need to distribute all 400 vZOO to the players. The reward amount cannot be less or more than this. It must be exactly 400 vZOO.

Finalize the game round with broadcast a reward

POST API_END_POINT_URL/API_KEY/game/over_v2

SDK Preparation

You need to prepare for SignedSignatureFromPayload by

Installing zoo-game-sdk by npm install zoo-game-sdk

Import SDK by import * as ApiKey from 'zoo-game-sdk/src/auth/apikey/index'

Signing by SDK

let bodyMessage =JSON.stringify(payload);

let hmac = ApiKey.signData(bodyMessage, SEC_KEY);

*Use "hmac" as SignedSignatureFromPayload

Query Parameters

Name	Type	Description
API_KEY*	String	API_KEY

Request Body

Name	Type	Description
gameResultAmount*	Number	How much reward Game Address wants to takes a reward from the game round. such as Fee or any purposes
usersResultAmount*	Array	Array of user's reward - Must ordered by entried order of user exactly from Game Start API
roundId*	Hex ID	ID your got from "Game Start" API result. Start with '0x1234....89'
gameAddress*	Address	Address of Game/Project registered Primary Address

200: OK Return of JSON result

First Tab

{
  success: true,
  data: {
    roundId: '0xe3c4937ee22e1f2eb80d2d7a881e7777de9aa547006a145f4dd5bb8ec7b40e31',
    txHash: '0xe259f525616f295e877a0da35b59e45f6c2e48c340a16102eb995f0d0c4c36a1'
  }
}

This roundId need to be saved locally to use on futher APIs

Second Tab

// Error by API //
{
    success: false;
    message: 'The primary error message',
    data: {
        errors: [
            {
                message: "sub error message #1",
                data: {
                   // requested data//
                }
            },
            {
                message: "sub error message #2",
                data: {
                   // requested data//
                }
            }
        ];
    }
}
// Error by Contract / Reverted by contract //
{
  success: false,
  message: 'Contract Pre-Check Error',
  data: {
    op: '0x95A6010F499005DE33F0DD526ce8f5a36CeA45a3',
    scError: {
        // Reverted reason //
    }
  }
}

List of error messages

Errors	Description
Game round not started	Game is not started yet or already overed
Game round not found	Cannot found this game round by roundId
Game round too short	You executed this API too early than Minimum Game round time in Global Game Config
Player count mismatch	Length of users reward not exactly the same with Length of users after you called "Game Start"
Game result amount is too large	Total Paid + Platform fee was more than Total vZOO locked in the pool You need to check gameResultAmount and usersResultAmount parameter

Cancel

The Cancel API is used when there is an issue with a specific game round, and you need to cancel it. By calling this API, all the vZOO tokens that were locked, both from the users and the game address, will be returned in their full amount.

Cancel the game round and return all locked vZOO

POST API_END_POINT_URL/API_KEY/game/cancel

SDK Preparation

You need to prepare for SignedSignatureFromPayload by

Installing zoo-game-sdk by npm install zoo-game-sdk

Import SDK by import * as ApiKey from 'zoo-game-sdk/src/auth/apikey/index'

Signing by SDK

let bodyMessage =JSON.stringify(payload);

let hmac = ApiKey.signData(bodyMessage, SEC_KEY);

*Use "hmac" as SignedSignatureFromPayload

Query Parameters

Name	Type	Description
API_KEY*	String	API_KEY

Request Body

Name	Type	Description
roundId*	Hex ID	ID you get from the "Game Start" API result. Start with '0x1234....89'
gameAddress*	Address	Address of Game/Project registered Primary Address

200: OK Return of JSON result

First Tab

{
  success: true,
  data: {
    roundId: '0xe3c4937ee22e1f2eb80d2d7a881e7777de9aa547006a145f4dd5bb8ec7b40e31',
    txHash: '0xe259f525616f295e877a0da35b59e45f6c2e48c340a16102eb995f0d0c4c36a1'
  }
}

Second Tab

// Error by API //
{
    success: false;
    message: 'The primary error message',
    data: {
        errors: [
            {
                message: "sub error message #1",
                data: {
                   // requested data//
                }
            },
            {
                message: "sub error message #2",
                data: {
                   // requested data//
                }
            }
        ];
    }
}
// Error by Contract / Reverted by contract //
{
  success: false,
  message: 'Contract Pre-Check Error',
  data: {
    op: '0x95A6010F499005DE33F0DD526ce8f5a36CeA45a3',
    scError: {
        // Reverted reason //
    }
  }
}

List of error messages

Errors	Description
Game round not started	Game is not started yet or already overed
Game round not found	Cannot found this game round by roundId
Game round too short	You executed this API too early than Minimum Game round time in Global Game Config
Player count mismatch	Length of users reward not exactly the same with Length of users after you called "Game Start"
Game result amount is too large	Total Paid + Platform fee was more than Total vZOO locked in the pool You need to check gameResultAmount and usersResultAmount parameter