S2S Protocol Overview

The S2S (Server-to-Server) protocol is Predictu's callback-based integration system for casino operators. It follows the same architectural pattern used by established gaming aggregators like Betby and SoftSwiss - Predictu calls the operator's backend for every wallet operation, and the operator remains the sole owner of player balances at all times.

How It Works

When a player interacts with the Predictu prediction market widget embedded on the casino site, every financial operation triggers an outbound HTTP POST from Predictu to the operator's registered callback_url. The operator processes the request, debits or credits the player's wallet, and returns a response.

  Player (Browser)         Predictu Platform           Operator Backend
  ─────────────────        ──────────────────          ──────────────────
        │                         │                          │
        │  Click "Buy YES"        │                          │
        ├────────────────────────►│                          │
        │                         │                          │
        │                         │  POST /api/callback      │
        │                         │  Authorization: Bearer   │
        │                         │  { method: "BET_MAKE",   │
        │                         │    params: { amount,     │
        │                         │    player_id, bet } }    │
        │                         ├─────────────────────────►│
        │                         │                          │
        │                         │  { status: "OK",         │
        │                         │    balance: 95000,       │
        │                         │    transaction_id }      │
        │                         │◄─────────────────────────┤
        │                         │                          │
        │  Trade confirmed +      │                          │
        │  balance updated        │                          │
        │◄────────────────────────┤                          │
        │                         │                          │

Request Envelope

Every S2S callback from Predictu uses the same top-level JSON envelope. Themethod field determines the type of operation, and the paramsobject contains method-specific data.

{
  "method": "BET_MAKE",
  "timestamp": "2026-03-19T14:30:00.000Z",
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "operator_id": "op_abc123",
  "params": {
    "player_id": "player_456",
    "transaction_id": "tx_789",
    "amount": 5200,
    "currency": "USD",
    "bet": {
      "market_id": "mkt_001",
      "market_title": "Will Bitcoin exceed $100k by June 2026?",
      "outcome": "yes",
      "odds": 1.92,
      "shares": 100,
      "execution_price": 52
    }
  }
}

Envelope Fields

Response Envelope

The operator must respond with a JSON object containing at minimum a status field. Additional fields depend on the method.

{
  "status": "OK",
  "balance": 95000,
  "transaction_id": "op-tx-abc-123"
}

Response Fields

Response Status Codes

Predictu recognizes five standard status codes in the response. Your callback endpoint must return one of these in the status field.

Monetary Amounts - Subunits

All monetary values in the S2S protocol are expressed in subunits (cents). This avoids floating-point precision issues and is standard practice in payment systems.

// Conversion helpers (reference implementation)
function toSubunits(dollars) {
  return Math.round(dollars * 100);
}

function fromSubunits(subunits) {
  return Math.round(subunits) / 100;
}

// Examples:
toSubunits(1.00)    // → 100
toSubunits(52.00)   // → 5200
fromSubunits(100)   // → 1.00
fromSubunits(5200)  // → 52.00

Supported Methods

The S2S protocol defines eight callback methods covering the full lifecycle of a prediction market bet - from placement through settlement or early sale.

Bet Lifecycle

A prediction market bet follows one of three paths after placement. Every path starts with BET_MAKE and ends with exactly one terminal callback.

Path A: Winning Bet

BET_MAKE (debit $52)  →  market resolves YES  →  BET_WIN (credit $100)
    Player profits: $100 - $52 = $48

Path B: Losing Bet

BET_MAKE (debit $52)  →  market resolves NO  →  BET_LOST (amount: 0)
    Player loses: $52 (already debited)

Path C: Early Sale

BET_MAKE (debit $52)  →  price moves to 65¢  →  BET_SELL (credit $63.40)
    Player profits: $63.40 - $52.00 = $11.40

Path D: Market Void / Refund

BET_MAKE (debit $52)  →  market voided  →  BET_REFUND (credit $52)
    Player is made whole: $0 net impact

Path E: Failed Trade (Rollback)

BET_MAKE (debit $52)  →  trade recording fails  →  BET_ROLLBACK (credit $52)
    Player is made whole: $0 net impact (compensating transaction)

Retry Behavior

When a callback fails due to a network error, HTTP 5xx response, or ERROR status, Predictu automatically retries with exponential backoff.

Attempt 1:  immediate
Attempt 2:  after 1,000ms   (1s)
Attempt 3:  after 2,000ms   (2s)
Attempt 4:  after 4,000ms   (4s)

Total max wait: ~7 seconds before the transaction is marked as failed.

Request Headers

Every S2S callback includes these HTTP headers:

Operator Configuration

Each operator has an S2S configuration record stored in Predictu's operator_api_configtable. This is managed via the God Mode admin dashboard during operator onboarding.

Transaction Recording

Every S2S callback is recorded in two tables for full auditability:

s2s_transactions

The primary transaction record. One row per callback attempt. Tracks the full lifecycle from pending through success or failed.

s2s_callback_log

Detailed HTTP-level log of every callback attempt. Includes the full request body, response status code, response body, and round-trip duration. Used for debugging and operator support.

Next Steps

• Callback Methods - Deep dive into each method's request/response schema
• JWT Authentication - Signature verification, key management, and replay prevention
• Reference Implementation - Working Express.js casino demo with SQLite wallets
• Trade Execution - How the trade executor orchestrates S2S callbacks