How the jackpot API works

Full article

💡 18+. The material is engineering-applied, without a call to play. Terms: platform - PAM/wallet/cash desk/bonuses/RG; RGS - Remote Game Server (core of studio games); aggregator - unified layer for multiple RGS; JP - jackpot service.

1) What is a jackpot system and where does it stand in the ecosystem

The jackpot system is a separate service (sometimes a cluster of services) that collects contributions from bets, manages pools and win triggers, calculates the distribution of prizes and initiates payments through the operator's payment loop. It integrates:

with RGS (messages about rates/outcomes and qualifications), with a platform/wallet (writing off contributions and crediting winnings), with an aggregator (routing from many studios/brands), with a BI/regulator (telemetry and reporting).

2) Types of jackpots (and what changes in API)

1. Fixed-The amount of the prize known in advance. There is no pool in the API, only condition checking and credit.

2. Progressive: The pool grows from bet contributions. We need endpoints of the contribution and the publication of the current size.

3. Multi-tier (Multi-tier: Mini/Major/Grand): multiple parallel pools with different odds and caps.

4. Local vs network: local pool - one operator/brand; network - total for many operators/brands/regions (multi-tenancy and replication are critical).

5. Time/event: a pool with a deadline or on a schedule (timers and auto-draws are needed).

3) Monetary invariants

The source of truth on the balance is the platform's wallet/ledger. JP stores only the state of pools and liabilities.

All money transactions are idempotent (keys' jp _ curb _ id ',' jp _ trigger _ id ',' jp _ payout _ id ').

Lost/Duplicated Payouts = 0. Compensation - only by events (sagas), not by manual database edits.

Separate contribution, trigger, and payout as standalone transactions with your own telemetry.

4) API Reference Contracts

4. 1 RGS/ → aggregator JP (contributions and triggers)

'POST/v1/jp/contributions' - accounting for pool contribution

json
{
"jp_contrib_id": "uuid-1",  "tenant_id": "brand-42",  "pool_id": "grand-eu-01",  "player_id": "p_abc",  "game_id": "studio:slot_777",  "round_id": "r_123",  "bet": {"amount": 2. 00, "currency": "EUR"},  "contrib": {"amount": 0. 02, "currency": "EUR"},  "occurred_at": "2025-10-23T15:12:05Z",  "idempotency_key": "round_r_123"
}

'POST/v1/jp/candidates' - application for participation/verification of conditions (optional)

Answer: 'eligible: true/false ', weight or chance, rules.

'POST/v1/jp/triggers' - recording the fact of operation

json
{
"jp_trigger_id": "uuid-2",  "pool_id": "grand-eu-01",  "reason": "random_hit",  "selector": {"player_id": "p_abc", "round_id": "r_123"},  "occurred_at": "2025-10-23T15:12:06Z",  "idempotency_key": "jp_t_grand_r_123"
}

💡 Note: in some models, the trigger is initiated by JP itself (internal roulette), and RGS only reports the round. Then 'triggers' are called JP→platforma and the RGS subscribes to the event.

4. 2 JP → platform (payments/provisions)

'POST/v1/wallet/reserve '- (optional) provision for future payout

'POST/v1/wallet/credit '- player win credit

json
{
"jp_payout_id": "uuid-3",  "tenant_id": "brand-42",  "player_id": "p_abc",  "pool_id": "grand-eu-01",  "amount": {"amount": 500000. 00, "currency": "EUR"},  "meta": {"tax": "withheld=false", "tier": "grand"},  "idempotency_key": "jp_p_grand_r_123"
}

Platform responses: 'credit. ok	failed ', with reason codes (RG/AML, withdrawal limits, sanctions, geo-block).

4. 3 Publish pool status (for fronts/widgets)

'GET/v1/jp/pools/{ pool _ id} '→ current size, seed, cap, number of participants, ETA, etc.

'GET/v1/jp/pools' → list of pools by brand/region with filters.

5) Event model (Kafka/Pulsar) and diagrams

Basic topics:

`jp. contribution. recorded`
`jp. pool. updated '(size, competitive updates)
`jp. triggered`

`jp. payout. requested	credited	failed`
`wallet. credit. '(mirroring for sagas)
`rg. limit. hit`, `aml. alert. opened '(if payment is blocked)
`audit. config. changed '(limits, seed, cap, distribution)

Contracts: Avro/JSON Schema + Schema Registry, participation keys' tenant _ id ',' pool _ id ',' player _ id '. Versioning - backward-compatible.

6) Trigger algorithms (high-level)

