Operator Integration Guide

Integrate Velo Games into your platform via iframe. The full flow takes under an hour to implement.

Quick Start

<!-- 1. Your backend calls our Launch API to get a session -->
<!-- POST https://your-rgs-host/v1/game/launch -->

<!-- 2. Embed the game -->
<iframe
  src="https://velo.games/game?gsid=YOUR_GSID"
  width="100%" height="100%"
  style="border: none; min-height: 100vh;"
  allow="fullscreen"
></iframe>

<!-- 3. Listen for events -->
<script>
window.addEventListener("message", (e) => {
  if (!e.data.type?.startsWith("VELO_")) return;
  console.log(e.data.type, e.data);
});
</script>

---

Architecture Overview

Two APIs, opposite directions:

API	Direction	Purpose
Game Launch API	Operator → Velo	Create a game session, get iframe URL
Seamless Wallet API	Velo → Operator	Debit/credit player balance during gameplay
Reconciliation API	Operator → Velo	Query round transactions and game history

---

1. Authentication

All API calls are authenticated with HMAC-SHA256.

Your operator account includes:

• api_key — public identifier
• api_secret — used to sign requests (never sent over the wire)

Game Launch Signing

The Game Launch API uses a message-based signature:

message = "api_key|player_id|timestamp"
signature = HMAC-SHA256(api_secret, message)

Wallet API Signing

The Seamless Wallet API uses body-based signatures. Every request to your wallet includes:

Header	Value
X-Api-Key	Your operator API key
X-Sign	HMAC-SHA256(request_body, api_secret)
X-Game-Id	e.g. velo_btc_5min

---

2. Game Launch API

POST /v1/game/launch

Request:

Field	Type	Required	Description
api_key	string	✅	Your operator API key
player_id	string	✅	Unique player identifier in your system
currency	string		Player currency (default: USD)
language	string		UI language (default: en)
return_url	string		URL to redirect when player exits
signature	string	✅	HMAC-SHA256 signature
timestamp	string	✅	Unix timestamp (must be within ±5 minutes of server time)
game_id	string		Game to launch (default: btc_5min)
reality_check_timeout	integer		Minutes between UKGC reality check dialogs
history_url	string		Operator URL for player wagering history (shown in reality check)
regulation_type	integer		Jurisdiction ID: 2=UK, 3=Italy, 6=Sweden, 7=NJ

Response:

{
  "launch_url": "https://velo.games/game?gsid=a1b2c3d4-...",
  "gsid": "a1b2c3d4-...",
  "session_token": "abc123def456...",
  "expires_in": 3600
}

Error codes: INVALID_API_KEY, INVALID_SIGNATURE, TIMESTAMP_EXPIRED, AUTH_FAILED, SESSION_CREATE_FAILED, DB_UNAVAILABLE

Flow:

1. Velo verifies the operator by api_key
2. Velo validates timestamp freshness (rejects requests >5 minutes old)
3. Velo verifies the HMAC signature
4. Velo authenticates the player via your wallet's /wallet/authenticate endpoint
5. Velo creates a game session (1-hour TTL) and returns a gsid

---

3. iframe Embedding

Load the launch_url in an iframe:

<iframe
  id="velo-game"
  src="https://velo.games/game?gsid=YOUR_GSID"
  width="100%"
  height="100%"
  style="border: none; min-height: 100vh;"
  allow="fullscreen"
></iframe>

Mobile

The game is fully responsive. The betting bar uses position: fixed relative to the iframe viewport, so it works correctly inside iframes on mobile devices.

Recommended iframe attributes

• allow="fullscreen" — enables fullscreen mode
• style="border: none" — removes default iframe border
• min-height: 100vh — ensures the game fills the viewport

---

4. postMessage Events

The game communicates with the parent page via window.postMessage.

Game → Operator

Event	When	Payload
VELO_READY	Game loaded	{ gsid }
VELO_BET_PLACED	Bet confirmed (debit)	{ betId, side, stake, odds, balance }
VELO_BET_SETTLED	Bet closed (credit)	{ betId, result, payout, balance }
VELO_ROUND_RESULT	Round settles	{ result, pnl }
VELO_BALANCE_UPDATE	Any balance change	{ balance }

Bet Lifecycle

Every VELO_BET_PLACED (debit) will always be followed by exactly one VELO_BET_SETTLED (credit). The result field in VELO_BET_SETTLED is one of:

• "win" — player won, payout = stake × odds
• "loss" — player lost, payout = 0
• "cashout" — player cashed out early, payout = cashout value

This 1:1 mapping enables clean ledger reconciliation.

Operator → Game

Event	Payload	Purpose
VELO_CLOSE	—	Close the game session
VELO_PAUSE	—	Pause gameplay (AML/fraud/responsible gaming)
VELO_RESUME	—	Resume gameplay after pause
VELO_BALANCE_UPDATE	{ balance }	Notify game of external deposit/withdrawal

const iframe = document.getElementById('velo-game');

// Close the game
iframe.contentWindow.postMessage({ type: 'VELO_CLOSE' }, '*');

// Pause for AML flag
iframe.contentWindow.postMessage({ type: 'VELO_PAUSE' }, '*');

// Resume after clearing
iframe.contentWindow.postMessage({ type: 'VELO_RESUME' }, '*');

// Push external deposit
iframe.contentWindow.postMessage({ type: 'VELO_BALANCE_UPDATE', balance: 2500.00 }, '*');

---

5. Seamless Wallet API

During gameplay, Velo calls your wallet endpoints to debit and credit player balances.

See the full Wallet API Reference for:

• POST /wallet/authenticate — Authenticate player session
• POST /wallet/debit — Debit player balance (bet placement)
• POST /wallet/credit — Credit player balance (win/cashout)
• POST /wallet/rollback — Reverse a failed transaction
• POST /wallet/balance — Return player balance
• POST /wallet/end_round — Signal round closure

All wallet calls include HMAC-SHA256 signatures via the X-Sign header for verification.

---

6. Reconciliation & History

See the full Reconciliation API Reference for:

• POST /v1/reconciliation/round — Query all wallet transactions for a round
• POST /v1/history — Query round outcome and all bets

---

7. Testing

Certification Sandbox

Set WALLET_MODE=sandbox to run the RGS with an in-memory wallet that pre-seeds 5 test players with $10,000. The sandbox supports configurable error injection for testing your error handling resilience.

See the full Sandbox & Testing guide for structured certification phases.

Live Integration Demo

Visit velo.games/integrate to see a working iframe integration with real-time event logging.

---

Support

Questions? Contact us at hi@velo.games.