SoftBet API

A single, programmable iGaming back-end: slots, sportsbook, crypto wallets, free-spin campaigns, white-label hosting, and operator dashboards. Same auth model, consistent error envelope, predictable rate-limits.

Base URLs

Versioning

All paths are explicitly versioned. The dashboard/auth surface lives under /v1/*; the slots/games surface lives under /api/v1/* for byte-compatibility with the legacy integration shape; new platforms (hosting, sportsbook) live under /v1/<platform>/*. Breaking changes ship as a new major prefix.

Content type

All requests and responses use application/json; charset=utf-8 unless explicitly noted. Set Accept: application/json on every request. Send Content-Type: application/json on every request with a body.

Pagination

List endpoints accept limit (default and max per-endpoint, never exceeds 200) and either cursor (opaque, stable across page-loads) or page for legacy admin views. Responses include { items: [...], next_cursor: "…" | null }. Stop when next_cursor is null.

Time

All timestamps are RFC 3339 / ISO 8601 in UTC with millisecond precision, e.g. 2026-05-21T12:34:56.789Z. Unix epoch where used is integer seconds.

SDKs

No official SDKs today — the API is REST + JSON over HTTPS, intentionally small enough to be one file in any language. Examples throughout these docs are in cURL, JavaScript (fetch), and Python (requests).

Authentication

Three authentication modes. Pick by the URL prefix you're calling.

1) Session cookie — Dashboard & admin

Endpoints under /v1/auth/*, /v1/dashboard/*, /v1/admin/*, and /v1/hosting/* (when called from a browser) authenticate by HttpOnly; Secure; SameSite=Lax session cookies set by POST /v1/auth/login. The cookie domain is .softbet.io — cross-subdomain requests work; cross-origin browser requests must call from a *.softbet.io host or include credentials: 'include' against api.softbet.io.

2) API key + HMAC — Programmatic slots / gateway

Endpoints under /api/v1/* (slots, games, freespins, freevouchers, self-exclusion) use a key+secret pair with an HMAC-SHA1 request signature. Create the pair in Dashboard → API keys; the secret is shown once.

On every request, send these headers in addition to the body:

Signature computed as HMAC-SHA1(canonicalQuery(params + authHeaders), bs_live_<secret>). The canonical string is the URL-encoded, sorted-by-key form of the request parameters concatenated with the four auth headers. See the HMAC signing reference for the exact algorithm and a worked example.

3) Bearer PAT — Hosting platform (programmatic)

Server-to-server access to /v1/hosting/* uses a personal access token. Create one in Dashboard → Hosting → API tokens. Tokens are prefixed prv_ and shown once.

Send as Authorization: Bearer prv_…. The token is scoped to your tenant; the URL-prefix guard rejects any request to a non-hosting path. PATs bypass TOTP 2FA (intentional — they're for unattended automation).

# 1) Session cookie (login first, then reuse the cookie jar)
curl -c cookies.txt -X POST https://api.softbet.io/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"·······"}'
curl -b cookies.txt https://api.softbet.io/v1/auth/me

# 2) API key + HMAC (slots / gateway)
TS=$(date +%s); NONCE=$(openssl rand -hex 8)
SIG=$(echo -n "page=1&limit=50&X-API-Key=bs_live_…&X-Timestamp=$TS&X-Nonce=$NONCE" \
  | openssl dgst -sha1 -hmac 'bs_live_<secret>' -hex | cut -d' ' -f2)
curl https://api.softbet.io/api/v1/games?page=1&limit=50 \
  -H "X-API-Key: bs_live_…" -H "X-Timestamp: $TS" \
  -H "X-Nonce: $NONCE"     -H "X-Sign: $SIG"

# 3) Bearer PAT (hosting)
curl https://api.softbet.io/v1/hosting/servers \
  -H 'Authorization: Bearer prv_…'

// 1) Session cookie
await fetch('https://api.softbet.io/v1/auth/login', {
  method: 'POST', credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email, password }),
});
const me = await fetch('https://api.softbet.io/v1/auth/me',
  { credentials: 'include' }).then(r => r.json());

// 2) API key + HMAC — see HMAC section for sign()
const sign = (params, secret) => { /* HMAC-SHA1 canonical */ };
const ts = Math.floor(Date.now()/1000);
const nonce = crypto.randomUUID().replace(/-/g,'').slice(0,16);
const params = { page: 1, limit: 50 };
const headers = {
  'X-API-Key': 'bs_live_…', 'X-Timestamp': ts, 'X-Nonce': nonce,
};
headers['X-Sign'] = sign({...params, ...headers}, 'bs_live_<secret>');
await fetch('https://api.softbet.io/api/v1/games?page=1&limit=50', { headers });

