Last updated: November 2026

Operator Integration Guide

A simple, step-by-step guide for backend and frontend engineers who want to embed Galaxy Games into their platform.

1The big picture

Galaxy Games is a crash-game platform. You connect to it with a small server-to-server API. Your backend asks for a game link, your frontend shows the link in an iframe, and Galaxy Games tells your wallet service about every bet and win.

1. Create sessionYour backend calls Galaxy Games with your API key.
2. Get game linkYou receive a signed gameUrl.
3. Player playsBrowser shows the game in an iframe.
4. Wallet updatesGalaxy Games sends signed webhooks to you.

Available games

2Getting started

A provider admin creates your operator account. You will receive the items below. Save them safely.

Default operator settings (all editable later in the admin panel):

3Authentication

There are two kinds of credentials. Do not mix them up.

• The token sits in the URL fragment (after #). Browsers never send fragments to servers, so it stays out of logs.
• The game reads the token once and removes it from the address bar.
• The token contains: playerId, operatorId, externalPlayerId, currency, isDemo, gameType and a one-time jti (for instant revocation).

4Launching a game

Step 1: Create a session (from your backend)

POST/api/v1/session/create

Headers: Content-Type: application/json and X-Api-Key: <your key>

{
  "externalPlayerId": "player_123",
  "username": "JohnD",
  "currency": "ETB",
  "isDemo": false,
  "gameType": "aviator",
  "launch": "game"
}

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "playerId": "a1b2c3d4-...",
  "expiresIn": 14400,
  "gameUrl": "https://games.example.com/aviator#token=eyJ..."
}

• playerId is the Galaxy Games ID. Keep it: you need it for free bets and reports.
• New players are created automatically. Existing players get their username updated if it changed.

Step 2: Show the game in an iframe

<iframe
  src="https://games.example.com/aviator#token=eyJ..."
  width="800" height="600" allow="fullscreen"
  sandbox="allow-scripts allow-same-origin allow-popups allow-forms">
</iframe>

Step 3 (optional): Let the player switch games

From inside the lobby, the game calls POST /api/v1/session/switch with the player token as Authorization: Bearer ... and body { "gameType": "fast_keno" }. You get a new token and gameUrl back. This is automatic. Player and operator status are re-checked every time, so a suspended player cannot sneak back in.

When session creation is refused

5Wallet webhooks

For every real-money action, Galaxy Games sends a signed POST request to your webhook URL. Your server must update the player's wallet. Demo sessions never send webhooks.

Example payload

{
  "type": "bet",
  "playerId": "a1b2c3d4-e5f6-...",
  "betId": "b7c8d9e0-...",
  "roundId": "f1a2b3c4-...",
  "amount": 50.00,
  "currency": "ETB",
  "multiplier": 2.50,        // win events only
  "trigger": "manual",       // win events only: "auto" or "manual"
  "gameType": "aviator",
  "isDemo": false,
  "timestamp": "2024-06-01T12:34:56.789Z"
}

Verify every webhook

Each request carries X-Galaxy-Signature: sha256=<hex> and X-Galaxy-Event. (The older X-Aviator-* headers are also sent.) Compute an HMAC-SHA256 of the raw body with your webhook secret and compare it using a constant-time check. Reject anything that does not match.

• Read the body as raw bytes, not parsed JSON. The signature is calculated over the exact raw text.

Delivery rules

6Free bets

Free bets are promotional bets you give to players. Placing one does not debit the wallet and sends no webhook. If it wins, you receive a normal win webhook.

Grant to one player

POST/api/admin/free-bets

{
  "playerId": "<player UUID>",
  "amount": 10.00,
  "currency": "ETB",
  "wageringRequirement": 1,
  "expiresInHours": 72,
  "bonusType": "welcome",
  "gameType": "aviator"
}

Grant in bulk

POST/api/admin/free-bets/bulk

• Auto bonus: the platform can grant a consecutive_loss free bet automatically after N losses in a row. Set it up in the admin panel; no API call needed.
• Safe by design: when a free bet is used, the server checks it belongs to the player, game and operator, matches the amount and is not expired or used. It is marked used and the bet saved in one atomic step.

7Reports & dashboard

All endpoints live under /api/admin/operator-dashboard/ and need admin login. Provider admins add ?operatorId=<uuid>.

8Player safety

Each player is identified by your externalPlayerId. The same ID at two different operators is two separate players.

