Executing Spins

The spin endpoint is the core of the KINGSTONE API. When your player taps "Spin," your server sends a request to KINGSTONE and receives a complete outcome with payout, visual symbols, and animation metadata.

The Spin Request

POST /api/partner/v1/spin

Field	Type	Required	Description
gameId	number	Yes	Game configuration ID from registration
playerId	string	Yes	Your external player identifier
wagerUsd	number	Yes	Wager amount in USD
requestId	string	No	Idempotency key (echoed back in response)

With the SDK

import { KingstoneClient } from '@kingstone/sdk';

const client = new KingstoneClient({
  apiKey: 'ks_sandbox_your_key_here',
  sandbox: true,
});

const result = await client.spin({
  gameId: 1,
  playerId: 'player-abc-123',
  wagerUsd: 0.25,
});

console.log(`Spin ID: ${result.spinId}`);
console.log(`Prize tier: ${result.outcome.prizeTier}`);
console.log(`Payout: $${result.outcome.payoutUsd.toFixed(2)}`);
console.log(`Combo: ${result.presentation.comboString}`);
console.log(`Balance: $${result.balance.balanceUsd.toFixed(2)}`);

With curl

curl -X POST https://sandbox.kingstone.dev/api/partner/v1/spin \
  -H "X-API-Key: ks_sandbox_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "gameId": 1,
    "playerId": "player-abc-123",
    "wagerUsd": 0.25
  }'

The Spin Response

{
  "spinId": "12345",
  "outcome": {
    "prizeTier": 3,
    "payoutUsd": 1.00,
    "isBonusTrigger": false
  },
  "presentation": {
    "comboString": "BAR|BAR|BAR",
    "reelSymbols": [
      { "name": "Bar", "display": "BAR", "isWild": false },
      { "name": "Bar", "display": "BAR", "isWild": false },
      { "name": "Bar", "display": "BAR", "isWild": false }
    ],
    "reelStops": [12, 24, 8],
    "animationHints": {
      "celebrationTier": "medium",
      "isNearMiss": false,
      "isBonusTrigger": false
    }
  },
  "balance": {
    "balanceUsd": 99.75
  }
}

Response Fields Explained

outcome — What the player won. This is the authoritative financial result.

Field	Description
prizeTier	The tier of this outcome: 0 = no win, 1-6 = winning tiers. Higher numbers are rarer and more valuable.
payoutUsd	The amount the player won in USD. Zero for no-win outcomes.
isBonusTrigger	Whether this spin triggers a bonus round sequence.

presentation — Visual data for your frontend to render the spin result.

Field	Description
comboString	A human-readable symbol combination like "7|7|7" or "BAR|BAR|BAR".
reelSymbols	Per-reel symbol details including the name, display character, and whether it is a wild.
reelStops	Reel stop positions for animating the spin. Use these to calculate where each reel lands.
animationHints	Metadata for your celebration animations. The celebrationTier tells you the intensity (none, small, medium, large, jackpot).

balance — The player's balance after this spin.

Field	Description
balanceUsd	Current balance in USD after the wager deduction and any payout.

Player Auto-Creation

You do not need to register players before they spin. KINGSTONE automatically creates an internal player mapping the first time it sees a new playerId. On subsequent spins, the existing mapping is reused.

This means your integration does not need a separate "create player" step. Just send the spin request with your player's ID, and KINGSTONE handles the rest.

If you need to look up a player later, use the player endpoint:

const player = await client.getPlayer('player-abc-123');
console.log(`Internal user ID: ${player.userId}`);
console.log(`Created: ${player.createdAt}`);

Using the Response in Your Frontend

Your server proxies the KINGSTONE response to your frontend. Here is what each piece of data is for:

1. reelSymbols — Use these to display the correct symbols on each reel after the spin animation.
2. reelStops — Use these as target positions for your reel spin animation.
3. animationHints.celebrationTier — Trigger the right level of celebration (confetti, sound effects, screen shake).
4. animationHints.isNearMiss — Optionally show a "close call" animation to build excitement.
5. outcome.payoutUsd — Display the win amount to the player.
6. balance.balanceUsd — Update the balance display.

Common Errors

Error Code	HTTP Status	Meaning
KS-4201	404	Game not found. Check the gameId.
KS-4103	400	Wager out of range or not on increment boundary.
KS-4291	429	Spin rate limit exceeded. Back off and retry.
KS-4202	400	Game is not active. Contact Predigy support.
KS-4203	503	Game outcome queue exhausted. Wait for block generation.

Next Steps

• Learn about daily settlement reconciliation
• Set up webhooks for real-time event notifications
• Check RTP compliance for your games