// 3) Bearer PAT
await fetch('https://api.softbet.io/v1/hosting/servers', {
  headers: { 'Authorization': 'Bearer prv_…' }
});

import requests, time, secrets, hmac, hashlib
s = requests.Session()

# 1) Session cookie
s.post('https://api.softbet.io/v1/auth/login',
       json={'email': '[email protected]', 'password': '·······'})
me = s.get('https://api.softbet.io/v1/auth/me').json()

# 2) API key + HMAC
def sign(params, secret):
    canon = '&'.join(f'{k}={params[k]}' for k in sorted(params))
    return hmac.new(secret.encode(), canon.encode(), hashlib.sha1).hexdigest()

ts = str(int(time.time())); nonce = secrets.token_hex(8)
params = {'page': 1, 'limit': 50}
headers = {'X-API-Key': 'bs_live_…', 'X-Timestamp': ts, 'X-Nonce': nonce}
headers['X-Sign'] = sign({**params, **headers}, 'bs_live_<secret>')
r = requests.get('https://api.softbet.io/api/v1/games', params=params, headers=headers)

# 3) Bearer PAT
requests.get('https://api.softbet.io/v1/hosting/servers',
             headers={'Authorization': 'Bearer prv_…'})

Cookie security & sessions

Sessions expire after 30 days of inactivity. Logging in from a new device emits an email notification (configurable in Settings). Calling POST /v1/auth/logout revokes the current session; calling POST /v1/auth/totp/disable with a verified TOTP code also revokes all other active sessions for the account.

Errors

Every error returns a JSON envelope with a stable machine-readable code and a human-readable message. Always switch on error.code, never on the message string.

Error envelope

{
  "ok": false,
  "error": {
    "code":    "validation_error",
    "message": "amount_usd must be at least 10",
    "details": { "field": "amount_usd", "min": 10 }
  }
}

{ "ok": false, "error": { "code": "validation_error", "message": "…", "details": {} } }

{ "ok": false, "error": { "code": "validation_error", "message": "…", "details": {} } }

HTTP status codes

Common error.code values

Retry guidance

• 429 — always honour Retry-After. Exponential back-off otherwise.
• 500 / 502 / 503 / 504 — safe to retry idempotent requests. For non-idempotent ones (e.g. POST /v1/billing/deposit) use a unique X-Nonce and retry — server-side de-duplication will return the prior response.
• 401 / 403 / 404 / 409 / 422 — never retry without changing the request. The same input will fail the same way.

Rate limits

Per-API-key, configurable, soft-fail with 429 and a Retry-After header.

Default budget

429 response

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{ "ok": false, "error": {
  "code": "rate_limited",
  "message": "Too many requests. Slow down and retry in ~12 s.",
  "details": { "retry_after_seconds": 12, "limit_rps": 50, "scope": "key" }
}}

// Headers: Retry-After: 12
{ ok: false, error: { code: 'rate_limited', message: '…', details: { retry_after_seconds: 12, limit_rps: 50, scope: 'key' } } }

# r.status_code == 429; r.headers['Retry-After'] == '12'
{ 'ok': False, 'error': { 'code': 'rate_limited', 'details': { 'retry_after_seconds': 12 } } }

Raising your budget

From the Dashboard, edit the key and set rate_limit_rps up to 2000. Above that, contact support — we'll discuss a dedicated capacity plan and pinned upstream slots quota.

Currencies & supported devises

Every monetary value in the API is denominated in one of the currencies below. Pass currency codes in upper-case ISO 4217 for fiat, in the canonical short form for crypto (with the network suffix where ambiguous).

Crypto — deposits, payouts, gateway

Fiat — wallet denomination & FX conversion