Status is checked at: session create, every WebSocket connection, every bet, and every game switch. Suspending a player disconnects them instantly. Suspending an operator disconnects all its players.

Responsible-gambling fields per player: dailyDepositLimit, sessionTimeLimitMins, selfExcludedUntil. Manage them in the admin panel under /admin/players/:id.

9Custom client (WebSocket)

Connect with Socket.IO and pass the player token. Crash games (Aviator, JetX) use the root namespace. Others use /chicken-road, /pilot-chicken or /fast-keno.

import { io } from 'socket.io-client';

const socket = io(url, { auth: { token: playerJwt } });

Client sends

Server sends

Rate limits (per connection): 30 bets per minute and 10 cash-outs per minute. Going over returns a "Too many requests" rejection.

10Server settings

These live in the Galaxy Games server .env file. They are managed by the provider, but good to know.

11Go-live checklist

Tick every box before you launch. Your ticks are saved in this browser.

• API key is in a secrets manager, not in code or Git.
• Sessions are created from your server, never from a browser or mobile app.
• Webhook signature is verified with a constant-time comparison.
• Webhook handler is idempotent (deduplicates on betId).
• Webhook answers with HTTP 2xx within 5 seconds.
• Webhook URL is public HTTPS, not a private IP.
• Your website origin is in ALLOWED_ORIGINS.
• Demo sessions (isDemo: true) never move real money in your wallet.
• You handle HTTP 403 (suspended / self-excluded) with a clear message.
• You never log or store the full player token, only the playerId.

0 / 10 complete

12Code examples

Create a session (Node.js)

async function createGameSession(playerId, username, currency = 'ETB') {
  const res = await fetch('https://games.example.com/api/v1/session/create', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': process.env.GALAXY_API_KEY,
    },
    body: JSON.stringify({
      externalPlayerId: playerId, username, currency,
      isDemo: false, gameType: 'aviator', launch: 'game',
    }),
  });
  if (!res.ok) {
    const err = await res.json();
    throw new Error(`Session create failed: ${err.error}`);
  }
  return res.json(); // { token, playerId, expiresIn, gameUrl }
}

Receive webhooks (Node.js / Express)

const express = require('express');
const crypto  = require('crypto');
const app = express();

app.post('/webhooks/galaxy', express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.headers['x-galaxy-signature'] ?? '';
    const expected = 'sha256=' + crypto
      .createHmac('sha256', process.env.GALAXY_WEBHOOK_SECRET)
      .update(req.body).digest('hex');

    const a = Buffer.from(expected), b = Buffer.from(signature);
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b))
      return res.status(401).json({ error: 'Invalid signature' });

    const event = JSON.parse(req.body.toString());
    if (await isAlreadyProcessed(event.betId)) return res.sendStatus(200);

    switch (event.type) {
      case 'bet':
        await debitPlayerWallet(event.playerId, event.amount,
                                event.currency, event.betId);
        break;
      case 'win':   // payout = amount x multiplier (confirm with provider)
        await creditPlayerWallet(event.playerId,
                                 event.amount * event.multiplier,
                                 event.currency, event.betId);
        break;
      case 'refund':
        await creditPlayerWallet(event.playerId, event.amount,
                                 event.currency, event.betId);
        break;
    }
    await markProcessed(event.betId);
    res.sendStatus(200);
  });

Embed the game (React)

function GameFrame({ playerId, username }) {
  const [gameUrl, setGameUrl] = React.useState(null);

  React.useEffect(() => {
    fetch('/api/game-session', {            // your own backend endpoint
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ playerId, username }),
    }).then(r => r.json()).then(({ gameUrl }) => setGameUrl(gameUrl));
  }, [playerId]);

  if (!gameUrl) return <div>Loading game...</div>;
  return (
    <iframe src={gameUrl} title="Galaxy Games" width="100%" height="700"
      allow="fullscreen"
      sandbox="allow-scripts allow-same-origin allow-popups allow-forms"
      style={{ border: 'none', borderRadius: 8 }} />
  );
}

13Error reference

Session errors

Bet rejection reasons (WebSocket)

If webhook deliveries keep failing

• Your endpoint takes longer than 5 seconds to respond.
• It returns a non-2xx status, including redirects (3xx). Use the final URL.
• There is an SSL certificate error on your endpoint.
• A firewall blocks Galaxy Games server IPs.

Failed transactions stay in the log. Contact your provider if problems continue after you fix your endpoint.