Calls provided by API V2

Introduction

API V2 supports simple operations like gamestart, win, and end. It also provides more complex endpoints. These endpoints let you wager wins. They also track game spin events, for example free spins in a gameround. They prevent the game from consuming more spins than it awarded.

API V2 also provides an interface to the hizi.io certified RNG (random number generator).

Game front ends use these calls to start communication with hizi.io. Game engines and third-party RGS also use these calls.

The following tables summarize the calls. More details and the structure of each call appear below.

Frontend Calls (GET)


Endpoint	Method	Required	Description
`/status`	GET	Optional	Check API status
`/connect`	GET	Mandatory	Establish connection, get long-lived token
`/reconnect`	GET	Optional	Re-establish connection using long-lived token
`/disconnect`	GET	Optional	Signal game close/leave to operator

Game Engine / RGS Calls (POST)


Endpoint	Method	Required	Description
`/testPing`	POST	Optional	Test communication and payload signature
`/startGameRound`	POST	Mandatory	Start round, debit bet, optionally credit win and close
`/startGameOrAddBet`	POST	Optional	Place a bet: start the round, or add a bet to the open round. Only for a game that expects more than one debit
`/endGameRound`	POST	Mandatory	Close a gameround
`/getGameRoundInfo`	POST	Optional	Get info about an open gameround
`/getGameRoundHistoryInfo`	POST	Optional	Get historical info about a closed gameround
`/voidGameRound`	POST	Optional	Void a debit for an open gameround
`/collectWin`	POST	Optional	Collect part or all of open winnings
`/addWin`	POST	Mandatory	Add a win to a gameround
`/wagerWin`	POST	Optional	Wager part or all of open winnings
`/getUncollectedAmount`	POST	Optional	Get amount of uncollected winnings
`/addSpinCounterGameState`	POST	Optional	Track spin events (for example free spins), not needed for RGS-to-RGS
`/getAvailableSpinCounter`	POST	Optional	Get available spin counter, not needed for RGS-to-RGS
`/getTokenForGameRound`	POST	Optional	Get token for a gameround
`/getTokenData`	POST	Optional	Get token data
`/getPlayerData`	POST	Optional	Get the stored data of a player for a game
`/setPlayerData`	POST	Optional	Store data for a player for a game
`/getLastGameRounds`	POST	Optional	Get last gamerounds
`/getRandomResult`	POST	Conditional¹	Get certified RNG result
`/getOperatorSettings`	GET	Optional	Get operator-specific settings
`/getBalance`	POST	Optional	Get player balance

¹ /getRandomResult is not required for a classic RGS-to-RGS integration. If your RGS runs on your own infrastructure and already uses your own certified RNG (the typical RGS-to-RGS case), do not call /getRandomResult. Keep using your certified RNG. Pass its results in the rngResult fields as usual. The hizi.io certified RNG is required only when the game logic runs inside the hizi.io RGS and must get randomness from hizi.io for compliance. This applies to direct game engine integrations hosted by hizi.io, and to a partner RGS hosted within the hizi.io RGS ("RGS inception"). See /getRandomResult below.

Game frontend calls

All calls use the GET method. Each call needs a valid token, except status calls. There are two types of token. The game launcher passes a short-lived token as a URL parameter named “token”. The connect call returns a long-lived token.

GET V2_API_ENDPOINT/status (optional)

API reference: /status

Use this call to check the status of the V2 API. You can call it from the game frontend, the game backend, or a third-party RGS.

parameters: none

response:         a JSON structure containing a message

GET V2_API_ENDPOINT/connect (mandatory to use)

API reference: /connect

The game launcher passes a connect URL and a short-lived token to the game frontend. The game frontend uses this information to establish communication with hizi.io. It also uses this information to get a long-lived token. The game frontend uses the long-lived token to authenticate further calls. The short-lived token is valid for 5 minutes only.

E.g. the game launcher is called via this URL

https://location-of-gamelauncher/index.html?token=206fa387-9565-4fc7-b6e6-b555ae064cfc&login=https%3A%2F%2Fapi.sample.hizi.io%2Fgameapi%2v2%2Fconnect

The game frontend then calls:

https://api.sample.hizi.io/v2/connect?token=206fa387-9565-4fc7-b6e6-b555ae064cfc

parameters: token

response: V2_ConnectReply

GET V2_API_ENDPOINT/reconnect (optional)

API reference: /reconnect

This call is similar to connect but uses a long-lived token from a previous connect call. Use it to reestablish connection after an error message.

parameters: token

response: V2_ConnectReply

GET V2_API_ENDPOINT/disconnect (optional)

API reference: /disconnect

Use this call to signal that a game frontend is closing or leaving to the operator. Some operators require this functionality. Implement this call. For the “token” parameter, use the long-lived token from a previous connect call. The response of this call is not defined. The frontend does not need to wait for the response.

parameters: token

response: none

Game engine / RGS calls

Game engines use this group of calls to communicate with the RGS. Operators do not use these calls. Game engines use these calls only to communicate with the RGS.

Signing RGS requests

All calls use the POST method with a JSON payload. Sign each request with a shared secret to hash the payload. The payload is always a JSON structure.

You need a secret to sign requests. Log in to the hizi.io backoffice with your credentials to get this secret. The signature is a base64-encoded SHA256 HMAC digest of a defined set of request parameters. This method shares the secret without including it in the request. You must also provide a timestamp in a request header field. Include this timestamp in the signature. Concatenate the fields with a hash character (#) before you calculate the SHA256 HMAC.

Every request sends the signature in the request header field X-H-AUTH-SIG. For an example implementation of creating signatures, log in to the hizi.io backoffice and look at the sample code provided.

See the sample source in the Appendix of this document.

Mandatory request headers

When you submit a call, pass the following request headers:


X-Request-Id	Unique ID to identify the call in logs
X-H-AUTH-ID	Game provider ID that hinterzimmer assigns
X-H-AUTH-SIG	Signature of the payload
X-H-TIMESTAMP	Timestamp (included in the signature data)

Response headers

The API sets the following headers in the response when it returns the call result:


X-Response-Status	For a successful call, this header is present and contains “ok”. Any other value, or the absence of this header, indicates an error.
X-H-ERROR-ID	Contains an error code if an error occurs
X-H-ERROR-MSG	An optional error message
X-Response-Id	Unique ID of the response, used to identify the call in logs

POST V2_API_ENDPOINT/testPing (optional)

API reference: /testPing

This call sends a test payload to the API. The API returns the same payload back. Use this call to check basic communication and the signature of the payload.

request: V2_TestPingRequestBody

response:         proxies body back in testDataReceived

Example:

{
  url: '/gameapi/v2/testPing',
  method: 'POST',
  body: '{"testData":{"testInt":1,"testString":"something","testBoolean":true}}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.429Z',
    'x-request-id': '8c00b93dd861405cbeb7c14fded1e72a',
    'x-h-auth-sig': 'fea0tckY+PfMPQA1mfhRsyUWdcJ9BXGseFOgOVE9MvE='
  },
  response: '{"testDataReceived":{"testInt":1,"testString":"something","testBoolean":true}}',
  responseHeaders: {
    'x-request-id': 'c28bb1aa40714c54ad36fe2bc6154939',
    'x-response-id': '1a3b4d1d499c4f43a78cc7a138bebdd5',
    'x-response-status': 'ok'
  }
}