Player wallets are denominated in a single fiat currency you choose at account creation; bet/win/refund callbacks all move that currency. The list below is the universe of supported account-currency choices.

FX rates are sourced from the European Central Bank reference set + on-chain oracles for crypto-fiat, cached for 60 s, and exposed through GET /v1/billing/currencies. Use that endpoint to drive UI dropdowns rather than hard-coding the list above.

Encoding amounts

Send amounts as decimal strings for crypto (e.g. "0.00025000") and as numbers for fiat (e.g. 25.00). Never round to fewer decimals than the table above — we will reject the request with 422 validation_error.

Auth endpoints

Account lifecycle, sign-in, email verification, password reset, and TOTP 2FA. Hosted at /v1/auth/*. All endpoints accept JSON and use session cookies on success — there is no JWT.

{ "ok": true, "user": { "id": "uuid", "email": "[email protected]", "status": "pending" } }

curl -X POST https://api.softbet.io/v1/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"AnExcellentPass1!","company_name":"Acme"}'

await fetch('https://api.softbet.io/v1/auth/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email, password, company_name: 'Acme' }),
});

requests.post('https://api.softbet.io/v1/auth/register', json={
    'email': '[email protected]', 'password': 'AnExcellentPass1!', 'company_name': 'Acme'
})

curl -X POST https://api.softbet.io/v1/auth/verify \
  -H 'Content-Type: application/json' -d '{"token":"ver_…"}' -c cookies.txt

await fetch('/v1/auth/verify', { method: 'POST', credentials: 'include',
  headers: {'Content-Type':'application/json'}, body: JSON.stringify({ token }) });

s.post('https://api.softbet.io/v1/auth/verify', json={'token': token})

curl -X POST https://api.softbet.io/v1/auth/login -c cookies.txt \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"·······"}'

const r = await fetch('https://api.softbet.io/v1/auth/login', {
  method: 'POST', credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email, password }),
}).then(r => r.json());
if (r.totp_required) { /* show TOTP screen, then POST /v1/auth/totp/verify */ }

r = s.post('https://api.softbet.io/v1/auth/login',
           json={'email': email, 'password': pw}).json()
if r.get('totp_required'):
    s.post('https://api.softbet.io/v1/auth/totp/verify',
           json={'challenge': r['challenge'], 'code': input('TOTP: ')})

curl https://api.softbet.io/v1/auth/me -b cookies.txt

const me = await fetch('/v1/auth/me', { credentials: 'include' }).then(r => r.json());
if (me.ok) { /* signed in */ } else { /* signed out */ }

me = s.get('https://api.softbet.io/v1/auth/me').json()

curl -X POST https://api.softbet.io/v1/auth/logout -b cookies.txt

await fetch('/v1/auth/logout', { method: 'POST', credentials: 'include' });

s.post('https://api.softbet.io/v1/auth/logout')

curl -X POST https://api.softbet.io/v1/auth/forgot \
  -H 'Content-Type: application/json' -d '{"email":"[email protected]"}'

await fetch('/v1/auth/forgot', { method: 'POST', headers: {'Content-Type':'application/json'},
  body: JSON.stringify({ email }) });

s.post('https://api.softbet.io/v1/auth/forgot', json={'email': email})

curl -X POST https://api.softbet.io/v1/auth/reset \
  -H 'Content-Type: application/json' \
  -d '{"token":"rst_…","password":"NewExcellentPass1!"}'

await fetch('/v1/auth/reset', { method: 'POST', headers: {'Content-Type':'application/json'},
  body: JSON.stringify({ token, password }) });

s.post('https://api.softbet.io/v1/auth/reset', json={'token': token, 'password': pw})

TOTP 2-factor authentication

Opt-in. Once enabled, every POST /v1/auth/login returns a challenge instead of a session — the client must then POST the 6-digit TOTP (or a backup code) to /v1/auth/totp/verify. PATs and webhook HMAC bypass 2FA (intentional). Per project-hosting-2fa-totp: otplib@13 async API, sha256-hashed single-use backup codes, 5-fail lockout for 15 min.

API keys

