v.1.0.0

Change log

Version	Changes
v1.0.0	- Initial TransferWallet release

Introduction

This API provides Transfer Wallet integration between Gamzix and your Casino. The API consists of four parts: Games API, Wallet API (including bonuses), and optional Free Rounds API and Rounds Report.

Unlike the Seamless integration, where Gamzix calls the Casino wallet on every bet and win, in the Transfer Wallet model Gamzix holds the player's game balance. The Casino tops up (deposit) and cashes out (withdraw) that balance through the Wallet API. During gameplay all bets, wins and refunds are settled by Gamzix internally against the held balance — no requests are sent to the Casino during a round.

A wallet is created automatically with a zero balance the first time a player is referenced. Each player uses a single game currency, fixed on the first game launch — launching a game for the same player with a different currency is rejected. The Wallet API itself does not enforce this, so funds deposited in a second currency cannot be played; the Casino must always use one currency per player.

OpenAPI Documentation

OpenAPI documentation is available at: https://api.gamzix.com/api/v1/transferwallet

The documentation includes endpoints for the Games API, Wallet API, Free Rounds API, and Rounds Report, as well as the ability to generate signatures for POST requests.

Game round flow

The Casino only interacts with this API to move money in and out of the player's balance and to read state. Bets and wins happen entirely inside Gamzix and never reach the Casino:

Deposit — the Casino funds the player's balance (POST /wallet/deposit).
Launch — the player opens a game; Gamzix reads the balance internally (GET /init).
Bet / Win — during the round Gamzix debits and credits the held balance internally. The Casino receives no callbacks.
Withdraw — the Casino cashes the player's balance out (POST /wallet/withdraw).
Balance / History — the Casino may read the balance (GET /wallet/balance) or the transaction list (GET /wallet/transactions) at any time.

Required data for integration

Given by Gamzix

Name	Description	Example
gamzix_url	Transfer Wallet URL	https://api.gamzix.com/transfer-wallet/:casino_id/api
password	Message signature key	GoF4GdKcN65e5Ni11dVf7V6m

Given by Casino

Name	Description	Example
casino_id	Casino external ID	casino-123
casino_ip[]	Casino IP white list	127.0.0.1, 192.168.0.1

The casino_id is part of gamzix_url (.../transfer-wallet/:casino_id/api). It identifies the Casino on every request, so it is not repeated in request bodies or query strings.

Communication format

Casino request URL to Gamzix starts with [gamzix_url]
All requests are GET or POST
All message bodies are JSON with Content-Type: application/json
POST requests must be signed for authentication (x-signature header)
DateTime format is ISO-8601 extended format (YYYY-MM-DDThh:mm:ss.sssZ)
All currencies are ISO-4217 — 3 uppercase letters: USD, EUR, etc.
All languages are ISO-639-1 — 2 lowercase letters: en, es, it, etc.
All requests are sent using HTTPS.
If a request is unsuccessful (HTTP status other than 200/201) the body contains an error description (see Response status codes).

Money format

Amounts and balances are transferred as integer values in the currency's minor units, encoded as strings (e.g. "1000" = 10.00 for a 2-decimal currency). The Casino must convert values conforming to the precision of the currency.

Currency	Precision
USD	2
EUR	2

Response status codes

A successful request returns HTTP status 200 or 201.
Errors come from two layers and have two different shapes:
- Authentication / Games API / Free Rounds / Rounds Report errors (raised before or by the Games layer) use the v13-style envelope with status, result and error fields.
- Wallet API errors (deposit / withdraw / balance / transactions) are returned by the wallet service and use the flat { statusCode, code, message, requestId } shape.

Authentication / Games API / Free Rounds / Rounds Report errors

These are the statuses this layer actually returns:

Code	`result` string	When
400	Bad Request	Invalid request parameters
401	Invalid Signature	`x-signature` missing or invalid
404	Page not found	Unknown casino / route
422	Unprocessable Entity	Unexpected value error
430	Freerounds not found	Free Round promotion does not exist
500	Unexpected Error	Server error

Error shape:

{
  "ts": 1723466400000,
  "status": 401,
  "result": "Invalid Signature",
  "message": "Signature invalid",
  "error": "Signature invalid"
}

Wallet API errors

These are the statuses the wallet service (and its proxy) actually return:

Code	`code` string	When
400	BAD_REQUEST	Invalid / missing / extra body or query parameter
400	DB_CHECK_VIOLATION	Value rejected by a database constraint
402	HTTP_ERROR	Insufficient funds (on withdraw)
404	DB_FOREIGN_KEY_VIOLATION	Referenced entity not found
409	DB_UNIQUE_VIOLATION	Duplicate / conflicting transaction
500	INTERNAL_SERVER_ERROR	Unexpected server error
502	BAD_GATEWAY	Wallet service temporarily unavailable