POST V2_API_ENDPOINT/startGameRound (mandatory)

API reference: /startGameRound

This call starts a new gameround and debits the bet. Optionally, it can also credit winnings and close the gameround immediately. Optionally, it can close any existing gameround and collect open winnings.

Use this call for every game that takes one debit per gameround. It is the safer of the two bet calls, because it starts exactly one gameround and takes exactly one debit.

A player can have only one open gameround at a time. This call always starts a new gameround, so a second call on an open gameround fails with error 12 GAMEROUNDALREADYSTARTED. Use /startGameOrAddBet only for a game that expects more than one debit in one gameround.

request: V2_StartGameRoundRequestBody

response: V2_GameAPIReply

Example (no win)

{
  url: '/gameapi/v2/startGameRound',
  method: 'POST',
  body: '{"token":"83020869-abc0-4123-a95e-ee4f5e8e8343","rngResult":{"rngCallId":"5cd23259ea4c49e7b955e79321da4365","result":"test","winAmount":0},"debitInformation":{"debitAmount":100,"currency":"EUR"},"endGame":true}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': '20e6bd07275c42fdb161f86a65a19a61',
    'x-h-auth-sig': 'Wq1xa11DsazyMNYoi26lBbes1P5SmVFc2VujHvgYea4='
  },
  response: '{"tokenData":{"operatorId":"000063d0ef40000000000000001b","playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","mode":"REAL","currency":"EUR","currentToken":"83020869-abc0-4123-a95e-ee4f5e8e8343","language":"DE","currencyMultiplier":1,"gameRound":"9f3e51d518024a98977be80c30106cc3"},"balance":{"totalBalance":6916,"mode":"REAL","currency":"EUR","balances":[{"type":"real","amount":6916,"currency":"EUR"}]},"amountToCollect":0,"amountCredited":0,"gameRoundInfo":{"hash":"9f3e51d518024a98977be80c30106cc3","status":"closed","stake":100,"mode":"REAL","currency":"EUR","game":"efbdc5b0ef8c434cbf11daab2fda0d5d"},"gameState":[{"hash":"9f3e51d518024a98977be80c30106cc3","type":"debit","result":{"winAmount":0},"processedOn":"2023-01-26T11:28:22.126Z"}]}',
  responseHeaders: {
    'x-response-id': '873ae012-ea6b-4b6e-b4d0-3946afb48b06',
    'x-h-error-id': '0',
    'x-h-repeatcount': '0',
    'x-response-status': 'ok',
    'x-request-id': 'c1822729c33f4ba69493ead9154291c9'
  }
}

Example (with win)

{
  url: '/gameapi/v2/startGameRound',
  method: 'POST',
  body: '{"token":"83020869-abc0-4123-a95e-ee4f5e8e8343","rngResult":{"rngCallId":"7c1d45ad589046f3b52fe779ffd96632","result":"test","winAmount":77},"debitInformation":{"debitAmount":100,"currency":"EUR"},"endGame":false}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': 'ace5640f237a4959b9a20e83b82dece7',
    'x-h-auth-sig': '3hG9jfqJtRAIdUppRQc6EJEELhUUtT95xbEAJHFed9A='
  },
  response: '{"tokenData":{"operatorId":"000063d0ef40000000000000001b","playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","mode":"REAL","currency":"EUR","currentToken":"83020869-abc0-4123-a95e-ee4f5e8e8343","language":"DE","currencyMultiplier":1},"balance":{"totalBalance":6816,"mode":"REAL","currency":"EUR","balances":[{"type":"real","amount":6816,"currency":"EUR"}]},"amountToCollect":77,"amountCredited":0,"gameRoundInfo":{"hash":"ff85e29cb4414c89a89829c8411dacc2","status":"open","stake":100,"mode":"REAL","currency":"EUR","game":"efbdc5b0ef8c434cbf11daab2fda0d5d"},"gameState":[{"hash":"ff85e29cb4414c89a89829c8411dacc2","type":"debit","result":{"winAmount":77},"processedOn":"2023-01-26T11:28:22.810Z"}]}',
  responseHeaders: {
    'x-response-id': 'e628b84c-6df4-45d1-9561-d7653e144a3a',
    'x-h-error-id': '0',
    'x-h-repeatcount': '0',
    'x-response-status': 'ok',
    'x-request-id': 'ec8a82e6ce0e4aa79095fe4119756a54'
  }
}

POST V2_API_ENDPOINT/startGameOrAddBet (optional)

API reference: /startGameOrAddBet

This call places a bet. It starts a new gameround on the first bet. It adds a further bet to the open gameround on each later bet.

Use this call only for a game that expects more than one debit

Use /startGameRound for every other game. /startGameRound is the safer call. It starts exactly one gameround and takes exactly one debit, so it rejects a duplicate bet that this call accepts. Choose /startGameOrAddBet only when the game design puts two or more bets in one gameround.

A player can have only one open gameround at a time. /startGameRound always marks its debit as the first debit of a new gameround. So a second /startGameRound on an open gameround fails with error 12 GAMEROUNDALREADYSTARTED and the message gameround <hash> already started. This is correct behaviour. Send the second bet to /startGameOrAddBet instead.

request: V2_StartGameRoundRequestBody (the same body as /startGameRound)

response: V2_GameAPIReply

How the call chooses between start and add

The call compares externalGameProviderRoundId in the request with the gameround on the session token:

Condition	Result
`externalGameProviderRoundId` is absent, or differs from the gameround on the token	The call starts a new gameround. It behaves like `/startGameRound`.
The two values match, and `debitInformation.externalGameProviderTransactionId` differs from the first bet of that gameround	The call adds a bet to the open gameround.
The two values match, and `debitInformation.externalGameProviderTransactionId` equals the first bet of that gameround	The call repeats the first bet. A lost first bet is safe to send again.

How to send more than one bet in one gameround

Send the first bet to /startGameOrAddBet. Set externalGameProviderRoundId to your own gameround id. hizi.io then uses that value as the gameround hash.
Send each later bet to the same call, with the same externalGameProviderRoundId.
Give each bet its own debitInformation.externalGameProviderTransactionId.
Keep both identifiers to 32 characters or fewer.
Send rngResult on every bet. It must carry the keys rngCallId, result and winAmount. The values can be null and 0.
Add one win per bet with /addWin. Give each win its own externalGameProviderTransactionId. Set collect: true to pay the player.
Close the gameround with /endGameRound.