Programmatic access to the slots / gateway surface (/api/v1/*). Each key has a public id (sent as X-API-Key) and a secret (used to compute the HMAC signature). Secrets are shown once at creation and on rotate; we store only the SHA-256 hash.

{ "ok": true, "key": {
  "id": "bs_live_3f4a…", "secret": "bs_live_9k8j…",   // ← shown ONCE
  "label": "Production app", "scopes": ["games:read","games:launch","webhooks:receive"],
  "rate_limit_rps": 50, "created_at": "2026-05-21T12:34:56Z"
} }

curl -X POST https://api.softbet.io/v1/keys -b cookies.txt \
  -H 'Content-Type: application/json' \
  -d '{"label":"Production app","rate_limit_rps":200}'

const k = await fetch('/v1/keys', { method:'POST', credentials:'include',
  headers:{'Content-Type':'application/json'},
  body: JSON.stringify({ label:'Production app', rate_limit_rps: 200 }) }).then(r=>r.json());
saveToVault(k.key.secret);

k = s.post('https://api.softbet.io/v1/keys',
           json={'label':'Production app','rate_limit_rps':200}).json()
save_to_vault(k['key']['secret'])

curl https://api.softbet.io/v1/keys -b cookies.txt

const { keys } = await fetch('/v1/keys', { credentials:'include' }).then(r=>r.json());

keys = s.get('https://api.softbet.io/v1/keys').json()['keys']

{ "ok": true, "key": { "id": "bs_live_3f4a…", "secret": "bs_live_NEW…", "rotated_at": "…" } }

Slots & games

Catalog browsing, real-money and demo game launches, lobby views, freespin context. Hosted under /api/v1/* — all endpoints require API-key + HMAC authentication.

curl 'https://api.softbet.io/api/v1/games?page=1&perPage=25' \
  -H "X-API-Key: …" -H "X-Timestamp: $TS" -H "X-Nonce: $NONCE" -H "X-Sign: $SIG"

await fetch('https://api.softbet.io/api/v1/games?page=1&perPage=25', { headers: signedHeaders });

requests.get('https://api.softbet.io/api/v1/games',
  params={'page':1,'perPage':25}, headers=signed_headers)

curl https://api.softbet.io/api/v1/game-tags -H "X-API-Key: …" -H "X-Sign: …" …

await fetch('/api/v1/game-tags', { headers: signedHeaders });

requests.get('https://api.softbet.io/api/v1/game-tags', headers=signed_headers)

{ "ok": true, "session": {
  "id": "sess_…", "url": "https://launcher.softbet.io/…?token=…",
  "expires_at": "2026-05-21T13:34:56Z"
} }

curl -X POST https://api.softbet.io/api/v1/games/init \
  -H "X-API-Key: …" -H "X-Timestamp: $TS" -H "X-Nonce: $NONCE" -H "X-Sign: $SIG" \
  -H "Content-Type: application/json" \
  -d '{
    "game_uuid":   "5e0a…",
    "player_id":   "p_42",
    "session_id":  "'"$(openssl rand -hex 16)"'",
    "currency":    "USD",
    "language":    "en"
  }'

const session_id = crypto.randomUUID().replace(/-/g,'');
const r = await signedFetch('POST', '/api/v1/games/init', {
  game_uuid, player_id, session_id, currency: 'USD',
}).then(r => r.json());
iframe.src = r.session.url;

import secrets
r = signed_post('/api/v1/games/init', {
    'game_uuid': game_uuid, 'player_id': player_id,
    'session_id': secrets.token_hex(16), 'currency': 'USD',
}).json()
iframe_url = r['session']['url']

Freespins

Grant a player N free spins on a specific game at a fixed bet amount. The spins are server-tracked through SoftBet — every spin's result is mirrored locally so you keep the full history even after SoftBet burns through the campaign.

curl -X POST https://api.softbet.io/api/v1/freespins/set \
  -H "X-API-Key: …" -H "X-Sign: …" \
  -H "Content-Type: application/json" \
  -d '{"campaign_id":"welcome_2026_05","player_id":"p_42","game_uuid":"5e0a…","spins":50,"bet_value":0.20}'

await signedFetch('POST','/api/v1/freespins/set', {
  campaign_id, player_id, game_uuid, spins: 50, bet_value: 0.2,
});

signed_post('/api/v1/freespins/set', {
    'campaign_id': cid, 'player_id': pid, 'game_uuid': uid,
    'spins': 50, 'bet_value': 0.2,
})

Freevouchers

Single-use cash credits redeemable by code. Unlike freespins, freevouchers are not tied to a game — they're a balance top-up the player redeems explicitly.

Self-exclusion

Responsible-gaming primitive. When a player self-excludes, all downstream actions (game launches, freespin sets, voucher redemptions, deposits) fail with 403 self_exclusion_active until the cool-off window expires.

Billing & deposits

Take crypto deposits from your players, convert at oracle spot, credit their fiat wallet. We handle the on-chain address, the confirmations, and the FX leg.

curl https://api.softbet.io/v1/billing/currencies -b cookies.txt

const { currencies } = await fetch('/v1/billing/currencies',
  { credentials:'include' }).then(r => r.json());

s.get('https://api.softbet.io/v1/billing/currencies').json()['currencies']

{ "ok": true, "deposit": {
  "id": "dep_…", "currency": "BTC", "amount_usd": 25.00,
  "amount_native": "0.00041500", "address": "bc1q…",
  "qr_svg_url": "https://…", "expires_at": "2026-05-21T13:34:56Z",
  "confirmations_required": 1, "status": "awaiting_payment"
} }

curl -X POST https://api.softbet.io/v1/billing/deposit -b cookies.txt \
  -H 'Content-Type: application/json' \
  -d '{"currency":"BTC","amount_usd":25}'

const { deposit } = await fetch('/v1/billing/deposit', {
  method:'POST', credentials:'include',
  headers:{'Content-Type':'application/json'},
  body: JSON.stringify({ currency:'BTC', amount_usd: 25 })
}).then(r => r.json());
showQr(deposit.qr_svg_url); pollUntil(deposit.id);

d = s.post('https://api.softbet.io/v1/billing/deposit',
           json={'currency':'BTC','amount_usd':25}).json()['deposit']

Dashboard data

Operator-facing endpoints powering the dashboard UI: account config, wallet balance, usage metrics, transaction history, sessions, recent requests, integration probe. All require session-cookie auth.

Gateway / Crypto

Take crypto deposits + send payouts on behalf of your end-users. Distinct from the simpler billing flow above — gateway is multi-tenant: you are the operator, your end-users are individual customers. Tatum is the underlying custody provider; we own KMS and address allocation.

Settings

Keys

Balances + history

End-users

Payouts

DASH-specific (legacy)

Dash has its own short-circuit set of endpoints kept for historical contracts. Treat as deprecated for new integrations; use the unified /v1/gateway/* surface with currency: "DASH" instead.

Hosting — Plans & images

Choose what hardware tier and base image to provision your VMs on. Read-only — Plans and Images are curated by us, you can't add custom ones via the API.

All hosting endpoints accept either a session cookie (dashboard) or Authorization: Bearer prv_… (PAT). Examples below show the PAT form for the most common server-to-server case.

curl https://api.softbet.io/v1/hosting/plans -H 'Authorization: Bearer prv_…'

await fetch('/v1/hosting/plans', { headers:{Authorization:'Bearer prv_…'}});

requests.get('https://api.softbet.io/v1/hosting/plans',
  headers={'Authorization':'Bearer prv_…'})

Hosting — Servers

Provision, query, mutate, and tear down virtual machines. Each server belongs to a tenant; PATs are tenant-scoped.

curl -X POST https://api.softbet.io/v1/hosting/servers \
  -H 'Authorization: Bearer prv_…' -H 'Content-Type: application/json' \
  -d '{"name":"web-01","plan_id":2,"image_code":"debian-12","tags":["prod"]}'

const s = await fetch('/v1/hosting/servers', {
  method:'POST', headers: { Authorization: 'Bearer prv_…',
                            'Content-Type':'application/json' },
  body: JSON.stringify({ name:'web-01', plan_id:2, image_code:'debian-12' })
}).then(r => r.json());

requests.post('https://api.softbet.io/v1/hosting/servers',
  headers={'Authorization':'Bearer prv_…'},
  json={'name':'web-01','plan_id':2,'image_code':'debian-12'})

Setup module

Configurable post-provision setup: timezone, swap, motd, hostname override, extra packages. Strict allow-list per project-hosting-setup-allowlist: hostname regex, 35-entry TZ list, motd ≤500, swap 64–4096 MiB, 37-package list.

Hosting — Volumes

Additional disks attached to a server. LVM-thin per-server; no cross-server move in v1.

Hosting — Firewall

Per-server stateless L3/L4 firewall rules enforced at the Proxmox bridge. Default-deny when enabled.

Hosting — DNS & domains

Attach domains to a server, point them at our nameservers (ns1.softbet.io, ns2.softbet.io), manage records through PowerDNS (CT110 master + CT111 slave). 100-record quota per domain. Per project-hosting-dns-permanent-error: 4xx upstream errors mark dirty=false; customer edits the record or hits POST /retry.

Hosting — SSH keys

Account-level key library + per-server attach/detach. Adding/removing a key on a server propagates via the QEMU guest agent (queued-detach on server transfer per project-hosting-transfer-atomic).

Hosting — Snapshots & backups

Two distinct primitives. Snapshots are local Proxmox volume snapshots (fast, cheap, deleted with the server). Backups are off-host archive copies (slower, durable, survive server destroy, billed separately).

Snapshots

Backups

Hosting — Alerts & notifications

Define rules ("CPU > 80 % for 5 min", "free disk < 10 %") on your servers and we'll route firings to in-app, email-instant, or email-daily-digest channels per project-hosting-notif-digest.

Alert rules

Notifications

Hosting — Sharing & transfer

Per project-hosting-role-caps and project-hosting-transfer-atomic. Roles: owner, member, billing, support. Transfer is owner-initiated, recipient-accepted, atomic across servers + volumes + alert rules.

Server members

Invites (recipient side)

Transfer (ownership)

Hosting — CMS install

One-click install of WordPress / Ghost / Nextcloud / etc. on a provisioned server. Installs are orchestrated server-side; you poll the install record for completion.

Hosting — API tokens (PAT)

Create tokens for unattended automation. Tokens prefix prv_, are tenant-scoped, shown once. Per project-hosting-pat-scope, the URL-prefix guard rejects PATs on any path that isn't /v1/hosting/*.

Hosting — Webhook subscriber endpoints

Manage YOUR HTTPS endpoints that receive our outbound hosting webhooks. Per project-hosting-webhooks-fanout, the dispatcher matches subscribers by tenant_id; rows with NULL tenant are silently dropped (intentional — that's only audit/alert data). For the wire format of the events you'll receive, see Webhooks → Outbound.

Sportsbook — Player API

Real-money sports betting. Sessions are short-lived per player and signed with the same HMAC scheme as slots.

Sportsbook — Operator settings

Operator-side configuration for the sportsbook product (margins, embed code generation, dashboard toggles).

Webhooks — Outbound (we send)

Events SoftBet POSTs to your registered endpoint. JSON body, signed with HMAC-SHA256 in the X-Provide-Hosting-Signature header (also used by the Phase E2 alerts pipeline — one format for both).

Common envelope

POST /your-webhook-receiver HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: SoftBet-Webhook/1.0
X-Provide-Hosting-Signature: sha256=<hex>
X-Event-Type: server.provisioned
X-Event-Id: evt_01HW…
X-Event-Delivery: dlv_01HW…   # unique per delivery attempt; same event_id retries get fresh delivery

{ "event_id": "evt_…", "event_type": "server.provisioned",
  "occurred_at": "2026-05-21T12:34:56.789Z",
  "tenant_id": "uuid",
  "data": { …event-specific payload… } }

import crypto from 'node:crypto';
import express from 'express';
const app = express();

// IMPORTANT: read the raw body — JSON.parse alters whitespace and breaks the signature.
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-provide-hosting-signature'] || '';
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(req.body).digest('hex');
  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).send('bad signature');
  }
  const event = JSON.parse(req.body);
  switch (event.event_type) {
    case 'server.provisioned': /* … */ break;
    case 'alert.fired':        /* … */ break;
  }
  res.sendStatus(204);
});

