Skip to content

Client Usage ​

The KingstoneClient class is the main entry point for the SDK. It handles authentication, JSON serialization, timeouts, and error mapping for all KINGSTONE partner API endpoints.

Constructor Options ​

typescript
import { KingstoneClient } from '@kingstoneapp/sdk';

const client = new KingstoneClient({
  apiKey: 'ks_sandbox_your_key_here',  // Required
  baseUrl: 'https://sandbox.kingstone.dev/api',  // Optional
  sandbox: true,   // Optional — uses sandbox URL when true
  timeoutMs: 30000, // Optional — request timeout (default: 30s)
});
OptionTypeRequiredDefaultDescription
apiKeystringYes—Your partner API key (starts with ks_)
baseUrlstringNoAuto-detectedOverride the base URL (useful for local development)
sandboxbooleanNofalseWhen true, uses https://sandbox.kingstone.dev/api
timeoutMsnumberNo30000Request timeout in milliseconds

If baseUrl is not set, the URL is determined by the sandbox flag:

  • sandbox: true uses https://sandbox.kingstone.dev/api
  • sandbox: false (or omitted) uses https://api.kingstone.dev/api

Method Reference ​

All methods are async and return typed responses. Errors throw KingstoneApiError.

Spin ​

The core endpoint. Executes a spin for a player.

typescript
const result = await client.spin({
  gameId: 1,
  playerId: 'player-abc',
  wagerUsd: 0.25,
  requestId: 'optional-idempotency-key',  // optional
});
// Returns: SpinResponse

PAR Sheets ​

Upload and list probability accounting reports.

typescript
// Upload a new PAR sheet
const uploaded = await client.uploadParSheet({
  gameTitle: 'My Game',
  manufacturer: 'My Studio',
  numReels: 3,
  virtualStopsPerReel: [32, 32, 32],
  certifiedRtp: 0.925,
  denominationUsd: 0.25,
  symbols: [/* ... */],
  tiers: [/* ... */],
  combinations: [/* ... */],
});
// Returns: UploadParSheetResponse

// List all active PAR sheets
const { parSheets } = await client.listParSheets();
// Returns: ListParSheetsResponse

Games ​

Register and list game configurations.

typescript
// Register a new game
const game = await client.registerGame({
  parSheetId: 1,
  displayName: 'Lucky Sevens',
  configName: 'LUCKY_SEVENS',
  // Fixed-wager: the wager is the PAR sheet's denomination.
  // Omit the band fields; if sent, each must equal the denomination.
});
// Returns: RegisterGameResponse

// List all partner games
const { games } = await client.listGames();
// Returns: ListGamesResponse

Players ​

Look up a player by your external ID.

typescript
const player = await client.getPlayer('your-external-player-id');
// Returns: PlayerResponse { externalPlayerId, userId, createdAt }

Players are auto-created on first spin. This endpoint returns 404 if the player has never spun.

Settlements ​

List, retrieve, acknowledge, and dispute daily settlement reports.

typescript
// List reports with pagination
const { reports, total } = await client.listSettlements({ page: 1, limit: 10 });
// Returns: ListSettlementsResponse

// Get a single report by date
const report = await client.getSettlement('2026-03-23');
// Returns: SettlementReport

// Acknowledge a report (numbers match your records)
const acked = await client.acknowledgeSettlement('2026-03-23');
// Returns: SettlementReport with status ACKNOWLEDGED

// Dispute a report (numbers do not match)
const disputed = await client.disputeSettlement('2026-03-23', 'Spin count mismatch');
// Returns: SettlementReport with status DISPUTED

Audit ​

Retrieve audit logs and verify the hash chain.

typescript
// Get paginated audit log
const { sessions } = await client.getAuditLog({
  gameConfigId: 1,    // optional filter
  startDate: '2026-03-01', // optional filter
  endDate: '2026-03-23',   // optional filter
  page: 1,
  limit: 50,
});
// Returns: AuditLogResponse

// Verify the SHA-256 hash chain for a game
const verification = await client.verifyAuditChain(1, {
  limit: 1000,  // optional, max sessions to verify
});
// Returns: AuditChainVerification { isValid, sessionsVerified, brokenLinks }

Compliance ​

Track RTP accuracy and generate compliance certificates.

typescript
// Per-game RTP compliance detail
const rtp = await client.getRtpCompliance(1);
// Returns: RtpComplianceResponse

// Compliance overview across all games
const summary = await client.getComplianceSummary();
// Returns: ComplianceSummaryResponse

// Downloadable compliance certificate
const cert = await client.getComplianceCertificate(1);
// Returns: ComplianceCertificate

Webhooks ​

Register, list, and delete webhook endpoints.

typescript
// Register a new webhook (returns the signing secret once)
const webhook = await client.registerWebhook({
  url: 'https://your-server.com/webhooks/kingstone',
  events: ['spin.large_win', 'settlement.report_ready'],
});
// Returns: RegisterWebhookResponse (includes secret)

// List all webhooks (secrets NOT included)
const { webhooks } = await client.listWebhooks();
// Returns: ListWebhooksResponse

// Delete a webhook
await client.deleteWebhook(webhookId);
// Returns: void

// Check delivery history
const { deliveries } = await client.getWebhookDeliveries(webhookId, {
  page: 1,
  limit: 20,
});
// Returns: WebhookDeliveriesResponse

Next Steps ​

KINGSTONE by Predigy Inc.