Limits

The call ignores endGame and creditInformation on a bet that it adds to an open gameround. Only the call that starts the gameround reads those two fields. Close the gameround with /endGameRound.
A repeated debitInformation.externalGameProviderTransactionId on a later bet fails with error 37 TRANSACTIONALREADYEXISTS. The call does not answer with a silent success.
A bet cannot join a gameround that started without externalGameProviderRoundId. The comparison in the table above always fails for such a gameround. So set the field on the first bet, even if you expect only one bet.

Example (first bet, which starts the gameround)

{
  url: '/gameapi/v2/startGameOrAddBet',
  method: 'POST',
  body: '{"token":"83020869-abc0-4123-a95e-ee4f5e8e8343","externalGameProviderRoundId":"round-0001","rngResult":{"rngCallId":"5cd23259ea4c49e7b955e79321da4365","result":"","winAmount":0},"debitInformation":{"debitAmount":100,"currency":"EUR","externalGameProviderTransactionId":"bet-0001"},"endGame":false}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': '20e6bd07275c42fdb161f86a65a19a61',
    'x-h-auth-sig': 'Wq1xa11DsazyMNYoi26lBbes1P5SmVFc2VujHvgYea4='
  },
  response: '{"tokenData":{"operatorId":"000063d0ef40000000000000001b","playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","mode":"REAL","currency":"EUR","currentToken":"83020869-abc0-4123-a95e-ee4f5e8e8343","language":"DE","currencyMultiplier":1,"gameRound":"round-0001"},"balance":{"totalBalance":6916,"mode":"REAL","currency":"EUR","balances":[{"type":"real","amount":6916,"currency":"EUR"}]},"amountToCollect":0,"amountCredited":0,"gameRoundInfo":{"hash":"round-0001","status":"open","stake":100,"mode":"REAL","currency":"EUR","game":"efbdc5b0ef8c434cbf11daab2fda0d5d"},"gameState":[{"hash":"round-0001","type":"debit","result":{"winAmount":0},"processedOn":"2023-01-26T11:28:22.126Z"}]}',
  responseHeaders: {
    'x-response-id': '873ae012-ea6b-4b6e-b4d0-3946afb48b06',
    'x-h-error-id': '0',
    'x-h-repeatcount': '0',
    'x-response-status': 'ok',
    'x-request-id': 'c1822729c33f4ba69493ead9154291c9'
  }
}

Example (second bet, which joins the same gameround)

{
  url: '/gameapi/v2/startGameOrAddBet',
  method: 'POST',
  body: '{"token":"83020869-abc0-4123-a95e-ee4f5e8e8343","externalGameProviderRoundId":"round-0001","rngResult":{"rngCallId":"7c1d45ad589046f3b52fe779ffd96632","result":"","winAmount":0},"debitInformation":{"debitAmount":100,"currency":"EUR","externalGameProviderTransactionId":"bet-0002"},"endGame":false}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:24.113Z',
    'x-request-id': 'ace5640f237a4959b9a20e83b82dece7',
    'x-h-auth-sig': '3hG9jfqJtRAIdUppRQc6EJEELhUUtT95xbEAJHFed9A='
  },
  response: '{"tokenData":{"operatorId":"000063d0ef40000000000000001b","playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","mode":"REAL","currency":"EUR","currentToken":"83020869-abc0-4123-a95e-ee4f5e8e8343","language":"DE","currencyMultiplier":1,"gameRound":"round-0001"},"balance":{"totalBalance":6816,"mode":"REAL","currency":"EUR","balances":[{"type":"real","amount":6816,"currency":"EUR"}]},"amountToCollect":0,"amountCredited":0,"gameRoundInfo":{"hash":"round-0001","status":"open","stake":200,"mode":"REAL","currency":"EUR","game":"efbdc5b0ef8c434cbf11daab2fda0d5d"},"gameState":[{"hash":"round-0001","type":"debit","result":{"winAmount":0},"processedOn":"2023-01-26T11:28:22.126Z"}]}',
  responseHeaders: {
    'x-response-id': 'e628b84c-6df4-45d1-9561-d7653e144a3a',
    'x-h-error-id': '0',
    'x-h-repeatcount': '0',
    'x-response-status': 'ok',
    'x-request-id': 'ec8a82e6ce0e4aa79095fe4119756a54'
  }
}

POST V2_API_ENDPOINT/endGameRound (mandatory)

API reference: /endGameRound

This call ends an open gameround. It collects any open winnings.

request:         V2_EndGameRoundRequestBody

response: V2_GameAPIReply

Example

{
  url: '/gameapi/v2/endGameRound',
  method: 'POST',
  body: '{"token":"d182d578-dcce-4850-b091-205c482c0f58","gameRound":"3c2d66db3e5142d1986e210c809f88e4"}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': 'ba8cf3f65d1e4f25aefd42cdc6b1caa6',
    'x-h-auth-sig': 'YuIsLOFtIfSDhKfvoY2DLnc7UxlcRMc8z7XXm9UkGSc='
  },
  response: '{"tokenData":{"operatorId":"000063d0ef40000000000000001b","playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","mode":"REAL","currency":"EUR","currentToken":"d182d578-dcce-4850-b091-205c482c0f58","language":"DE","currencyMultiplier":1,"gameRound":"3c2d66db3e5142d1986e210c809f88e4"},"balance":{"totalBalance":6954,"mode":"REAL","currency":"EUR","balances":[{"type":"real","amount":6954,"currency":"EUR"}]},"amountToCollect":0,"amountCredited":0,"gameRoundInfo":{"hash":"3c2d66db3e5142d1986e210c809f88e4","status":"closed","stake":13,"mode":"REAL","currency":"EUR","game":"efbdc5b0ef8c434cbf11daab2fda0d5d"},"gameState":[{"hash":"3c2d66db3e5142d1986e210c809f88e4","type":"debit","result":{"winAmount":0},"processedOn":"2023-01-26T11:28:26.591Z"}]}',
  responseHeaders: {
    'x-response-id': '7ba96252-1aad-41a0-af34-abc9ff939299',
    'x-h-error-id': '0',
    'x-h-repeatcount': '0',
    'x-response-status': 'ok',
    'x-request-id': '7dd55c93439b474b8523be610c0e05d5'
  }
}

POST V2_API_ENDPOINT/getGameRoundInfo (optional)

API reference: /getGameRoundInfo

This call returns information about a gameround.

request:         V2_GetGameRoundDetailsRequestBody

response: V2_GameAPIReply

Example