Probabilistic (p-stable): for each qualified round we generate a hit with probability'p '(depending on the pool/level type).

Range (must-drop): the pool must fall to the cap-sum or deadline - keep the internal random in the range [min, max], publish cap/ETA.

Seed and entropy management: server seed + per-round salt; abandoning client jackpot seats. All changes to seed are under WORM audit.

Honesty: The trigger should not depend on the player's specific personality (other than geo/license/qualification rules). Any "personal" targeting is taboo.

7) SLO and performance

p95 'contribution' <120 ms, p99 <250 ms.

p95 'trigger→credit' <500 ms (without external payment hops).

"Lost/duplicated payouts" = 0 (checked by contract tests).

Event delivery to BI ≤ 5 min.

JP API availability for critical paths ≥ 99. 95%.

8) Safety and compliance

mTLS + signatures (HMAC/EdDSA) on all S2S calls short-lived tokens.

Zero-trust: network policies/mesh, minimum privileges, segmentation by region.

WORM audit of changes to limits, formulas, seed/entropy, pool configs.

GDPR/Data residency/PCI: PII and logs - in the region; tokenization of sensitive fields; banning cross-region readings.

RG/AML: synchronous brake lights on payout; SAR/STR uploads are automated.

9) Coherence and sagas

Contribution ('contribution') - fix in JP, publish 'jp. contribution. recorded`.

Trigger ('triggered') - creates an obligation; JP launches' payout'saga.

Payout ('payout. requested → wallet. credit. ok ') - ends the saga; with fake - retrai with deduplication.

Outbox/CDC is the only way to publish events; no "bypass" loggers.

10) Telemetry and dashboards

Business:

`pool_size`, `contrib_rate`, `avg_contrib_per_bet`, `time_to_drop`, `payouts_count/sum`, `tier_distribution`.

Technical:

p50/p95/p99 по `contribution`, `trigger`, `payout`;
error rate с типами (5xx/4xx/business), retry storms, queue lag;
`wallet. credit` latency/ok-rate; pool update conflict.

Alerts:

growth'payout. failed '> X% by brand/region,' pool _ size '> cap - Y% of time (configuration error), drift between' pool _ size 'and reconciliation contribution amount> Z ppm.

11) Multi-tenancy and isolation

All requests and events are marked 'tenant _ id/brand _ id/license/region'.

Local/network pools are physically separated (DB/cluster) under different licenses/regions.

Row-level security (RLS) and masking in BI storefronts.

Individual keys/secrets and schematic spaces per brand/region.

12) Integration with bonuses/tournaments

Contributions do not increase the vager directly; contribution to the bonus - comes from the bet, not from the contribution.

Tournaments may award points for "JP participation" or "top contribution." Source - events' jp. contribution. recorded` и `jp. triggered`.

Mandatory rule: Jackpot mechanics do not change the basic RTP of the game; otherwise separate certification is needed.

13) Testing and chaos practices

Contract tests RGS↔JP↔koshelyok: double-delivery, delays, out-of-order, rollback.

Load tests: storm of bets and triggers, scaling pool workers.

Chaos exercises: the fall of the JP region, offline wallet, time desynchronization; check outbox and degradation (pause triggers/no new contributions).

14) Checklists

For Studio/RGS

Idempotent 'contribution' and correct 'round _ id '/' bet _ id'.
No publications "bypassing" transactions (outbox/CDC only).
Tests of duplicates/repeated triggers/compensations.
max bet/qualification limits are transferred to JP.

For operator/platform

Ledger is the source of truth, 'wallet. credit 'with deduplication.
RG/AML stops are processed on pay; SAR/STR reports.
p95 'trigger→credit' dashboards, error rate, pool reconciliations.

For JP Owner

WORM audit of formula/seed/limit changes.
Event schemas in Registry and versioning.
DR: RPO ≤ 5 min, RTO ≤ 30 min; regular exercises.
RLS/isolation by brand/license; keys/secrets per region.

15) Red flags (anti-patterns)

Manual edits of pool sizes and payments in the database.

Lack of idempotence → duplicate loans.

Publishing telemetry without outbox/CDC → "lost" contributions/triggers.

Mixing PII and monetary data of different regions.

Jackpot that affects the RTP of the base game without new certification.

No wallet and pool reconciliations; reports are based on combat OLTP.

Jackpot systems API is a monetary event contract between a studio, platform and operator. Its foundation: idempotence and sagas, strict isolation of money, clear event schemes, security and WORM audit, observability and SLO. On this design, fix/progressive and network pools scale predictably, payments remain correct, and regulatory and business reporting are transparent and reliable.