Launch & Wallet

This page connects the reference surfaces into one story: how a player’s launch URL becomes a live WebSocket session, and how a single bet moves money through the platform to the operator and back. Each step links to the reference page with the exact payloads.

The whole journey

sequenceDiagram
  participant P as Player Browser
  participant LN as Cloud1x2 Launcher
  participant GS as Game Service
  participant PL as Platform
  participant OP as Partner Operator

  Note over P,OP: 1. Launch
  P->>LN: GET launch URL (gameId, token, currency, customer, ...)
  LN->>GS: proxy the iframe content
  GS-->>P: game SPA + assets

  Note over P,OP: 2. Handshake
  P->>GS: WebSocket connect (auth + launchQs)
  GS->>PL: POST /internal/verify-launch
  PL->>OP: authenticate (real mode only)
  OP-->>PL: ok + balance
  PL-->>GS: session (currency, balance, demo, limits, locale)
  GS-->>P: emit 'session' + current round

  Note over P,OP: 3. Bet
  P->>GS: placeBet { amount, ... }
  GS->>PL: POST /internal/wallet/debit (real mode)
  PL->>OP: signed debit
  OP-->>PL: ok + new balance
  PL-->>GS: { httpOk, balance }
  GS->>PL: POST /internal/consolidated/tx (open ledger)
  GS-->>P: bet_accepted

  Note over P,OP: 4. Settle
  GS->>GS: round closes (win / lose)
  GS->>PL: POST /internal/wallet/credit (win > 0, or 0 on loss)
  PL->>OP: signed credit
  GS->>PL: POST /internal/consolidated/tx/settle
  GS-->>P: round_close + outcome

1. Launch

An operator embeds a Cloud1x2 launch URL in an iframe on its own site. The launcher proxies that request to the game service, which serves the game SPA and its assets. The player never sees Cloud1x2 directly — only the operator’s iframe.

The launch URL carries gameId, token, currency, customer, organizationId, trader, and demo. These are forwarded, unchanged, into the WebSocket handshake.

2. Handshake → session

On WebSocket connect, the game service forwards the launch query to POST /internal/verify-launch. This single round-trip decides everything about the session:

• whether the launch is allowed (partner not suspended, game and currency allowed),
• whether it is real or demo,
• the starting balance, currency, locale, and bet limits.

In real mode the platform calls authenticate on the operator wallet to validate currency and read the balance. On success, the service stores the returned session and emits session to the browser, followed by the current round.

→ Launch Verification · Gameplay Protocol

3. A bet moves money

When the player sends placeBet, the game service validates server-side (round open, amount within limits, sufficient balance, no duplicate bet), then:

1. Debit — POST /internal/wallet/debit (real mode only). The platform signs and relays it to the operator. A response with httpOk: false means the operator refused: the bet is rejected and no ledger row is written.
2. Open the ledger — POST /internal/consolidated/tx with status: open, keyed by the bet UID (the idempotency key).
3. Accept — add the bet to the engine and emit bet_accepted.

Demo mode skips the entire wallet half; the ledger row is still written when save_demo_bets is set.

→ Wallet API · Config + Ledger · Bet UID Format

4. Settlement

When the round closes, the game service settles each bet:

Outcome	Wallet call	Ledger settle
Win	credit with amount = payout	status: won, winAmount
Loss	credit with amount = 0 (a settle signal, no money)	status: lost, winAmount: 0
Round crash	rollback (reverse the debit)	status: rolled_back

Every bet has a symmetric open (debit) and close (credit) pair to the operator — even a loss sends a zero-amount credit, which keeps operator reconciliation consistent. The outcome is emitted to the browser as round_close.

→ Wallet API — ledger coordination

The two hard rules

• A game service never talks to the operator directly. Every money movement goes Service → Platform → Operator; the platform signs, retries, and translates.
• The financial truth lives in the platform ledger. A service may keep its own snapshot, but the ledger (keyed by bet UID, idempotent) is authoritative.

With launch and wallet understood end to end, the Quickstart builds a minimal version of this exact loop.