{
  url: '/gameapi/v2/getGameRoundInfo',
  method: 'POST',
  body: '{"token":"83020869-abc0-4123-a95e-ee4f5e8e8343","gameRound":"ff85e29cb4414c89a89829c8411dacc2"}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': '4dcef13fa1094f29b720df41e16376fc',
    'x-h-auth-sig': 'zwlF64lg7h71r1qgHPXuILziZsaZxHtH7AZJfrtQvPY='
  },
  response: '{"tokenData":{"operatorId":"000063d0ef40000000000000001b","playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","mode":"REAL","currency":"EUR","currentToken":"83020869-abc0-4123-a95e-ee4f5e8e8343","language":"DE","currencyMultiplier":1,"gameRound":"ff85e29cb4414c89a89829c8411dacc2"},"amountToCollect":77,"gameRoundInfo":{"hash":"ff85e29cb4414c89a89829c8411dacc2","status":"open","stake":100,"mode":"REAL","currency":"EUR","game":"efbdc5b0ef8c434cbf11daab2fda0d5d"},"gameState":[{"hash":"ff85e29cb4414c89a89829c8411dacc2","type":"debit","result":{"winAmount":77},"processedOn":"2023-01-26T11:28:22.810Z"}]}',
  responseHeaders: {
    'x-request-id': '57ad03d0c9f54cd6ab5b81d7895a154d',
    'x-response-id': '400f691553b3490080681432e3fd65c0',
    'x-response-status': 'ok'
  }
}

POST V2_API_ENDPOINT/getGameRoundHistoryInfo (optional)

API reference: /getGameRoundHistoryInfo

This call returns historical information about a gameround.

request:         V2_GetGameRoundDetailsRequestBody

response: V2_GameAPIReply. The response also includes any protectedInfo.

Notes: This call is not available for open gamerounds. Use getGameRoundInfo instead.

POST V2_API_ENDPOINT/voidGameRound (optional)

API reference: /voidGameRound

This call voids a debit for a gameround. The operator receives a doTransactions call with a void operation for the initial debit. This call does not work if the gameround is not open. It also does not work if the operator already processed a credit successfully. In these cases, the call returns an HTTP 400 error with one of these error codes (see Response Codes & Error Codes):

GAMEROUNDNOTFOUND (14): the gameround hash is unknown.
GAMEROUNDNOTACTIVE (13): the gameround exists, but it is no longer open. A repeated void call on the same round also returns this code.
TRANSACTIONSARERETRYING (26): a credit for the gameround was already processed.

Do not send the call again after one of these three errors. The standard retry policy for an HTTP 4xx response applies. Other failures are different. Retry /voidGameRound after an HTTP 5xx response, a timeout, or a network error. A lost void is not a void that went through.

request:         V2_VoidGameRoundRequestBody

response: V2_GameAPIReply,

Example

{
  url: '/gameapi/v2/voidGameRound',
  method: 'POST',
  body: '{"token":"83020869-abc0-4123-a95e-ee4f5e8e8343","gameRound":"ff85e29cb4414c89a89829c8411dacc2"}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': 'b5f00dc745f84da3adcd474da161f759',
    'x-h-auth-sig': '4c4gjIruvm+qHmZO+Jc2eFbdH35sr45xVXNW6pDKUAw='
  },
  response: '{"balance":6902941,"gameRoundInfo":{"hash":"8f105c8a01fc46d7bb45c317c619445a","status":"cancel","stake":13,"mode":"REAL","currency":"EUR","game":"093a992277e14d6bbb1e5ead156f6734","baseStake":13,"currencyMultiplier":1}}',
  responseHeaders: {
    'x-response-id': '23778189-4957-45fe-91f2-704541b11010',
    'x-h-error-id': '0',
    'x-h-repeatcount': '0',
    'x-response-status': 'ok',
    'x-request-id': '90f91efe393f4ca5af621728e11f7227'
  }
}

POST V2_API_ENDPOINT/collectWin (optional)

API reference: /collectWin

This call collects part or all open winnings. It optionally closes the gameround when the call collects all open winnings.

request:         V2_CollectWinRoundRequestBody

response: V2_GameAPIReply

Example

{
  url: '/gameapi/v2/collectWin',
  method: 'POST',
  body: '{"token":"83020869-abc0-4123-a95e-ee4f5e8e8343","gameRound":"ff85e29cb4414c89a89829c8411dacc2","collectInformation":{"currency":"EUR","creditAmount":37}}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': 'b5f00dc745f84da3adcd474da161f759',
    'x-h-auth-sig': '4c4gjIruvm+qHmZO+Jc2eFbdH35sr45xVXNW6pDKUAw='
  },
  response: '{"tokenData":{"operatorId":"000063d0ef40000000000000001b","playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","mode":"REAL","currency":"EUR","currentToken":"83020869-abc0-4123-a95e-ee4f5e8e8343","language":"DE","currencyMultiplier":1,"gameRound":"ff85e29cb4414c89a89829c8411dacc2"},"balance":{"totalBalance":6853,"mode":"REAL","currency":"EUR","balances":[{"type":"real","amount":6853,"currency":"EUR"}]},"amountToCollect":40,"amountCredited":37,"gameRoundInfo":{"hash":"ff85e29cb4414c89a89829c8411dacc2","status":"open","stake":100,"mode":"REAL","currency":"EUR","game":"efbdc5b0ef8c434cbf11daab2fda0d5d"},"gameState":[{"hash":"ff85e29cb4414c89a89829c8411dacc2","type":"debit","result":{"winAmount":77},"processedOn":"2023-01-26T11:28:22.810Z"},{"hash":"9e959481e6c8411f88a0fcdb43e9e55f","type":"credit","result":{},"collected":37,"reason":"collect 0.37 EUR","processedOn":"2023-01-26T11:28:23.260Z"}]}',
  responseHeaders: {
    'x-response-id': '23778189-4957-45fe-91f2-704541b11010',
    'x-h-error-id': '0',
    'x-h-repeatcount': '0',
    'x-response-status': 'ok',
    'x-request-id': '90f91efe393f4ca5af621728e11f7227'
  }
}

POST V2_API_ENDPOINT/addWin (mandatory)

API reference: /addWin

This call adds an uncollected (open) win to an open gameround. Optionally, it can also collect the win amount immediately and close the gameround.

request: V2_AddWinRequestBody

response: V2_GameAPIReply

Example