Note: a Wallet API request with a missing or invalid signature fails at the authentication layer and therefore returns the v13-style error shape above (status 401), not the flat shape.

Error shape:

{
  "statusCode": 402,
  "code": "HTTP_ERROR",
  "message": "Insufficient funds",
  "requestId": "1f5b0c2e-8a3d-4e1a-9c7b-2f6d0a1b3c4d"
}

Authentication

It is highly recommended to authenticate messages at the prod stage. The x-signature header must be included in every POST request.

x-signature is a hashed SHA-512 string = payload + ":" + password (given by Gamzix), where payload is:

for POST requests — the JSON string of the request body;
for signed GET requests (/wallet/balance, /wallet/transactions) — the JSON string of the query parameters object.

Signatures are required on all POST requests (except /round/info) and on the signed GET requests /wallet/balance and /wallet/transactions.

If the message has an invalid signature, an error message is returned:

{
  "ts": 1723466400000,
  "status": 401,
  "result": "Invalid Signature",
  "message": "Signature invalid",
  "error": "Signature invalid"
}

The following functions might be used to sign messages:

NodeJS

const crypto = require("crypto");
/**
 * @param { string } payload
 * @param { string } password
 */
const sign = (payload, password) =>
  crypto
    .createHash("sha512")
    .update(payload + ":" + password)
    .digest("hex");

PHP

function sign(string $payload, string $password): string {
  return hash('sha512', $payload.':'.$password);
}

Examples

// POST /wallet/deposit — sign the body
const body = { pid: "player-456", gid: 1045, tid: "550e8400-...", currency: "USD", amount: "1000" };
const signature = sign(JSON.stringify(body), password);

// GET /wallet/balance?pid=player-456&currency=USD — sign the query object
const query = { pid: "player-456", currency: "USD" };
const signature = sign(JSON.stringify(query), password);

Idempotency

All Wallet API transaction requests (deposit, withdraw) are idempotent. Each request carries a tid (transaction UUID). A repeated request with the same tid for the same Casino is not processed twice — the stored result of the original transaction is returned unchanged.

Games Api

The Games API returns responses wrapped in a { status, ts, result } envelope.

GET /languages

Method: GET

URI: [gamzix_url]/languages

Description: Returns the list of languages available for the Casino

Response Type:

type Result = string[];

Response:

{
  "status": 200,
  "ts": 1234567890,
  "result": ["bg", "en", "cs", "es", "go", "it"]
}

GET /currencies

Method: GET

URI: [gamzix_url]/currencies

Description: Returns the list of currencies available for the Casino

Response Type:

type Result = string[];

Response:

{
  "status": 200,
  "ts": 1234567890,
  "result": ["EUR", "LKR", "MGA", "UAH", "USD", "uBTC"]
}

GET /games

Method: GET

URI: [gamzix_url]/games

Description: Returns the list of games available for the Casino

Response Type:

type Result = {
  id: number;
  name: string;
  logo: string; // Link to game logo image
  order: number | null;
  tags?: string[] | null;
}[];

Response:

{
  "status": 200,
  "ts": 1234567890,
  "result": [
    {
      "id": 1045,
      "name": "Sunny Coin 2",
      "logo": "https://.../g1045.jpg",
      "order": 2,
      "tags": ["fruits", "snow"]
    },
    {
      "id": 2001,
      "name": "Royal Hot v2",
      "logo": "https://.../g2001.jpg",
      "order": 1
    }
  ]
}

GET /freerounds/info

Method: GET

URI: [gamzix_url]/freerounds/info

Description: Returns information about all Free Rounds settings available for the Casino.

Response Type:

type Result = {
  offers: {
    currency: string;
    game_id: string;
    game_name: string;
    bets: number[]; // list of free round bets available for the game and currency
  }[];
};

Response:

{
  "status": 200,
  "ts": 1234567890,
  "result": {
    "offers": [
      {
        "currency": "UAH",
        "game_id": "1045",
        "game_name": "Sunny Coin 2",
        "bets": [200, 500, 1000]
      },
      {
        "currency": "USD",
        "game_id": "2001",
        "game_name": "Royal Hot v2",
        "bets": [100, 200, 1000]
      }
    ]
  }
}

GET /init

Method: GET

Params:

type Params = {
  gid: number;         // Gamzix Game ID
  pid: string;         // Casino Player ID
  currency: string;    // Casino Player currency
  home?: string;       // Button HOME moves the player to this URL
  demo?: number;       // Non-zero value means the player is the demo
  lang?: string;       // Casino Player language
  client?: string;     // Html Client type. "desktop" or "mobile"
  token?: string;      // Game launch token
  countryCode?: string; // Casino Player country code (KZ, TR, etc.)
};

URI: [gamzix_url]/init?gid=[ your gid ]&pid=[ your pid ]&currency=[ your currency ]&home=/&demo=0&lang=en&client=desktop&token=[ your token ]

Description: Returns the URL of the chosen game.

The Casino must forward the Player into an iframe with the returned URL. Make sure the iframe has an "allowfullscreen" attribute.

Response Type:

type Result = string;

Response:

{
  "status": 200,
  "ts": 1234567890,
  "result": "https://cdn-v2.gamzix.com/3x3-hold-the-spin/v1.9.2?host=sapp.gamzix.com&port=443&lang=en&sid=avkdboqlz"
}

Wallet Api

The Wallet API is used by the Casino to move money in and out of the player's balance and to read state. It returns flat JSON responses (no { status, result } envelope).

POST /wallet/deposit

Method: POST

URI: [gamzix_url]/wallet/deposit

Description: Deposits money into the player's transfer wallet. Returns the player's balance after the transaction.

Body:

type Body = {
  pid: string;      // Casino Player ID
  gid: number;      // Gamzix Game ID
  tid: string;      // Transaction ID (UUID)
  currency: string; // Player currency (ISO-4217)
  amount: string;   // Deposit amount, positive integer as string
};

Response Type:

type Result = {
  balance: string;        // Player balance after transaction
  transaction_id: string; // Processed transaction ID
};

Response:

{
  "balance": "8750",
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000"
}

POST /wallet/withdraw

Method: POST

URI: [gamzix_url]/wallet/withdraw

Description: Withdraws money from the player's transfer wallet. Returns the player's balance after the transaction. If the amount exceeds the balance, an Insufficient funds (402) error is returned and no money is moved.

Body:

type Body = {
  pid: string;      // Casino Player ID
  gid: number;      // Gamzix Game ID
  tid: string;      // Transaction ID (UUID)
  currency: string; // Player currency (ISO-4217)
  amount: string;   // Withdrawal amount, positive integer as string
};

Response Type:

type Result = {
  balance: string;        // Player balance after transaction
  transaction_id: string; // Processed transaction ID
};

Response:

{
  "balance": "7750",
  "transaction_id": "660e8400-e29b-41d4-a716-446655440000"
}

Insufficient funds response:

{
  "statusCode": 402,
  "code": "HTTP_ERROR",
  "message": "Insufficient funds",
  "requestId": "1f5b0c2e-8a3d-4e1a-9c7b-2f6d0a1b3c4d"
}

GET /wallet/balance

Method: GET

Params:

type Params = {
  pid: string;      // Casino Player ID
  currency: string; // Player currency (ISO-4217)
};

URI: [gamzix_url]/wallet/balance?pid=[ pid ]&currency=[ currency ]

Description: Returns the player's current balance. The wallet is created with a zero balance if it does not yet exist.

Response Type:

type Result = {
  balance: string;  // Player balance
  currency: string; // Player currency
};

Response:

{
  "balance": "8750",
  "currency": "USD"
}

GET /wallet/transactions

Method: GET

Params:

type Params = {
  pid: string;        // Casino Player ID
  date_from?: string; // ISO-8601 datetime, must include time (date-only rejected)
  date_to?: string;   // ISO-8601 datetime, must include time (date-only rejected)
  page?: number;      // Page number, starts at 1 (default 1)
  per_page?: number;  // Page size (default 25, max 100)
};

URI: [gamzix_url]/wallet/transactions?pid=[ pid ]

Description: Returns a paginated list of wallet transactions for the player, optionally filtered by a date range.

Response Type:

type Result = {
  total: number;       // Total transactions matching the filter
  page: number;        // Current page
  per_page: number;    // Page size
  total_pages: number; // Total number of pages
  from: number;        // Index of the first item on the page
  to: number;          // Index of the last item on the page
  data: {
    player_external_id: string;
    casino_external_id: string;
    game_external_id: number | null;
    round_external_id: string | null;
    currency_code: string;
    internal_id: string;   // Gamzix internal transaction ID
    external_id: string;   // Transaction ID provided on the request (tid)
    balance_before: string;
    balance_after: string;
    type: "casino_deposit" | "casino_withdraw" | "bet" | "win";
    amount: string;
    created_at: string;    // ISO-8601 datetime
    updated_at: string;    // ISO-8601 datetime
  }[];
};

