Sandbox Testing

The Slotty Labs sandbox environment lets you test your integration with simulated players, balances, and forced game outcomes — all without real money.

Test Player Creation

REST API

POST /api/v1/test/players

// Request body
interface CreateTestPlayerRequest {
  externalId: string;
  currency: string;        // e.g. "USD"
  startingBalance: number; // e.g. 10000
  username: string;
}

// Response
interface CreateTestPlayerResponse {
  player: {
    id: string;
    externalId: string;
    username: string;
    currency: string;
  };
  wallet: {
    id: string;
    balance: number;
    currency: string;
  };
  ssoToken: string; // Ready-to-use launch token
}

SDK Method

const { player, wallet, ssoToken } = await client.test.createPlayer({
  externalId: 'test-player-001',
  currency: 'USD',
  startingBalance: 10000,
  username: 'TestPlayer1',
});

// Use ssoToken directly in a launch URL
const launchUrl = client.games.getLaunchUrl('slotty-slots', ssoToken);

Adding Balance

Top up a test player's balance at any time:

POST /api/v1/test/players/:id/add-balance

await client.test.addBalance('player-id', {
  amount: 5000,
  currency: 'USD',
});

Resetting Players

Reset a test player to their initial state (clears all rounds, resets balance):

POST /api/v1/test/players/:id/reset

await client.test.resetPlayer('player-id');

Forced Outcomes

Force specific game outcomes for testing. This is only available in sandbox mode.

Current support

Forced outcomes apply to demo (play-money) sessions only and are currently consumed by Slotty Slots (reelPositions substitute the five reel-stop RNG draws — the game math still runs, so only outcomes the engine could genuinely produce are possible). The shapes documented below for the other four games predate the July 2026 engine retunes and are being re-specified; posting them succeeds but the next round falls back to the real RNG (with a warning in the game-service logs).

POST /api/v1/test/force-outcome

Slots

await client.test.forceOutcome({
  playerId: 'player-id',
  gameId: 'slotty-slots',
  outcome: {
    type: 'slots',
    reelPositions: [3, 7, 12, 1, 9], // 5 reel stop positions
  },
});

Safe Smash

await client.test.forceOutcome({
  playerId: 'player-id',
  gameId: 'safe-smash',
  outcome: {
    type: 'safe_smash',
    multipliers: [0.5, 1.0, 1.5, 2.0, 0.0, 3.0], // Per-hit multipliers
    hammerBreakOnHit: 5, // Hammer breaks on hit 5 (null = never)
  },
});

Bit Key Rush

await client.test.forceOutcome({
  playerId: 'player-id',
  gameId: 'bit-key-rush',
  outcome: {
    type: 'bit_key_rush',
    correctChars: ['A', '7', 'Z', 'B', '3', 'K', 'Q', '9', 'W', '1', 'M', 'F'],
    guessResults: [
      { position: 0, correct: true, multiplier: 1.5 },
      { position: 1, correct: false, penalty: 0.2, traceIncrease: 15 },
    ],
    fbiTracePerGuess: [10, 15, 12, 20, 8, 18, 14, 22, 11, 16, 19, 13],
  },
});

Fox'n Flock

await client.test.forceOutcome({
  playerId: 'player-id',
  gameId: 'fox-n-flock',
  outcome: {
    type: 'fox',
    goatMultipliers: [1.2, 0.8, 2.5, 1.0, 3.0, 0.5, 1.8, 4.0],
    shepherdState: 'sleeping', // 'sleeping' | 'alert' | 'patrolling'
  },
});

Katapuuult

await client.test.forceOutcome({
  playerId: 'player-id',
  gameId: 'katapuuult',
  outcome: {
    type: 'catapult',
    collectibles: [
      { x: 200, y: 350, type: 'coin', value: 0.5 },
      { x: 400, y: 280, type: 'gem', value: 1.5 },
      { x: 600, y: 200, type: 'star', value: 2.0 },
    ],
    hazards: [
      { x: 300, y: 300, type: 'cloud', penalty: 0.3 },
      { x: 500, y: 250, type: 'bird', penalty: 0.5 },
    ],
  },
});

Health Check

Verify that all platform services are operational:

GET /api/v1/test/health

const health = await client.test.getHealth();

Response includes 10 service checks:

interface HealthCheckResponse {
  status: 'healthy' | 'degraded' | 'unhealthy';
  checks: {
    database: 'ok' | 'error';
    redis: 'ok' | 'error';
    websocket: 'ok' | 'error';
    gameEngine: 'ok' | 'error';
    walletService: 'ok' | 'error';
    authService: 'ok' | 'error';
    webhookDelivery: 'ok' | 'error';
    blockchainScanner: 'ok' | 'error';
    provablyFair: 'ok' | 'error';
    cdn: 'ok' | 'error';
  };
  timestamp: string;
  version: string;
}

Onboarding Status Machine

Your operator account progresses through these states:

created → configured → sandbox_ready → integrating →
integration_complete → review_requested → under_review →
approved → production → active

State	Description
created	Account created, no configuration yet
configured	API keys generated, webhook URL set
sandbox_ready	Sandbox environment provisioned
integrating	Active development and testing
integration_complete	All integration tests passing
review_requested	Operator submitted for production review
under_review	Slotty Labs team reviewing integration
approved	Integration approved, production keys available
production	Production environment active
active	Live traffic flowing

TIP

You can check your current onboarding status in the operator dashboard or via the API. Contact office@slottylabs.com to request a review when you're ready.