Game Launch

Operator → Beexar

Beexar provides two launch endpoints: one for real-money sessions and one for demo sessions with virtual balance.

---

Real-Money Launch

POST {GATEWAY_URL}/api/v1/softswiss/launcher/real

Headers

Header	Value
Content-Type	application/json
X-REQUEST-SIGN	HMAC-SHA256 signature of the request body (64 hex chars)

Body

Field	Type	Required	Description
casino_id	string	Yes	Operator slug (e.g. "casinoxyz")
game	string	Yes	Game slug (e.g. "dice", "slots", "crash")
account	object	Yes	Player account details
account.id	string	Yes	Player ID on your side (max 255 chars)
account.currency	string	Yes	Currency code (e.g. "USD", "EUR", or custom "CUSTOM_TOKEN")
account.nickname	string	No	Player nickname (may be displayed in multiplayer games)
account.country	string	No	ISO 3166-1 alpha-2 country code
locale	string	No	UI language (default: "en")
ip	string	No	Player IP address (IPv4 or IPv6)
client_type	string	No	"desktop" or "mobile"
urls.return_url	string	No	URL to redirect player after game
urls.deposit_url	string	No	URL for player to make a deposit
jurisdiction	string	No	Country code for regulatory restrictions (e.g. "DE", "CA-ON")
session_id	string	No	Your session identifier (UUID) for round tracking
session_payload	string	No	Opaque string (max 4096 chars) echoed back in every wallet callback

Example

{
  "casino_id": "casinoxyz",
  "game": "dice",
  "account": {
    "id": "player_123",
    "currency": "USD",
    "nickname": "LuckyPlayer"
  },
  "locale": "en",
  "client_type": "desktop",
  "urls": {
    "return_url": "https://casino.example.com/lobby",
    "deposit_url": "https://casino.example.com/deposit"
  }
}

Response (200 OK)

{
  "launch_url": "https://games.beexar.com/dice/casinoxyz/dice-game?token=a1b2c3d4e5f6..."
}

Field	Type	Description
launch_url	string	Full URL to launch the game (embed in iframe or redirect)

---

Demo Launch

POST {GATEWAY_URL}/api/v1/softswiss/launcher/demo

Demo sessions use a virtual balance stored in Beexar — no wallet callbacks are triggered during demo play.

Two Modes

Mode	Authentication	Use Case
Operator mode	X-REQUEST-SIGN with real HMAC signature	Casino backend launches demo for a known player
Frontend mode	X-REQUEST-SIGN: 0000...0000 (64 zeros)	Game lobby or website launches anonymous demo

Body

Field	Type	Required	Description
casino_id	string	Yes	Operator slug
game	string	Yes	Game slug
currency	string	No	Currency for virtual balance (default: "USD")
balance	string	No	Initial virtual balance (default: "10000")
player_id	string	No	Anonymous player ID (for frontend mode, stored in localStorage)
locale	string	No	UI language

Example (Operator Mode)

{
  "casino_id": "casinoxyz",
  "game": "slots",
  "currency": "USD",
  "balance": "5000"
}

Example (Frontend Mode)

curl -X POST https://gateway.beexar.com/api/v1/softswiss/launcher/demo \
  -H "Content-Type: application/json" \
  -H "X-REQUEST-SIGN: 0000000000000000000000000000000000000000000000000000000000000000" \
  -d '{
    "casino_id": "casinoxyz",
    "game": "dice",
    "player_id": "anon_abc123"
  }'

Response (200 OK)

{
  "launch_url": "https://games.beexar.com/dice/casinoxyz/dice-game/demo?token=demo_a1b2c3...&balance=10000&currency=USD"
}

Note

Demo sessions have a 30-minute TTL with sliding window. Active players get their session automatically extended. No wallet callbacks are made during demo play — all balance operations happen in Beexar’s virtual wallet.

---

Error Responses

Both endpoints answer with the SoftSwiss Twirp envelope. Only two values ever appear in code — invalid_argument and internal — and the specific meaning is carried by meta.api_code. Branch on meta.api_code, never on code.

HTTP	code	meta.api_code	Meaning
403	invalid_argument	403	Invalid request signature
400	invalid_argument	400	Malformed body or schema validation failure — meta.api_message names the offending field
400	invalid_argument	404	casino_id not found, or it does not match the operator
400	invalid_argument	405	Game is not available to your casino
400	invalid_argument	410	Casino is disabled
400	invalid_argument	420	This endpoint is not available for the operator’s integration type
400	invalid_argument	154	Currency not allowed — also returned when the currency needs an active feature subscription, or when bet limits are not configured for it. See Custom Currencies
500	internal	500	Internal error, or a temporarily unavailable game-availability check. Retryable

Caution

A signature mismatch is the one case that answers HTTP 403. Every other client error is HTTP 400. There is no unauthenticated, permission_denied or not_found value in code — those are not part of this contract.

{
  "code": "invalid_argument",
  "msg": "invalid request signature",
  "meta": {
    "api_code": "403",
    "api_message": "invalid request signature"
  }
}

---

Embedding the Game

Desktop: iframe

<iframe
  src="https://games.beexar.com/dice/casinoxyz/dice-game?token=a1b2c3d4..."
  style="width: 100%; height: 100vh; border: none;"
  allow="autoplay"
  sandbox="allow-scripts allow-same-origin allow-popups"
></iframe>

Mobile: Redirect

For mobile browsers, redirect the player directly to the launch_url:

if (isMobile()) {
  window.location.href = launchUrl;
} else {
  document.getElementById('game-frame').src = launchUrl;
}

Device	Strategy	Implementation
Desktop	iframe	Embed launch_url in <iframe>
Mobile	Redirect	Redirect to launch_url directly
Auto	Detect	Check User-Agent or use client_type field

---

curl Example (Real-Money)

BODY='{"casino_id":"casinoxyz","game":"dice","account":{"id":"player_123","currency":"USD"}}'
SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "your_auth_token" | awk '{print $2}')

curl -X POST https://gateway.beexar.com/api/v1/softswiss/launcher/real \
  -H "Content-Type: application/json" \
  -H "X-REQUEST-SIGN: $SIGNATURE" \
  -d "$BODY"

---

Game URL Format

The launch_url follows this pattern:

Mode	URL Format
Real	https://games.beexar.com/{game_type}/{casino_slug}/{game_slug}?token={session_token}
Demo	https://games.beexar.com/{game_type}/{casino_slug}/{game_slug}/demo?token={demo_token}&balance={amount}&currency={code}

The game frontend extracts the token from the URL and uses it for all subsequent API calls to Beexar.

---

Session Lifecycle

Once a session is created:

1. The session is valid for 30 minutes with a sliding window — active players get auto-extended
2. Beexar sends wallet requests (/balance, /betwin, /rollback, /finish) to your callback URLs (real-money only)
3. When the session expires or the player closes the game, open rounds are finalized
4. If return_url was provided, the player is redirected there