{
  url: '/gameapi/v2/addWin',
  method: 'POST',
  body: '{"token":"d182d578-dcce-4850-b091-205c482c0f58","gameRound":"ff85e29cb4414c89a89829c8411dacc2","rngResult":{"rngCallId":"69cf2876471845ba8e97f3adbdf1d163","result":"test-uncollected","winAmount":10}}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': '9c6c2a59e2e9468d82214839ecf9c45d',
    'x-h-auth-sig': 'tMWdNcBZf+6SwrB9qm74B/uKhbE5qDotugxrwdssqqM='
  },
  response: '{"tokenData":{"operatorId":"000063d0ef40000000000000001b","playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","mode":"REAL","currency":"EUR","currentToken":"d182d578-dcce-4850-b091-205c482c0f58","language":"DE","currencyMultiplier":1,"gameRound":"ff85e29cb4414c89a89829c8411dacc2"},"amountToCollect":89,"gameState":[{"hash":"ff85e29cb4414c89a89829c8411dacc2","type":"debit","result":{"winAmount":77},"processedOn":"2023-01-26T11:28:22.810Z"},{"hash":"9e959481e6c8411f88a0fcdb43e9e55f","type":"credit","result":{},"collected":37,"reason":"collect 0.37 EUR","processedOn":"2023-01-26T11:28:23.260Z"},{"hash":"7ac21c2772124befbcd5c70500f421a8","type":"wager","result":{"winAmount":60},"amountWagered":21,"processedOn":"2023-01-26T11:28:24.037Z"},{"hash":"cfbbf8f2a6554d1c9738ecd14aabbb8a","type":"genericwin","result":{"winAmount":10},"processedOn":"2023-01-26T11:28:24.647Z"}]}',
  responseHeaders: {
    'x-request-id': '5c022f0582f04763b9751ce0aca1e8d9',
    'x-response-status': 'ok'
  }
}

POST V2_API_ENDPOINT/wagerWin (optional)

API reference: /wagerWin

This call wagers part or all of open winnings. It adds the result as a new open win amount.

request:         V2_WagerWinRoundRequestBody

response: V2_GameAPIReply

Example

{
  url: '/gameapi/v2/wagerWin',
  method: 'POST',
  body: '{"token":"d182d578-dcce-4850-b091-205c482c0f58","gameRound":"ff85e29cb4414c89a89829c8411dacc2","rngResult":{"rngCallId":"c976d024c19e4a76940b7302beb87939","result":"test","winAmount":60},"wagerInformation":{"currency":"EUR","wagerAmount":21}}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': 'b034474af1e242fa8377f6bfa275081e',
    'x-h-auth-sig': 'NTJrcVX3yfgFZdFp9lO7FdSti7UhGbIIsdSJjE3OF/0='
  },
  response: '{"tokenData":{"operatorId":"000063d0ef40000000000000001b","playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","mode":"REAL","currency":"EUR","currentToken":"d182d578-dcce-4850-b091-205c482c0f58","language":"DE","currencyMultiplier":1,"gameRound":"ff85e29cb4414c89a89829c8411dacc2"},"amountCredited":0,"amountToCollect":79,"gameState":[{"hash":"ff85e29cb4414c89a89829c8411dacc2","type":"debit","result":{"winAmount":77},"processedOn":"2023-01-26T11:28:22.810Z"},{"hash":"9e959481e6c8411f88a0fcdb43e9e55f","type":"credit","result":{},"collected":37,"reason":"collect 0.37 EUR","processedOn":"2023-01-26T11:28:23.260Z"},{"hash":"7ac21c2772124befbcd5c70500f421a8","type":"wager","result":{"winAmount":60},"amountWagered":21,"processedOn":"2023-01-26T11:28:24.037Z"}]}',
  responseHeaders: {
    'x-request-id': 'abe54ec392bd47ad8fc142b6e9349380',
    'x-response-status': 'ok'
  }
}

POST V2_API_ENDPOINT/getUncollectedAmount (optional)

API reference: /getUncollectedAmount

This call returns the amount of uncollected (open) winnings.

request:         V2_GetUncollectedAmountRequestBody
response:         V2_GameAPIGetUncollectedAmountReply

Example

{
  url: '/gameapi/v2/getUncollectedAmount',
  method: 'POST',
  body: '{"token":"d182d578-dcce-4850-b091-205c482c0f58","gameRound":"ff85e29cb4414c89a89829c8411dacc2"}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': '9ac31f8269514695b0cf287f3f721843',
    'x-h-auth-sig': '+iT88iL/NZ/QSrN5ovH6Ljr5OwQtFMBtYKGtxvNsklM='
  },
  response: '{"tokenData":{"operatorId":"000063d0ef40000000000000001b","playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","mode":"REAL","currency":"EUR","currentToken":"d182d578-dcce-4850-b091-205c482c0f58","language":"DE","currencyMultiplier":1,"gameRound":"ff85e29cb4414c89a89829c8411dacc2"},"amountToCollect":79}',
  responseHeaders: {
    'x-request-id': '54c06093d0ec405fab2142e0cb770f08',
    'x-response-status': 'ok'
  }
}

POST V2_API_ENDPOINT/addSpinCounterGameState (optional, not needed for RGS-to-RGS)

API reference: /addSpinCounterGameState

This call adds a game request with a counter, for example free spins won. It can also consume a counter, for example when the game plays a free spin. When it consumes a counter, the call checks if the game state is available. This check makes sure the game does not play more free spins than it won.

request:         V2_AddSpinCounterGameStateRequestBody
response:         V2_GameAPIAddSpinCounterGameStateReply

Example

{
  url: '/gameapi/v2/addSpinCounterGameState',
  method: 'POST',
  body: '{"token":"d182d578-dcce-4850-b091-205c482c0f58","gameRound":"ff85e29cb4414c89a89829c8411dacc2","counterType":"customspin","rngResult":{"rngCallId":"937bfc0d50c4493fa47ce7221d9afc12","result":{"awarded":10},"winAmount":0}}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': '869a2d200905426f8e09d1fc15d91418',
    'x-h-auth-sig': 'HnjWEUTdQ56mAph4BFgiGfx6mwq+Lwebz2834nk9T0E='
  },
  response: '{"tokenData":{"operatorId":"000063d0ef40000000000000001b","playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","mode":"REAL","currency":"EUR","currentToken":"d182d578-dcce-4850-b091-205c482c0f58","language":"DE","currencyMultiplier":1,"gameRound":"ff85e29cb4414c89a89829c8411dacc2"},"amountToCollect":89,"spinsAvailable":10,"gameState":[{"hash":"ff85e29cb4414c89a89829c8411dacc2","type":"debit","result":{"winAmount":77},"processedOn":"2023-01-26T11:28:22.810Z"},{"hash":"9e959481e6c8411f88a0fcdb43e9e55f","type":"credit","result":{},"collected":37,"reason":"collect 0.37 EUR","processedOn":"2023-01-26T11:28:23.260Z"},{"hash":"7ac21c2772124befbcd5c70500f421a8","type":"wager","result":{"winAmount":60},"amountWagered":21,"processedOn":"2023-01-26T11:28:24.037Z"},{"hash":"cfbbf8f2a6554d1c9738ecd14aabbb8a","type":"genericwin","result":{"winAmount":10},"processedOn":"2023-01-26T11:28:24.647Z"},{"hash":"8531967219184c98a06cba7a009640b8","type":"genericwin","result":{"winAmount":10},"processedOn":"2023-01-26T11:28:24.806Z"},{"hash":"15171253390246f18d889d9d1c18e893","type":"credit","result":{},"collected":10,"reason":"collect 0.10 EUR","processedOn":"2023-01-26T11:28:24.826Z"},{"hash":"9ac37a5ceb754f78a51645fd8a9a316f","type":"customspin","result":{"winAmount":0},"processedOn":"2023-01-26T11:28:25.227Z"}]}',
  responseHeaders: {
    'x-request-id': 'b3a6057f422942918672b6c627921d17',
    'x-response-status': 'ok'
  }
}