import os, hmac, hashlib
from flask import Flask, request, abort
app = Flask(__name__)

@app.post('/webhook')
def webhook():
    raw = request.get_data()  # raw bytes — needed for HMAC
    sig = request.headers.get('X-Provide-Hosting-Signature', '')
    expected = 'sha256=' + hmac.new(
        os.environ['WEBHOOK_SECRET'].encode(), raw, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(sig, expected):
        abort(401)
    event = request.get_json()
    if event['event_type'] == 'server.provisioned':
        ...
    return '', 204

Event types

Delivery, retries, ordering

• Delivery is at-least-once. Your receiver must be idempotent on event_id.
• Retries on non-2xx: 5 attempts with exponential back-off (~30 s, 2 min, 10 min, 30 min, 2 h). After the 5th failure the delivery is marked dead and surfaced in /deliveries.
• Ordering is not guaranteed. Use occurred_at to order; ignore stale events with older occurred_at.
• Timeout: your endpoint has 2 s to respond. Longer = treated as failure.

Webhooks — Inbound (slot callbacks)

When a player bets / wins / refunds / rolls back on one of your slot games, we POST the event to your callback URL. The wire format is preserved byte-for-byte compatible with the upstream provider's contract so any existing integration migrates without code changes.

Callback URL

Configure under Dashboard → Settings → Webhook URL. HTTPS only, ≤2 s response, must return HTTP 200 with a JSON body acknowledging the action — failure to ack causes the wallet to refuse the bet (which then reverses on the upstream).

Signature header

Every request carries X-Signature: <hex>. The signature is HMAC-SHA1(rawBody, <your API secret>). Verify before processing.

Event types you'll receive

Bonus buy & zero-amount callbacks

You will receive bet (and sometimes win) callbacks with amount: 0. This is normal: in a bonus buy the player pays once for the feature, then each feature spin/choice arrives as a bet with amount = 0 (the round stays open until the feature ends). Zero-win spins arrive as win with amount = 0.

Example: bet callback

POST https://your-casino.example/wallet-callback
Content-Type: application/json
X-Signature: a1b2c3…

{ "type": "bet",
  "transaction_id":    "sb_tx_…",
  "round_id":          "sb_round_…",
  "related_transaction_id": null,
  "player_id":         "p_42",
  "game_uuid":         "5e0a…",
  "session_id":        "sess_…",
  "amount":            0.50,
  "currency":          "USD",
  "occurred_at":       "2026-05-21T12:34:56.789Z" }

import crypto from 'node:crypto';
app.post('/wallet-callback', express.raw({ type: 'application/json' }), async (req, res) => {
  const sig = req.headers['x-signature'];
  const expected = crypto.createHmac('sha1', process.env.SOFTBET_SECRET)
    .update(req.body).digest('hex');
  if (sig !== expected) return res.status(401).json({ ok: false, error: 'bad_signature' });
  const evt = JSON.parse(req.body);
  const balance = await wallet.applyAndReturnBalance(evt);
  res.json({ ok: true, balance });
});

@app.post('/wallet-callback')
def cb():
    raw = request.get_data()
    expected = hmac.new(SOFTBET_SECRET.encode(), raw, hashlib.sha1).hexdigest()
    if request.headers.get('X-Signature') != expected:
        return {'ok': False, 'error': 'bad_signature'}, 401
    evt = request.get_json()
    bal = wallet.apply_and_return_balance(evt)
    return {'ok': True, 'balance': bal}

Idempotency

Always dedupe on transaction_id. If you've already processed that id, return the previously-computed balance without re-applying — never double-debit on a retry. We retry failed callbacks with the same transaction_id for up to 24 h.

Refund / rollback must be idempotent. If you receive a refund/rollback you have already applied, do not error — ack with { ok: true, balance } (the current balance). Returning a generic failure or a duplicate/conflict error makes us retry the refund indefinitely, so the player never settles. Key your refund idempotency on the refund's own transaction_id, not on the parent bet's related_transaction_id.

HMAC signing reference

The canonicalisation algorithm used for slot/gateway API requests. Source: /opt/bc/api/src/lib/sg-sign.js (canonicalQuery) + customer-hmac.js.

Algorithm

1. Collect all request params (query-string for GET, JSON body keys for POST/PUT/PATCH).
2. Add the four auth header values: X-API-Key, X-Timestamp, X-Nonce (NOT X-Sign).
3. Sort all keys lexicographically (case-sensitive).
4. URL-encode BOTH keys and values using application/x-www-form-urlencoded rules (PHP http_build_query / RFC 1738) — NOT RFC 3986. The one rule that bites most integrators: a space encodes to +, never %20. Concretely, the server does encodeURIComponent(v) then replaces %20→+ and percent-encodes ! * ' ( ) → %21 %2A %27 %28 %29. Unreserved - _ . ~ stay literal; : / etc. are percent-encoded.
5. Join as key=value&key=value&….
6. Compute HMAC-SHA1(canonical, secret).
7. Encode as lowercase hex.
8. Send as X-Sign.

Space → +: if any signed value contains a space (e.g. a campaign name or player_name), it MUST be encoded as +. Using %20 (RFC 3986 / Python quote()) yields a different canonical string and the request is rejected with 401 hmac_bad_signature.

Worked example

Suppose you're calling GET /api/v1/games?page=1&perPage=25 with:

• X-API-Key: bs_live_3f4a
• X-Timestamp: 1779400000
• X-Nonce: 9f7e1c8a
• secret: bs_live_S3CR3T

Canonical string (sorted by key):

X-API-Key=bs_live_3f4a&X-Nonce=9f7e1c8a&X-Timestamp=1779400000&page=1&perPage=25

Signature:

HMAC-SHA1(canonical, "bs_live_S3CR3T") = e4f8a92c1d…

Example with a space in a value — POST /api/v1/freespins/set with name=weekend promo. The space becomes + in the canonical string:

…&currency=EUR&freespin_bet=0.40&freespins_count=50&game_uuid=0b6e…&name=weekend+promo&player_id=p_42&…

Reference implementations

canon='X-API-Key=bs_live_3f4a&X-Nonce=9f7e1c8a&X-Timestamp=1779400000&page=1&perPage=25'
echo -n "$canon" | openssl dgst -sha1 -hmac "bs_live_S3CR3T" -hex | cut -d' ' -f2

import crypto from 'node:crypto';
const encode = v => encodeURIComponent(String(v))
  .replace(/%20/g, '+')                       // form-encoding (RFC 1738): space → +
  .replace(/[!*'()]/g, c => '%' + c.charCodeAt(0).toString(16).toUpperCase());
function sign(params, secret) {
  const keys = Object.keys(params).sort();
  // encode BOTH keys and values
  const canon = keys.map(k => `${encode(k)}=${encode(params[k])}`).join('&');
  return crypto.createHmac('sha1', secret).update(canon).digest('hex');
}

import hmac, hashlib
from urllib.parse import quote_plus          # quote_plus → space becomes '+'
def sign(params, secret):
    # encode BOTH keys and values; quote_plus matches the server's form-encoding
    canon = '&'.join(
        f'{quote_plus(str(k), safe="")}={quote_plus(str(params[k]), safe="")}'
        for k in sorted(params)
    )
    return hmac.new(secret.encode(), canon.encode(), hashlib.sha1).hexdigest()

Common signing pitfalls

• Encoding — application/x-www-form-urlencoded (RFC 1738), NOT RFC 3986. Space → + (use JS encodeURIComponent(v).replace(/%20/g,'+') or Python quote_plus(v, safe='') — plain quote() emits %20 and will fail). Also encode !*'().
• Sort order — case-sensitive lexicographic. X-API-Key sorts before page because 'X' < 'p' in ASCII.
• Header inclusion — include X-API-Key, X-Timestamp, X-Nonce; do NOT include X-Sign (chicken-and-egg).
• Number coercion — coerce all values to strings before encoding; integers vs strings produce different signatures.
• Body vs query — for POST with a JSON body, sign the body's top-level scalar fields. Nested objects/arrays are excluded from the canonical and must be hashed separately if you need their integrity protected.

Changelog

Documentation revisions and notable API changes. Endpoint deprecations are announced here 90 days before removal.

2026-05-21

• Initial reference build. 100+ endpoints across auth, slots, freespins, billing, dashboard, gateway, hosting (12 sub-areas), and sportsbook.
• Whitelabel rebrand: dashboard + admin UI no longer expose the upstream slot-provider name. Public contract unchanged (route paths, callback shape, HMAC algorithm all preserved).
• Hosting Phase F4.5 daily digest documented under Alerts & notifications.