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

import { KingstoneClient } from '@kingstone/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)
});

Option	Type	Required	Default	Description
apiKey	string	Yes	—	Your partner API key (ks_ for sandbox, kp_ for production)
baseUrl	string	No	Auto-detected	Override the base URL (useful for local development)
sandbox	boolean	No	false	When true, uses https://sandbox.kingstone.dev/api
timeoutMs	number	No	30000	Request 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.

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.

// 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.

// Register a new game
const game = await client.registerGame({
  parSheetId: 1,
  displayName: 'Lucky Sevens',
  configName: 'LUCKY_SEVENS',
  minWagerUsd: 0.10,     // optional, default 0.10
  maxWagerUsd: 5.00,     // optional, default 5.00
  wagerIncrementUsd: 0.10, // optional, default 0.10
});
// Returns: RegisterGameResponse

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

Players

Look up a player by your external ID.

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.

// 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.

// 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.

// 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.

// 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

• See complete working examples in the Examples page
• Learn about error handling in the Error Handling guide