POST/getAvailableSpinCounter (optional, not needed for RGS-to-RGS)

API reference: /getAvailableSpinCounter

This call gets the value of a spin counter. For example, it returns the number of available free spins after an addSpinCountGameState call.

request:         V2_GetAvailableSpinCounterRequestBody
response:         V2_GameAPIGetAvailableSpinCounterReply

Example

{
  url: '/gameapi/v2/getAvailableSpinCounter',
  method: 'POST',
  body: '{"token":"d182d578-dcce-4850-b091-205c482c0f58","gameRound":"ff85e29cb4414c89a89829c8411dacc2","counterType":"customspin"}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': '8e162d3e2081490dbca7db48d84188a2',
    'x-h-auth-sig': 'LZX7T0pRn0ldVtwBfCJ+aBkhL9UfXj6h5S2abngBO2Q='
  },
  response: '{"tokenData":{"operatorId":"000063d0ef40000000000000001b","playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","mode":"REAL","currency":"EUR","currentToken":"d182d578-dcce-4850-b091-205c482c0f58","language":"DE","currencyMultiplier":1,"gameRound":"ff85e29cb4414c89a89829c8411dacc2"},"amountToCollect":104,"spinsAvailable":9}',
  responseHeaders: {
    'x-request-id': '96471d3f90824c4484a288169734bf5e',
    'x-response-status': 'ok'
  }
}

POST V2_API_ENDPOINT/getTokenForGameRound (optional)

API reference: /getTokenForGameRound

This call gets a new token for an open gameround. Use it for janitor or autoclose functions.

Note: This call revokes any existing tokens for the given player, operator, and game. Use this call only in janitor calls.

request:         V2_GetTokenForGameRoundRequestBody
response:         V2_GetTokenForGameRoundReply

Example

{
  url: '/gameapi/v2/getTokenForGameRound',
  method: 'POST',
  body: '{"gameRound":"ff85e29cb4414c89a89829c8411dacc2"}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': 'd5dd1017005d4c3ea9b31301bd7de6c0',
    'x-h-auth-sig': 'JbFPHyWd+EOgn+sCf1/QLK+SeRJuksnoqIze7mz2M4Y='
  },
  response: '{"tokenData":{"operatorId":"000063d0ef40000000000000001b","playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","mode":"REAL","currency":"EUR","currentToken":"d182d578-dcce-4850-b091-205c482c0f58","language":"DE","currencyMultiplier":1,"gameRound":"ff85e29cb4414c89a89829c8411dacc2"}}',
  responseHeaders: {
    'x-request-id': '2c19baca98a4424ab67ffa76bc1d74dc',
    'x-response-status': 'ok'
  }
}

POST V2_API_ENDPOINT/getTokenData(optional)

API reference: /getTokenData

This call gets token data from a given token ID.

request:         V2_GetTokenDataRequestBody

response: V2_GetTokenDataReply

Example

{
  url: '/gameapi/v2/getTokenData',
  method: 'POST',
  body: '{"token":"cfa822f6-4f53-4ecb-a6f9-647788a6fcd5"}',
  headers: {
    'x-h-auth-id': '000063ea2b200000000000000029',
    'x-h-timestamp': '2023-02-13T14:30:41.130Z',
    'x-request-id': '96317c437f264b3ba2fcd4bf68e8172f',
    'x-h-auth-sig': 'Pb0TjKXo9aAgongzqvAV+C3mz7L2qPspvjhz7y8riCI='
  },
  response: '{"tokenData":{"operatorId":"000063ea2b200000000000000029","playerId":"cd4def34682447ab9b5684340bf25cfe","gameId":"b42a6a2e13554d9cb5c1da72fcb22b8b","mode":"REAL","currency":"EUR","currentToken":"cfa822f6-4f53-4ecb-a6f9-647788a6fcd5","language":"DE","currencyMultiplier":1,"gameRound":"eb6320faf7ac4cdc85ce6f0043573f2f"}}',
  responseHeaders: {
    'x-request-id': 'b6f46c69b7a1454ab2075b67fa220265',
    'x-response-status': 'ok'
  }
}

POST V2_API_ENDPOINT/getPlayerData (optional)

API reference: /getPlayerData

This call reads the data that /setPlayerData stored for one player in one game. The RGS keeps the data in its database. The data stays available after the session ends. Use it for a game state that must survive a session, for example a collection counter or a progress value.

The request carries only the token. The RGS reads the player, the game and the mode (REAL or DEMO) from the token. A game cannot read the data of another player or of another game.

currency and stake filter the result. The RGS applies a filter only for a value that is present and not zero. stake: 0 does not filter. An empty currency does not filter. Omit both values to get every entry of that player in that game and mode.

The RGS does not return an entry whose expires is in the past. The entry stays in the database until a clean-up deletes it. Treat an expired entry as gone.

request:         V2_GetPlayerDataRequestBody
response:         V2_GetPlayerDataReply

Errors: an invalid token or an expired token gives HTTP 400 with error 1008 SESSIONINVALID.

Example

{
  url: '/gameapi/v2/getPlayerData',
  method: 'POST',
  body: '{"token":"d182d578-dcce-4850-b091-205c482c0f58"}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2026-09-17T11:28:21.509Z',
    'x-request-id': '7c1f3a2b58f24d0b9a1d0c5e3f47ab19',
    'x-h-auth-sig': 'QvH3s0Yq5nT1bVwCfJ+aBkhL9UfXj6h5S2abngBO2Q='
  },
  response: '{"data":[{"playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","data":{"played":0}},{"playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","data":{"collected":1},"stake":100,"expires":"2026-09-17T12:00:00.000Z"}]}',
  responseHeaders: {
    'x-request-id': '2f58a9c0d4b74e7ea6f1c2d38b90e451',
    'x-response-status': 'ok'
  }
}

To read only the entry of one stake level, send that stake:

{
  url: '/gameapi/v2/getPlayerData',
  method: 'POST',
  body: '{"token":"d182d578-dcce-4850-b091-205c482c0f58","stake":100}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2026-09-17T11:28:25.104Z',
    'x-request-id': 'b0d4e61c8a7f4f2d91c3ab5e7d02f846',
    'x-h-auth-sig': 'k9Rp2XcA7mYs4Lt0QvB+aBkhL9UfXj6h5S2abngBO2Q='
  },
  response: '{"data":[{"playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","data":{"collected":1},"stake":100,"expires":"2026-09-17T12:00:00.000Z"}]}',
  responseHeaders: {
    'x-request-id': 'd7c9013ea4bf42d8b5e6f0a2c1938d7b',
    'x-response-status': 'ok'
  }
}

