Integration Docs

Everything you need to embed Solex games into your casino platform — Prediction Markets and TraderHero.

Interactive REST API reference.

Live Prediction Markets demo.

Live TraderHero jackpot demo.

IGSP Integration

The iGaming Standard Protocol (IGSP) is an open standard for game-provider-to-platform communication. Casino platforms that support IGSP can integrate Solex games without implementing proprietary webhooks or the postMessage protocol.

1. Register

2. Discover & Launch

Call the Provider API to list games, then create a player session. Embed the returned launch URL in an iframe.

3. Handle Hooks

Expose a single hooks endpoint. Solex calls it with action: balance | bet | win | refund to manage the player’s wallet.

HMAC-SHA256 Authentication

All IGSP API calls use HMAC-SHA256 signatures with a shared key pair. The same scheme applies in both directions — platform to Solex and Solex to platform.

Required Headers (every request)

Header	Value	Example
Authorization	Bearer <api_key>	Bearer gp_live_a14f22...
X-Timestamp	UTC ISO-8601	2025-10-17T12:03:41Z
X-Signature	HMAC-SHA256 hex	7b9a3d2c7f1c9e4a...

Signature Formula

HMAC_SHA256(secret_key, raw_request_body + X-Timestamp)

Use the exact JSON string without reformatting. For GET requests with no body, sign an empty string + timestamp. Reject requests where the timestamp differs by more than 5 minutes. Use constant-time comparison for signature verification.

Partner Registration

POST /api/v1/casino/auth/register Content-Type: application/json X-Casino-Key: <admin_key> { "name": "Acme Casino", "integrationMode": "igsp", "igspHooksUrl": "https://api.acme-casino.com/webhooks/igsp/v1/hooks", "defaultCurrency": "USD" }

The response includes your IGSP key pair:

{ "id": "uuid", "name": "Acme Casino", "apiKey": "ck_...", "apiSecret": "cs_...", "integrationMode": "igsp", "igspApiKey": "gp_live_a14f22...", "igspSecretKey": "91b2c7a4aadb48b62e...", "igspHooksUrl": "https://api.acme-casino.com/webhooks/igsp/v1/hooks" }

igspApiKey — public identifier, sent in the Authorization header.
igspSecretKey — shared HMAC secret. Never expose in logs, client code, or repositories.

Provider API

All Provider API endpoints require HMAC authentication.

GET /igsp/v1/providers

Returns Solex provider metadata. Supports cursor pagination via cursor, limit, and updated_after query params.

{ "data": [{ "id": "00000000-0000-4000-a000-000000000001", "name": "Solex Gaming", "slug": "solex", "currencies": ["USD", "EUR", "GBP", "BRL", "TRY"], "restricted_countries": [], "images": [], "min_age": 18, "min_kyc_level": "none" }], "cursor": { "next": null, "previous": null }, "meta": { "limit": 50, "returned": 1, "has_more": false } }

GET /igsp/v1/games

Returns the game catalog. Use updated_after for delta syncs.

{ "data": [ { "id": "...", "slug": "prediction-markets", "name": "Prediction Markets", "status": "active", "categories": ["other"], "rtp": 96, ... }, { "id": "...", "slug": "traderhero-jackpot", "name": "TraderHero Jackpot", "status": "active", "categories": ["jackpot"], "rtp": 90, ... } ], "cursor": { "next": null, "previous": null }, "meta": { "limit": 50, "returned": 2, "has_more": false } }

POST /igsp/v1/sessions

Creates a player session and returns a game launch URL.

Field	Required	Type	Notes
game_id	Yes	string	prediction-markets or traderhero-jackpot
player_id	Yes	string	Stable player identifier
player_name	Yes	string	Display name for in-game HUD
currency	Yes	string	ISO-4217 (e.g. USD, EUR)
session_id	Yes	string	Platform-issued unique reference
balance	Yes	number	Current player balance
device	No	string	desktop or mobile (default: mobile)
return_url	No	string	Post-game redirect URL
language	No	string	ISO-639-1 (default: en)
is_demo	No	boolean	Demo mode flag

Example request:

POST /igsp/v1/sessions Authorization: Bearer gp_live_a14f22... X-Timestamp: 2025-10-17T12:03:41Z X-Signature: 7b9a3d2c7f1c9e4a... { "game_id": "prediction-markets", "player_id": "player-912", "player_name": "LuckyFox", "currency": "EUR", "session_id": "sess-20250101-0001", "balance": 100.00, "device": "desktop", "return_url": "https://casino.example.com/lobby", "language": "en" }

Response (201 Created):

{ "url": "https://api.solex.games/embed/index.html?igsp_session=<session_uuid>" }

Embed this URL directly in an iframe. The player is redirected to the game and authenticated automatically. Sessions expire after 4 hours. Duplicate session_id values return 409 Conflict.

Wallet Hooks (Platform Endpoint)

Your platform must expose a single hooks endpoint at the URL you configured as igspHooksUrl. Solex sends HMAC-signed POST requests with action to manage the player’s wallet.

action: balance

Called when the game needs the player’s current balance.

Request

{ "action": "balance", "player_id": "player-912", "currency": "EUR", "session_id": "sess-20250101-0001" }

Response

{ "balance": 97.50 }

action: bet

Debit the player’s balance when they place a bet.

Request

{ "action": "bet", "player_id": "player-912", "amount": 2.50, "currency": "EUR", "game_id": "prediction-markets", "transaction_id": "bet-20250101-000045", "session_id": "sess-20250101-0001", "type": "bet", "round_id": "round-18", "finished": false }

Response

