Slot Machine API

RESTful API for slot machine simulation

Overview

The Slot Machine API provides two main endpoints for interacting with a fully-featured slot machine game engine. The API supports both single spins for interactive gameplay and bulk simulations for statistical analysis.

Base URL: /slot/api/

Response Format: JSON (spin endpoint) and Server-Sent Events (simulate endpoint)

🎯 Key Features

Real-time Progress: Progress events every 2,500 spins with partial statistics
Stoppable Simulations: Close the connection anytime to stop and keep partial results
Full Analytics: Complete simulations return detailed analytics (biggest wins, bonus rounds, etc.)
Keepalive Mechanism: Prevents timeouts during long simulations
Connection Monitoring: Backend detects disconnections and stops processing immediately

Game Features

5 Reels x 3 Rows: Classic slot machine layout with 15 visible symbols
10 Paylines: Horizontal, diagonal, and zigzag patterns
8 Symbols: 🍒 🍋 🍊 🍇 🍉 ⭐ 💎 🎰
Bonus Feature: 3+ scatter symbols (🎰) trigger 15 free spins with up to 5x multiplier
Max Win Cap: 5000x bet amount (e.g., €5,000 at €1 bet, €500,000 at €100 bet)
Target RTP: ~95%

GET /api/spin.php

Execute a single spin and return the results immediately.

/slot/api/spin.php?bet=1&multiplier=1

Query Parameters

Parameter	Type	Required	Description
bet	float	No	Bet amount per spin (0.10 to 100). Default: 1
multiplier	integer	No	Bonus round multiplier (1-5). Default: 1

Response (JSON)

{
  "reels": [
    ["🍒", "🍋", "🍊"],
    ["🍇", "🍉", "⭐"],
    ["💎", "🎰", "🍒"],
    ["🍋", "🍊", "🍇"],
    ["🍉", "⭐", "💎"]
  ],
  "bonus": {
    "triggered": false,
    "scatters": 1
  },
  "win": 0,
  "winningLines": [],
  "maxWinCapped": false,
  "uncappedWin": 0
}

Response Fields

Field	Type	Description
reels	array[][]	5x3 grid of symbols representing the final reel positions
bonus	object	Bonus round information (triggered, scatters, freeSpins, multiplier)
win	float	Total win amount (after max win cap applied)
winningLines	array	Array of winning paylines with symbol, matches, and payout
maxWinCapped	boolean	True if win exceeded max win cap (5000x bet)
uncappedWin	float	Win amount before max cap applied

Response:

GET /api/simulate.php

Execute a bulk simulation with real-time progress updates via Server-Sent Events (SSE).

/slot/api/simulate.php?spins=1000000&bet=1

Query Parameters

Parameter	Type	Required	Description
spins	integer	No	Number of spins to simulate. Default: 1,000,000
bet	float	No	Bet amount per spin (0.10 to 100). Default: 1

Note: This endpoint returns Server-Sent Events (SSE). Use EventSource in JavaScript to consume the stream.

Event Types

Event Type	Description	Frequency
start	Simulation started	Once at beginning
progress	Progress update with RTP and completion percentage	Every 2,500 spins
complete	Final results with full analytics	Once at end
error	Error message	On error

Progress Event Response

{
  "type": "progress",
  "completed": 250000,
  "total": 1000000,
  "progress": 25.0,
  "rtp": 94.8,
  "bonusRounds": 8500,
  "totalWagered": 250000,
  "totalWon": 237000
}

Note: Progress events include partial statistics that update every 2,500 spins. This allows you to stop the simulation and keep the partial results.

Complete Event Response

{
  "type": "complete",
  "totalSpins": 1000000,
  "normalSpins": 985000,
  "bonusSpins": 15000,
  "totalBonusRounds": 1000,
  "totalWagered": 985000,
  "totalWon": 936250.50,
  "rtp": 95.05,
  "biggestSingleSpin": {
    "win": 5000,
    "details": { ... }
  },
  "biggestBonusRound": {
    "total": 1250.75,
    "details": { ... }
  },
  "top5BonusRounds": [ ... ],
  "maxWinHits": {
    "count": 3,
    "details": [ ... ]
  }
}

JavaScript Example (Basic)

// Connect to streaming endpoint
let eventSource = new EventSource('/slot/api/simulate.php?spins=1000000');

eventSource.onmessage = function(event) {
  const data = JSON.parse(event.data);

  if (data.type === 'progress') {
    console.log(`Progress: ${data.progress}% | RTP: ${data.rtp}%`);
    console.log(`Wagered: €${data.totalWagered} | Won: €${data.totalWon}`);
  }
  else if (data.type === 'complete') {
    console.log('Simulation complete!', data);
    eventSource.close();
  }
};

eventSource.onerror = function(error) {
  console.error('Connection error', error);
  eventSource.close();
};

JavaScript Example (With Stop Functionality)

// Store latest progress data
let eventSource = null;
let latestProgress = null;

// Start simulation
function startSimulation() {
  eventSource = new EventSource('/slot/api/simulate.php?spins=1000000');

  eventSource.onmessage = function(event) {
    const data = JSON.parse(event.data);

    if (data.type === 'progress') {
      latestProgress = data; // Store for stop functionality
      console.log(`${data.completed} spins | RTP: ${data.rtp}%`);
    }
    else if (data.type === 'complete') {
      console.log('Complete!', data);
      eventSource.close();
    }
  };
}

// Stop simulation and get partial results
function stopSimulation() {
  if (eventSource) {
    eventSource.close(); // Stops server processing

    if (latestProgress) {
      console.log('Partial Results:', {
        spins: latestProgress.completed,
        wagered: latestProgress.totalWagered,
        won: latestProgress.totalWon,
        rtp: latestProgress.rtp
      });
    }
  }
}

Response:

Paytable

Symbol	5 of a Kind	4 of a Kind	3 of a Kind
🍒 Cherry	€2.10	€1.05	€0.42
🍋 Lemon	€2.85	€1.43	€0.57
🍊 Orange	€4.20	€2.10	€0.84
🍇 Grape	€6.80	€3.40	€1.36
🍉 Watermelon	€11.50	€5.75	€2.30
⭐ Star	€29	€14.50	€5.80
💎 Diamond	€78	€39	€15.60
🎰 Jackpot	€240	€120	€48

Note: The 🎰 symbol also acts as a scatter. Landing 3+ anywhere on the reels triggers 15 free spins with a multiplier based on scatter count (3=3x, 4=4x, 5=5x).

Error Handling

The API returns appropriate HTTP status codes and JSON error messages:

{
  "error": "Error message describing what went wrong"
}

HTTP 500: Internal server error (game engine failure)