POST V2_API_ENDPOINT/setPlayerData (optional)

API reference: /setPlayerData

This call stores data for one player in one game. The RGS keeps the data in its database. The data stays available after the session ends. Read it back with /getPlayerData.

The request carries only the token. The RGS reads the player, the game and the mode (REAL or DEMO) from the token. A game cannot store data for another player or for another game.

Note: The payload to store is data.data. The outer data object also holds currency, stake and expires. Its published type is Omit<V2_PlayerData, 'playerId' | 'gameId' | 'gameMode'>, so it is a V2_PlayerData without playerId and gameId.

data.data is unknown in the published type, so the entry holds any JSON value. Most games store an object.

The RGS keys an entry on the player, the game, currency, stake and the mode. The call replaces the entry with that key. It is an upsert, not an append. Use currency and stake to hold several independent entries for one player in one game, for example one entry for each stake level. Omit both values to hold one entry for each player.

expires is optional. It is a timestamp in ISO 8601 format, in UTC. An entry with no expires never expires.

In DEMO mode the RGS limits the lifetime of an entry. The limit is MAXLIFETIME_PLAYERDATA_INDEMOGAMES_SECONDS, which is 86400 seconds (24 hours) by default. The RGS sets expires to that limit when the request sends none. The RGS lowers a later expires to that limit. REAL mode has no limit.

The reply is a read-back after the write. It holds the entries that match the currency and the stake of the request.

request:         V2_SetPlayerDataRequestBody
response:         V2_SetPlayerDataReply

Errors:

An invalid token or an expired token gives HTTP 400 with error 1008 SESSIONINVALID.
A request without data.data gives HTTP 400 with error 19 INVALIDPARAMETER and the message cannot store tokendata as no data present.

Example

{
  url: '/gameapi/v2/setPlayerData',
  method: 'POST',
  body: '{"token":"d182d578-dcce-4850-b091-205c482c0f58","data":{"stake":100,"data":{"collected":1},"expires":"2026-09-17T12:00:00.000Z"}}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2026-09-17T11:28:19.771Z',
    'x-request-id': '3a90c5e7b21d43f0aa6c81d5479e2f3b',
    'x-h-auth-sig': 'T4mZ8qLxRv2Ns1CbPw0+aBkhL9UfXj6h5S2abngBO2Q='
  },
  response: '{"data":[{"playerId":"c9c5385f9ee449459fcd6ff39ac53911","gameId":"efbdc5b0ef8c434cbf11daab2fda0d5d","data":{"collected":1},"stake":100,"expires":"2026-09-17T12:00:00.000Z"}]}',
  responseHeaders: {
    'x-request-id': '58b1f7a0c93d4e26bb0f2d47e81ac635',
    'x-response-status': 'ok'
  }
}

POST V2_API_ENDPOINT/getLastGameRounds (optional)

API reference: /getLastGameRounds

This call gets a list of recently closed games.

request: V2_GetLastGamesRequestBody

response: V2_GetLastGamesReply

Example

{
  url: '/gameapi/v2/getLastGameRounds',
  method: 'POST',
  body: '{"token":"d182d578-dcce-4850-b091-205c482c0f58"}',
  headers: {
    'x-h-auth-id': '000063d0ef40000000000000001b',
    'x-h-timestamp': '2023-01-26T11:28:21.509Z',
    'x-request-id': 'cf64d9f4cb964a14a6c464b74512cf73',
    'x-h-auth-sig': 'b8QF77vhsf7rCp7hNZnHxUV4gBeQ0Nz/rYAdq2SwXYA='
  },
  response: '{"gameRoundList":[{"id":"a016d46dd75b4725baf06d0ef0fdbe7f","status":"closed","timestamp":"2023-01-26T11:28:28.953Z","bet":13,"won":10,"currency":"EUR","gameSpecificDetails":{"result":{"result":"test","rngCallId":"830e8c88405a48b2af5b33f89745084e","winAmount":10}}},{"id":"ed404d20c18b4821880e465b0e41c570","status":"closed","timestamp":"2023-01-26T11:28:28.769Z","bet":13,"won":10,"currency":"EUR","gameSpecificDetails":{"result":{"result":"test","rngCallId":"28732aa1acd3472fa743ef8e6acc36ef","winAmount":10}}}]}',
  responseHeaders: {
    'x-response-id': '25b52b253ab543239d8490d32b6a63cd',
    'x-response-status': 'ok'
  }
}

POST V2_API_ENDPOINT/getRandomResult (conditional)

API reference: /getRandomResult

This call gets random integers or doubles within a given range from the hizi.io certified RNG.

When is this required? This call is required only when the game logic runs inside the hizi.io RGS. In this case, the game logic must obtain its randomness from hizi.io for compliance. This applies to direct game engine integrations hosted by hizi.io. It also applies to a partner RGS hosted within the hizi.io RGS ("RGS inception").
A classic RGS-to-RGS integration does not call this endpoint. In the typical RGS-to-RGS case, your RGS runs on your own infrastructure and uses your own certified (for example, provably-fair) RNG. Keep using your own RNG. Pass its results in the rngResult fields of /startGameRound, /addWin, and other calls. You run your own certification on your own infrastructure. hizi.io is not involved in your certification. hizi.io provides no certification suite for it. No part of hizi.io expects /getRandomResult calls from such integrations.

request:         V2_GetRandomResultRequestBody

response: V2_GameAPIRngReply

Example

{
  url: '/gameapi/v2/getRandomResult',
  method: 'POST',
  body: '{"token":"123162d0-315d-474b-930c-7e43625c2ae3","rngEndPoint":"getDoubles","rngPayload":{"min":1,"max":10,"count":2}}',
  headers: {
    'x-h-auth-id': '000063d0ef400000000000000029',
    'x-h-timestamp': '2023-01-26T11:43:58.115Z',
    'x-request-id': '7f0fab897ea745d1a82b79934ee93b6d',
    'x-h-auth-sig': 'kLiIcxtblFF2+c9g5zUmKrNoOZFpqeO7ODXZGUklVSg='
  },
  response: '{"values":[3.068702629156329,9.509780327419449],"tokenData":{"operatorId":"000063d0ef400000000000000029","playerId":"9f1cfa5dfcbd4946817675ecbccc26c5","gameId":"f1252f6014084e1cbf5bb1982f911e0c","mode":"REAL","currency":"EUR","currentToken":"123162d0-315d-474b-930c-7e43625c2ae3","language":"DE","currencyMultiplier":1}}',
  responseHeaders: {
    'x-response-id': '0c83abf945a14e78ab8babaa4b96005b',
    'x-response-status': 'ok',
    'x-request-id': 'c95a958b11614905b932aa7dce9d695d'
  }
}

