hizi docs

Appearance

Game Studio API Reference ​

This page documents every call, callback, and data structure of the Game Studio API (RGS / Game Studio API V2). VitePress renders it from the OpenAPI 3.0 specification. Each operation has its own page, with its parameters, request and response schemas, examples, and code samples.

The prose documentation under Game Studio API is the normative source. If the two disagree, the notes in the spec and the prose take priority.

v1.21.0

hizi.io Game Studio API (RGS / Game Studio API V2)​

Download OpenAPI Document

The interface game engines and third-party RGS use to integrate with the
hizi.io RGS — game launch, round lifecycle, certified RNG and freeplays.

Machine-readable description of the RGS / Game Studio API V2 — the
interface a game engine or a third-party RGS uses to integrate with the
hizi.io Remote Gaming Server. It is generated from, and kept faithful to,
the hand-written documentation under /game-studio-api/.

This is not the Operator API. The Operator API describes the
operator ⇄ hizi.io wallet/session protocol (doTransactions,
getGameURL, …) and is specified separately. The two protocols share the
X-H-AUTH-* signing header family and the response/error-code catalogue
(see Response Codes & Error Codes), but
their endpoints and payloads are different.

Who this API is for

Classic RGS-to-RGS (typical) hizi.io-hosted engine
Where game logic runs your own infrastructure inside the hizi.io RGS
Transport HTTP/2 RabbitMQ or HTTP/2
RNG your own certified RNG, passed in rngResult hizi.io certified RNG via POST /getRandomResult
Certification entirely yours; expose hashes via GET /certifiedfiles built and certified inside the hizi.io stack

Two transports, one payload set

The API can be consumed in two ways:

  1. RabbitMQ — subscribe to the hizi.io message broker and send RPC
    messages. Recommended by hizi.io (lower resource usage, better
    scalability and failure tolerance). The message payloads and the
    X-H-* header names are the same as below; they travel as queue
    message headers instead of HTTP headers, so this document describes
    them as HTTP.
  2. RESTful HTTP/2 — listen on an HTTP port for the calls under the
    calls-to-implement tag and POST/GET the calls under the other
    tags to the hizi.io RGS. This variant must be used for an
    RGS-to-RGS integration where the third-party RGS is not hosted by
    hizi.io.

Directions of traffic

  • Everything served from the V2_API_ENDPOINT server is provided by
    hizi.io     and called by the game frontend, the game engine or the
    third-party RGS.
  • Everything tagged calls-to-implement is served from the
    backendQueue server, i.e. it is implemented by you and called by
    hizi.io (the janitor, the operator support proxy, monitoring and
    certification bodies).

Amounts and currency

All amounts in requests and responses are integers in minor units
(1/100 of the currency). currencyMultiplier is an FX-style factor
applied once, by the game, when building the stake ladder in
getGameConfiguration; it is not applied a second time to transaction
amounts. debitInformation.debitAmount is already in player-currency
minor units and should equal the chosen stake (or the feature price on a
buy-feature round).

Idempotency and retries

All calls should be idempotent on the hashes passed. Note the documented
limit: V2 calls are only idempotent on gameround / transaction
(gamestate) hashes while the gameround is still open — once the round is
closed a repeated call is treated as a call on a non-open gameround and
fails.

On a lost response, query before retrying:

  1. Do not immediately retry the original call.
  2. Query the round with POST /getGameRoundInfo.
  3. If status is closed and the transactions match expectation, treat
    it as success. If status is open with partial processing (debit
    done, win not credited), close the round with POST /endGameRound.
  4. Only retry the original call on 5xx. Never retry 4xx (e.g. error
    code 15 GAMEROUNDNOTSTARTED means the operation cannot proceed).

See Handling Lost Responses and Retry Scenarios.

Error signalling

An HTTP 200 normally means success. If the X-H-ERROR-ID response
header is present on a 200, the call must be treated as failed as if a
400 had been received. X-H-ERROR-MSG may carry a textual
description. The numeric codes are the shared catalogue documented in
Response Codes & Error Codes and modelled
here as ErrorCodeId.

Round lifecycle

OpenAPI cannot express call ordering; see the round-lifecycle tag
description for the state machine the round calls form.

Source documents

Overview ·
Basics ·
Game Launch ·
Game configuration ·
Calls provided by API V2 ·
Calls to be implemented by games ·
Data structures ·
Freeplays ·
Lost responses & retries ·
Signing appendix

Contact​

hizi.io customer support

Servers​

{V2_API_ENDPOINT}The hizi.io RGS API V2 endpoint. The concrete host is supplied by hizi.io per environment; the path component is `/gameapi/v2` (the `V2_API_QUEUE` setting for RPC integrations). The value below is the sample endpoint used throughout the documentation examples.
{backendQueue}Your own game engine / third-party RGS base URL, configured in the hizi.io backoffice as the game's `backendQueue`. Only the operations tagged `calls-to-implement` are served from here.

Operations ​

game-launch

round-lifecycle

session-and-lookups

certified-rng

freeplays

calls-to-implement