Sarái — Integration API for operators (1.0.0)

Player ──▶ Operator ──(1) launch──▶ Sarái
                                        │ returns a URL with a session
Player ◀──────(2) opens the game────────┘
Player ──(3) spin──▶ Sarái ──(4) credit_transfer──▶ Operator
Player ◀───result─── Sarái ◀──────new balance────── Operator

1. Your server asks to open a game for a player with launch.
2. The player opens the URL returned by that call in their browser.
3. On every spin, the game calls Sarái. You take no part in that call.
4. Sarái calls your wallet to charge the bet and credit the win.

The integration therefore has two parts:

Both use the same credentials and the same signature.

For each integration (each site or brand) you receive a token, made of two values:

• The secret is handed over only once. If it is lost or leaked, ask for it to be renewed: the previous one stops working at that moment.
• Each token has its own RTP, its assigned games, its bet limits per currency, its wallet mode and its billing.
• The same player_id under two different tokens is two different players.

Besides the credentials, you need to tell us:

• The two URLs of your wallet (balance and credit_transfer).
• The credit_transfer mode: separate or combined.
• Optionally, the outbound IP addresses of your server, so the integration API is only accepted from them.

Every server-to-server request is signed with HMAC-SHA256, in both directions: the ones you send to Sarái and the ones Sarái sends to your wallet. They carry three headers:

The signature is the HMAC-SHA256, keyed with the token's secret, of this string:

timestamp + "." + METHOD + "." + path + "." + body

• METHOD is the HTTP method in uppercase: GET or POST.
• path is the path with its query string, without the domain: /operator/v1/launch.
• body is the exact body being sent, byte for byte. It is empty for a GET.
• A request with more than 5 minutes of clock skew is rejected: the server clock must be synchronised.

Python:

import hashlib, hmac, json, time, urllib.request

API = "https://api.sarai-games.com"
TOKEN = "fk_…"
SECRET = b"…"

def call(method, path, payload=None):
    body = json.dumps(payload).encode() if payload is not None else b""
    timestamp = str(int(time.time()))
    message = f"{timestamp}.{method}.{path}.".encode() + body
    signature = hmac.new(SECRET, message, hashlib.sha256).hexdigest()
    request = urllib.request.Request(API + path, data=body or None, method=method, headers={
        "X-FK-Token": TOKEN,
        "X-FK-Timestamp": timestamp,
        "X-FK-Signature": signature,
        "Content-Type": "application/json",
    })
    with urllib.request.urlopen(request) as response:
        return json.load(response)

Node.js:

import { createHmac } from 'node:crypto';

const API = 'https://api.sarai-games.com';
const TOKEN = 'fk_…';
const SECRET = '…';

async function call(method, path, payload) {
  const body = payload === undefined ? '' : JSON.stringify(payload);
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const signature = createHmac('sha256', SECRET).update(`${timestamp}.${method}.${path}.${body}`).digest('hex');
  const response = await fetch(API + path, {
    method,
    headers: { 'X-FK-Token': TOKEN, 'X-FK-Timestamp': timestamp, 'X-FK-Signature': signature, 'Content-Type': 'application/json' },
    body: body || undefined,
  });
  return response.json();
}

PHP:

function call(string $method, string $path, ?array $payload = null): array {
    $body = $payload === null ? '' : json_encode($payload);
    $timestamp = (string) time();
    $signature = hash_hmac('sha256', "$timestamp.$method.$path.$body", SECRET);
    $context = stream_context_create(['http' => [
        'method' => $method,
        'header' => "X-FK-Token: " . TOKEN . "\r\nX-FK-Timestamp: $timestamp\r\nX-FK-Signature: $signature\r\nContent-Type: application/json\r\n",
        'content' => $body,
        'ignore_errors' => true,
    ]]);
    return json_decode(file_get_contents(API . $path, false, $context), true);
}

Command line:

BODY='{"player_id":"u-1001","game":"fruits-classic","currency":"EUR","lang":"es"}'
TS=$(date +%s)
SIG=$(printf '%s.%s.%s.%s' "$TS" POST /operator/v1/launch "$BODY" \
  | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')
curl -X POST "$API/operator/v1/launch" \
  -H "X-FK-Token: $TOKEN" -H "X-FK-Timestamp: $TS" -H "X-FK-Signature: $SIG" \
  -H 'Content-Type: application/json' -d "$BODY"

Your wallet must verify the signature of every call it receives and reject the ones that fail. This is what prevents a third party from moving your players' balances.

import hashlib, hmac, time

def verify(secret: bytes, headers: dict, method: str, path: str, body: bytes) -> bool:
    timestamp = headers.get("X-FK-Timestamp", "")
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
        return False
    expected = hmac.new(secret, f"{timestamp}.{method}.{path}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, headers.get("X-FK-Signature", ""))

path is the path of your wallet URL, with its query string if it has one, and body is the raw bytes of the body as received, before decoding the JSON.

• Signing one JSON and sending another, with a different key order or spacing. You must sign exactly the bytes you send.
• Leaving the query string out of the path of a GET.
• Verifying the signature over the JSON after decoding and re-encoding it, instead of over the bytes received.
• An unsynchronised clock.

• Amounts always travel as decimal text ("2.50"), never as a number, so no precision is lost.
• Fiat and crypto currencies are supported. Each currency has its own decimals: 2 for EUR, 0 for JPY, 8 for BTC, 18 for ETH. An amount never has more decimals than its currency.
• There is no conversion: a session plays in a single currency from start to finish, the one you send in launch.
• A currency can only be used if it is enabled and has bet limits configured for your token.

Errors from the integration API always have this shape, with a stable code you can rely on in your code. message is an explanation in English for whoever is debugging; it is not meant to be shown to the player.

{ "status": "error", "code": "game_not_allowed", "message": "the game is not assigned to this token" }

Each operation adds its own.

The mode is chosen per token and decides how many calls your wallet receives on each round.

In separate mode, the win call is also sent when the win is zero, so you can close the round. This can be turned off per token.

These are what prevent double charges and lost money. Your wallet must comply with all of them.

1. Idempotency. If a transaction_id you have already processed arrives, return the same result without moving the balance again. Fruit King retries with the same transaction_id when it gets no response.
2. rollback. A call with type: "rollback" undoes everything the round round_id got to apply. Sarái sends it when a round was voided because your wallet did not respond.
3. rollback of something that does not exist. If the round was never applied, respond ok anyway, without changing the balance.
4. rollback before the bet. If the rollback arrives first, because the original bet is still on its way, remember it and reject the bet when it arrives.

Your wallet always responds with HTTP 200 and one of the two documented bodies (ok or rejected). Anything else —another HTTP status, a body that is not that JSON, a redirect, or not responding in time— is an unknown response: Sarái does not know whether you applied the operation.

Retries of rollbacks and win credits use the same transaction_id, with increasing waits from 5 seconds to 15 minutes, for about three hours (20 attempts). After that, the call goes to manual review by our team. If you respond rejected to a rollback or a win credit, it is not retried: it goes straight to manual review.

The maximum wait for each call is configured per token, up to 30 seconds. A slow wallet makes the game slow: aim to respond in under 200 ms.

• The secret is only on the server, never in the browser or the repository.
• The signature of incoming calls is verified and invalid ones are rejected.
• A repeated transaction_id returns the same result without moving the balance.
• A bet with insufficient balance responds rejected, with HTTP 200.
• A rollback of an applied bet returns the balance.
• A rollback of an unknown round responds ok.
• A rollback followed by its bet: the bet is rejected.
• A repeated win credit is not paid twice.
• The wallet responds in under 200 ms under normal load.
• The server clock is synchronised.
• The outbound IPs have been communicated, if the IP restriction is used.

Along with your integration credentials you also receive an account for the read-only operator portal: activity summary, tokens, players, the detail of every round, reports exportable to CSV, and monthly invoices. Each account can turn on two-step verification.

Open a game for a player. Called by your server.

Available games and the detail of a round. Called by your server.

The two URLs that you implement and that Sarái calls with POST, JSON and the token's signature. They are configured on the token; they can be any https URL on your server.

Read the four wallet rules and what happens when your wallet does not respond first.