GET V2_API_ENDPOINT/getOperatorSettings (optional)

API reference: /getOperatorSettings

This call gets operator-specific settings.

request:         V2_GetOperatorSettingsQuery

response: V2_GameSettings

Example

 {
  url: '/gameapi/v2/getOperatorSettings?game=f1252f6014084e1cbf5bb1982f911e0c-unk&operator=000063d0ef400000000000000029-unk&currency=EUR',
  method: 'GET',
  body: undefined,
  headers: {
    'x-h-auth-id': '000063d0ef400000000000000029',
    'x-h-timestamp': '2023-01-26T11:43:58.115Z',
    'x-request-id': 'e67161f5bc354717871b021144945154',
    'x-h-auth-sig': 'D3p/3TU6q3DYGZ56TtFXVDog5UU4uVRw38FrMVd1ru4='
  },
  response: '{"autoplayEnabled":true,"autoplayLossLimitRequired":false,"displayCoins":true,"displayJackpotOdds":false,"displayRTP":false,"displayXRTP":false,"forceOrientation":0,"gambleEnabled":true,"historyURL":"","homeURL":"","loadMsg":"","maxExposure":25000000,"multipleInstancesAllowed":false,"rcDisplayWinLoss":false,"rcEnabled":false,"stopEnabled":true,"topupURL":"","turboEnabled":true,"homeEnabled":true,"dynamicMinSpinTime":false,"redirectTarget":"top","packageBuyEnabled":true}',
  responseHeaders: {
    'x-response-id': '475c54c307174c2a98d86b190feebb09',
    'x-response-status': 'ok'
  }
}

POST V2_API_ENDPOINT/getBalance (optional)

API reference: /getBalance

This call gets the player's balance.

request: V2_GetTokenDataRequestBody

response: GameAPIBalanceReply

Example

{
  url: '/gameapi/v2/getBalance',
  method: 'POST',
  body: '{"token":"cfa822f6-4f53-4ecb-a6f9-647788a6fcd5"}',
  headers: {
    'x-h-auth-id': '000063ea2b200000000000000029',
    'x-h-timestamp': '2023-02-13T14:30:41.130Z',
    'x-request-id': '96317c437f264b3ba2fcd4bf68e8172f',
    'x-h-auth-sig': 'Pb0TjKXo9aAgongzqvAV+C3mz7L2qPspvjhz7y8riCI='
  },
  response: '{"totalBalance":6816,"mode":"REAL","currency":"EUR","balances":[{"type":"real","amount":6816,"currency":"EUR"}]}',
  responseHeaders: {
    'x-request-id': 'b6f46c69b7a1454ab2075b67fa220265',
    'x-response-status': 'ok'
  }

Calls provided by API V2 ​

Introduction ​

Game frontend calls ​

GET V2_API_ENDPOINT**/status (optional)** ​

GET V2_API_ENDPOINT**/connect (mandatory to use)** ​

GET V2_API_ENDPOINT**/reconnect (optional)** ​

GET V2_API_ENDPOINT**/disconnect (optional)** ​

Game engine / RGS calls ​

Signing RGS requests ​

Mandatory request headers ​

Response headers ​

POST V2_API_ENDPOINT**/testPing (optional)** ​

POST V2_API_ENDPOINT**/startGameRound (mandatory)** ​

POST V2_API_ENDPOINT**/startGameOrAddBet (optional)** ​

How the call chooses between start and add ​

How to send more than one bet in one gameround ​

Limits ​

POST V2_API_ENDPOINT**/endGameRound (mandatory)** ​

POST V2_API_ENDPOINT**/getGameRoundInfo (optional)** ​

POST V2_API_ENDPOINT**/getGameRoundHistoryInfo (optional)** ​

POST V2_API_ENDPOINT**/voidGameRound (optional)** ​

POST V2_API_ENDPOINT**/collectWin (optional)** ​

POST V2_API_ENDPOINT**/addWin (mandatory)** ​

POST V2_API_ENDPOINT**/wagerWin (optional)** ​

POST V2_API_ENDPOINT**/getUncollectedAmount (optional)** ​

POST V2_API_ENDPOINT**/addSpinCounterGameState (optional**, not needed for RGS-to-RGS**)** ​

POST**/getAvailableSpinCounter (optional**, not needed for RGS-to-RGS**)** ​

POST V2_API_ENDPOINT**/getTokenForGameRound (optional)** ​

POST V2_API_ENDPOINT**/getTokenData(optional)** ​

POST V2_API_ENDPOINT**/getPlayerData (optional)** ​

POST V2_API_ENDPOINT**/setPlayerData (optional)** ​

POST V2_API_ENDPOINT**/getLastGameRounds (optional)** ​

POST V2_API_ENDPOINT**/getRandomResult (conditional)** ​

GET V2_API_ENDPOINT**/getOperatorSettings (optional)** ​

POST V2_API_ENDPOINT**/getBalance (optional)** ​

Example ​

Calls provided by API V2

Introduction

Game frontend calls

GET V2_API_ENDPOINT/status (optional)

GET V2_API_ENDPOINT/connect (mandatory to use)

GET V2_API_ENDPOINT/reconnect (optional)

GET V2_API_ENDPOINT/disconnect (optional)

Game engine / RGS calls

Signing RGS requests

Mandatory request headers

Response headers

POST V2_API_ENDPOINT/testPing (optional)

POST V2_API_ENDPOINT/startGameRound (mandatory)

POST V2_API_ENDPOINT/startGameOrAddBet (optional)

How the call chooses between start and add

How to send more than one bet in one gameround

Limits

POST V2_API_ENDPOINT/endGameRound (mandatory)

POST V2_API_ENDPOINT/getGameRoundInfo (optional)

POST V2_API_ENDPOINT/getGameRoundHistoryInfo (optional)

POST V2_API_ENDPOINT/voidGameRound (optional)

POST V2_API_ENDPOINT/collectWin (optional)

POST V2_API_ENDPOINT/addWin (mandatory)

POST V2_API_ENDPOINT/wagerWin (optional)

POST V2_API_ENDPOINT/getUncollectedAmount (optional)

POST V2_API_ENDPOINT/addSpinCounterGameState (optional, not needed for RGS-to-RGS)

POST/getAvailableSpinCounter (optional, not needed for RGS-to-RGS)

POST V2_API_ENDPOINT/getTokenForGameRound (optional)

POST V2_API_ENDPOINT/getTokenData(optional)

POST V2_API_ENDPOINT/getPlayerData (optional)

POST V2_API_ENDPOINT/setPlayerData (optional)

POST V2_API_ENDPOINT/getLastGameRounds (optional)

POST V2_API_ENDPOINT/getRandomResult (conditional)

GET V2_API_ENDPOINT/getOperatorSettings (optional)

POST V2_API_ENDPOINT/getBalance (optional)

Example