Response:

{
  "total": 125,
  "page": 1,
  "per_page": 25,
  "total_pages": 5,
  "from": 1,
  "to": 25,
  "data": [
    {
      "player_external_id": "player-456",
      "casino_external_id": "casino-123",
      "game_external_id": 1045,
      "round_external_id": "660e8400-e29b-41d4-a716-446655440000",
      "currency_code": "USD",
      "internal_id": "f839de99-6c08-4f8a-a802-d1d6e6ec9158",
      "external_id": "550e8400-e29b-41d4-a716-446655440000",
      "balance_before": "5000",
      "balance_after": "6000",
      "type": "casino_deposit",
      "amount": "1000",
      "created_at": "2026-03-12T12:15:45.000Z",
      "updated_at": "2026-03-12T12:15:45.000Z"
    }
  ]
}

The transaction type values bet and win are produced by internal game-round settlement; casino_deposit and casino_withdraw correspond to the Casino's own /wallet/deposit and /wallet/withdraw requests.

Free Rounds Api

Free Rounds (FR) API is an optional API.

The Casino using the FR API is able to grant free bets to users. First-time-user bonuses are supported: FR feature functions even if a player has not played Gamzix games yet.

FR settings may have constraints set by Gamzix: games, currencies, bet values or time. The Casino may have several FR settings with its constraints. To provide FR to some players, Casino has to specify which FR settings they are based on.

POST /freerounds/v2/create

Method: POST

Body:

type Body = {
  fr_id: string;              // Gamzix FR ID
  started_at?: string;        // FR allowed from this time (optional)
  finished_at?: string;       // FR allowed to this time (optional)
  gid: string | number[];     // List of Gamzix Game IDs
  bet_amount: number;         // Bet Amount
  rounds: number;             // Amount of FR
  pid: string;                // Casino Player ID
  currency?: string;          // Casino Player currency (optional)
};

* As bet_amount you can set a value from the list of game bets for currency.

URI: [gamzix_url]/freerounds/v2/create

Description: Creates or updates the freerounds settings if exists

Response Type:

type Result = {
  fr_id: string; // Gamzix FR ID
};

Response:

{
  "status": 200,
  "ts": 1234567890,
  "result": {
    "fr_id": "13ec1944-4106-42ae-b410-c634a6a08f19"
  }
}

POST /freerounds/cancel

Method: POST

Body:

type Body = {
  fr_id: string; // Gamzix FR ID
};

URI: [gamzix_url]/freerounds/cancel

Description: Deletes the freerounds settings if exists.

Response:

{
  "status": 200,
  "ts": 1234567890
}

Rounds Report

POST /round/info

Method: POST

Body:

type Body = {
  externalId: string; // Gamzix round ID
};

URI: [gamzix_url]/round/info

Description: Returns information about a specific round.

Response Type:

type Info = {
  bet: number;         // Round bet amount
  win: number;         // Round win amount
  created_at: string;  // Round created date
  closed_at: string;   // Round closed date
  type: string;        // Round type (spin, freeRound, prize)
  currency: string;    // Round currency
};

Response:

{
  "info": {
    "bet": 10,
    "win": 100,
    "created_at": "2024-01-15T14:27:41.202000Z",
    "closed_at": "2024-01-15T14:27:41.278499Z",
    "type": "spin",
    "currency": "EUR"
  },
  "success": true
}

Change log​

Introduction​

OpenAPI Documentation​

Game round flow​

Required data for integration​

Communication format​

Money format​

Response status codes​

Authentication​

Idempotency​

Games Api​

GET /languages​

GET /currencies​

GET /games​

GET /freerounds/info​

GET /init​

Wallet Api​

POST /wallet/deposit​

POST /wallet/withdraw​

GET /wallet/balance​

GET /wallet/transactions​

Free Rounds Api​

POST /freerounds/v2/create​

POST /freerounds/cancel​

Rounds Report​

POST /round/info​

Change log

Introduction

OpenAPI Documentation

Game round flow

Required data for integration

Communication format

Money format

Response status codes

Authentication

Idempotency

Games Api

GET /languages

GET /currencies

GET /games

GET /freerounds/info

GET /init

Wallet Api

POST /wallet/deposit

POST /wallet/withdraw

GET /wallet/balance

GET /wallet/transactions

Free Rounds Api

POST /freerounds/v2/create

POST /freerounds/cancel

Rounds Report

POST /round/info