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", "candy-cash")
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 of the game’s Home (lobby) button. Any scheme://host… (https://…, or a native app’s myapp://lobby); without it the game shows no Home button
urls.deposit_url	string	No	URL of the game’s Deposit button and low-balance prompt, same shape; without it the game shows no Deposit button
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": "plinko",
  "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 stays valid while the player is active: it expires 10–30 minutes after the last action, and 24 hours after launch at the latest (see Session Flow)
2. Beexar sends wallet requests (/balance, /betwin, /rollback, /finish) to your callback URLs (real-money only)
3. After expiry the token is refused with INVALID_SESSION; the game shows a “session expired” screen and the player relaunches from your lobby (a new session). Expiry itself sends no wallet request — rounds still open are completed by the game server like any other round
4. If return_url was provided, the game’s Home menu leads there; without it there is no Home button. deposit_url works the same way for the Deposit button and the low-balance prompt
5. Every wallet request of a round carries the session_id of the session that opened the round — also when the player finishes it after relaunching the game from your lobby