{ "balance": 95.00, "transaction_id": "plt-tx-845" }

action: win

Credit the player’s balance on a win or jackpot payout.

Request

{ "action": "win", "player_id": "player-912", "amount": 10.00, "currency": "EUR", "game_id": "prediction-markets", "transaction_id": "win-20250101-000045", "session_id": "sess-20250101-0001", "type": "win", "round_id": "round-18", "finished": true }

Response

{ "balance": 105.00, "transaction_id": "plt-tx-846" }

action: refund

Reverse a previous bet (e.g. trade execution failure or market cancellation).

Request

{ "action": "refund", "player_id": "player-912", "amount": 2.50, "currency": "EUR", "game_id": "prediction-markets", "transaction_id": "refund-20250101-000045", "session_id": "sess-20250101-0001", "type": "bet", "bet_transaction_id": "bet-20250101-000045", "finished": true }

Response

{ "balance": 107.50, "transaction_id": "plt-tx-847" }

Full Integration Flow

Register — POST /api/v1/casino/auth/register with integrationMode: "igsp". Store the returned igspApiKey and igspSecretKey.

Sync Games — GET /igsp/v1/games to populate your lobby.

Player Clicks Play — POST /igsp/v1/sessions with player details and current balance. Receive a launch URL.

Embed Iframe — Render the launch URL in an iframe. The game initializes automatically from the session.

Handle Hooks — Your hooks endpoint receives bet, win, refund, and balance calls. Verify the HMAC signature, process the wallet action, and return the new balance.

Session API (Embed-side)

These endpoints are called by the embed or your integration code during an active session. Routes marked Public do not require HMAC headers but do require X-Casino-Key: igsp_<sid> (the session token issued when the session was created).

GET /igsp/v1/sessions/:sessionId/state

Public. Called by igsp-init.js on iframe load to bootstrap the session. Returns full session state and partner config. Header: X-Casino-Key: igsp_<sid>.

GET /igsp/v1/sessions/:sessionId/balance

Public. Real-time balance fetched from the platform wallet adapter. Header: X-Casino-Key: igsp_<sid>.

POST /igsp/v1/sessions/:sessionId/bet

Public. Processes a bet placed inside the IGSP session. Debits the platform wallet via the configured hooks URL.

// ProcessBetDto body { "amount": 2.50, "marketId": "market-uuid", "outcome": "YES", // "YES" | "NO" "transactionId": "optional-platform-ref", "roundId": "optional-round-ref", "finished": false // optional }

POST /igsp/v1/sessions/:sessionId/cash-out/preview

Public. Returns the estimated cash-out value for an active bet without executing the cash-out. Body: { betId }.

// Response { "success": true, "betId": "bet-uuid", "available": true, "netCashOut": 1.85, "fee": 0.15, "fairValue": 2.00 }

POST /igsp/v1/sessions/:sessionId/cash-out

Public. Executes the cash-out for an active bet. Credits the platform wallet via the configured hooks URL. Body: { betId }.

// Response { "success": true, "netCredit": 1.85, "fee": 0.15, "transactionId": "tx-uuid", "balance": 101.85 }

Inbound Webhook & Demo Session

In addition to the outbound hooks that Solex calls on your platform, there is an inbound HMAC-protected route and a public demo-session route.

POST /igsp/v1/hooks

HMAC. Direction: platform → Solex. Your platform sends HMAC-signed POST requests to this endpoint when wallet events occur on your side. Solex reconciles these against active sessions. Body: IgspWebhookDto (action: 'balance' | 'bet' | 'win' | 'refund', player_id, currency, amount?, game_id?, transaction_id?, session_id?, type?, bet_transaction_id?, round_id?, finished?).

Note: this is the opposite direction to the wallet hooks documented in the “Wallet Hooks” section above — those are Solex → your platform; this one is your platform → Solex.

POST /igsp/v1/demo/sessions

Public. Creates a demo session without HMAC authentication. Same body as POST /igsp/v1/sessions (CreateSessionDto). Used by the website demo pages. Returns the same { "url": "..." } response (201 Created).

Live Demo

Try the IGSP flow in action. The demo pages for each game use IGSP sessions instead of the postMessage protocol. Click “Play Demo” on any game page to see:

An IGSP session is created via POST /igsp/v1/sessions
The returned launch URL is embedded in an iframe
The iframe self-initializes using igsp-init.js — no postMessage from the parent
Wallet operations (bets, wins, refunds) flow through server-side IGSP hooks

Prediction Markets Demo TraderHero Demo

Setup: To run the demo locally, register an IGSP partner and set the IGSP_API_KEY and IGSP_SECRET_KEY environment variables in the website’s .env.

IGSP vs postMessage

Aspect	IGSP	postMessage
Auth	HMAC-SHA256 server-side	API key via postMessage
Session init	iframe self-initializes from session URL	Parent sends CASINO_INIT message
Wallet ops	Server-side hooks (bet/win/refund)	Client-side postMessage (SOLX_BET_REQUEST → CASINO_BET_RESPONSE)
Balance	Managed by platform wallet hooks	Managed by parent window
Client implementation	None required	message handlers in your host page (no library)
Integration effort	Implement one hooks endpoint	Implement postMessage handlers + webhooks

Error Handling

Status	When
400	Invalid request body, unsupported currency, or missing required fields
401	Missing/invalid Authorization header or HMAC signature mismatch
409	Duplicate session_id (already exists)
410	Session expired or closed
502	Platform hooks endpoint unreachable

Sessions expire after 4 hours. When a session expires, create a new one via POST /igsp/v1/sessions.