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.

Webhook Integration

When webhook mode is enabled, Solex sends HTTP POST requests to your configured webhook URL for every financial event. This applies to both Prediction Markets and TraderHero.

Webhook Events

Event	When	Game Types
deposit	Player places a bet — deduct from balance	Both
win	Player wins — credit the payout	Both
refund	Market cancelled or event voided — return the bet	Prediction Markets

Webhook Payload

{
  "event": "deposit" | "win" | "refund",
  "transaction_id": "uuid-v4",       // Unique per webhook — use for idempotency
  "timestamp": "2026-03-02T12:00:00Z",
  "casino_id": "partner-uuid",
  "user_id": "external-user-id",
  "amount": 100.00,
  "currency": "USD",                  // Currency from partner config
  "metadata": {
    // Prediction Markets:
    "market_id": "uuid",
    "market_title": "...",
    "bet_id": "uuid",
    "outcome": "YES",

    // TraderHero:
    "game_type": "jackpot",
    "round_id": "uuid",
    "bet_amount": 25,
    "payout_amount": 50,
    "target_rtp": 90
  }
}

Expected Response

{
  "status": "success" | "failure",
  "balance": 1400.00,              // Updated balance after operation
  "reason": "insufficient_balance" // Only on failure
}

Idempotency

Every webhook includes a unique transaction_id. Your server should use this to ensure idempotent processing — if you receive the same transaction_id twice (e.g. due to retries), return the same response without double-processing.

Security Headers

X-Solex-Signature: sha256=<hmac-hex>

X-Solex-Timestamp: <unix-seconds>

X-Solex-Event: deposit | win | refund

X-Solex-Transaction-Id: <uuid>

Verify signatures using HMAC-SHA256: HMAC(secret, "{timestamp}.{body}"). The signing key is your webhook_signing_key (or api_secret as fallback).

Retry Policy

Failed webhooks are retried up to 4 times with exponential backoff: 5s, 30s, 2min. Each retry uses the same transaction_id but a fresh signature.

JWT Authentication

JWT tokens authenticate players for the webhook flow. The same JWT system works for both Prediction Markets and TraderHero. Configure either a shared HMAC secret or a verification URL on your partner settings.

JWT Payload

{
  "sub": "external_user_id",       // Required: your user ID
  "name": "Player Display Name",   // Optional: shown in UI
  "iat": 1709400000,
  "exp": 1709403600,
  "casino_id": "partner-uuid"      // Your partner ID
}

Verification Endpoint

POST /api/v1/casino/auth/verify-jwt
Content-Type: application/json

{
  "jwt": "<token>",
  "casinoId": "<partner-uuid>"
}

// Success response
{
  "valid": true,
  "user": {
    "id": "internal-uuid",
    "displayName": "Test Player",
    "externalUserId": "external_user_id"
  },
  "session": {
    "token": "solex_session_...",
    "expiresAt": "2026-03-02T13:00:00Z"
  }
}

Passing JWT to Iframes

Prediction Markets

iframe.contentWindow.postMessage({ type: 'CASINO_SESSION_REFRESH', version: '1.0', timestamp: Date.now(), payload: { jwt: jwtToken } }, '*')

Posts CASINO_SESSION_REFRESH directly to the iframe

TraderHero

iframe.postMessage({ type: 'jackpot_settings', jwt: token }, '*')

JWT passed alongside balance/settings messages

Currency Support

Currency is configured per partner. All bets, payouts, and webhook amounts use the partner's configured currency.

// Set during partner registration
POST /api/v1/casino/auth/register
{
  "name": "My Casino",
  "defaultCurrency": "EUR",    // USD, EUR, GBP, BTC, etc.
  ...
}

// Or update later
PATCH /api/v1/casino/admin/config
Headers: X-Casino-Key: your_key
{
  "defaultCurrency": "BTC"
}

// Currency flows through to:
// - Webhook payloads (currency field)
// - Transaction records
// - Prediction Markets postMessage (CASINO_INIT payload.balance.currency)
// - TraderHero (jackpot round currency field)