How API integration works between studios and platforms

Integration of the studio (game provider) with the platform/aggregator is a chain of synchronous and asynchronous calls around the session, wallet, spin result and event telemetry. Below is a brief but practical map of how everything connects without pain for developers and compliance.

1) Architecture in the palm of your hand

Actors:

Studio RGS (Remote Game Server) - game logic, RNG, bonuses, jackpots.
Platform/Aggregator - routing, billing, promo, compliance.
Operator - player's wallet, KYC/RG, showcase.
Client - web/mobile game container (iframe/webview/native).

Main buses:

Sync API: sessions, wallet, outcome.
Async/Event Bus: spin events, bonuses, jackpots, RG, technical errors.
Metadata/catalog: games, market builds, RTP profiles, locales.

2) Protocols and basic solutions

Transport: HTTPS/JSON (sometimes gRPC for Event Bus/Wallet).

Versioning: 'Accept: application/vnd. rgs. v1 + json 'or '/v1/...'; compatibility degradation - only through new versions.

Identification: 'game _ id', 'build _ hash', 'operator _ id', 'session _ id', 'round _ id', 'spin _ id'.

Time: strictly UTC, ISO-8601 with milliseconds.

Currencies: ISO-4217 + accuracy (minor units). FX - operator/aggregator side.

3) Authentication and authorization

Server-to-server: OAuth2 Client Credentials или HMAC-подпись (`X-Signature: HMAC_SHA256(payload, shared_key)`).

Player session: short-lived JWT (signs platform) c 'sub', 'geo', 'rg _ flags', 'exp', 'aud = studio'.

Access lists: IP allow + mTLS for production loops.

4) Wallet models: debit/credit vs transfer

A) Debit/Credit (on-the-fly):

1. The platform calls RGS: 'SpinRequest (stake)' → RGS calculates the outcome → returns' win '.

2. In parallel, the platform makes' debit (stake) 'and' credit (win) 'at the operator's place.

Pros: Simple bookkeeping. Cons: more network calls, strict requirements for idempotency.

B) Transfer (session balance):

1. At the beginning of the session, the platform does' transferIn (amount) 'on the RGS.

2. During spins, RGS itself balances the session; on completion - 'transferOut (remaining)'.

Pros: Fewer wallet chats. Cons: accounting for "money on the side of RGS," additional risks and reconciliations.

Recommendations:

For slots, debit/credit with idempotent keys is more often used.

On free spins and tournaments it is convenient to have separate bet types' spin _ type = free	promo`.

5) Idempotency and consistency

Each money step must have a unique 'idempotency _ key' (for example, 'round _ id' or 'spin _ id').

Duplicates ('HTTP 409/425') return the same result, not an "error already executed."

Exactly-once is difficult to achieve, so we build at-least-once + idempotency.

Idempotence is extended to: 'debit', 'credit', 'jackpot _ contribution', 'bonus _ award'.

6) Key query schemes (abbreviated)

6. 1. Start of the session

json
POST /rgs/v1/sessions
{
"session_id": "s-…",  "operator_id": "op-…",  "player_id": "p-…",  "game_id": "g-BookOf…",  "build_hash": "sha256:…",  "jwt": "eyJhbGci…",  "geo": "DE",  "currency": "EUR",  "rg_flags": {"self_excluded": false, "time_limit_min": 60}
}

6. 2. Spin (debit/credit)

json
POST /rgs/v1/spins
{
"spin_id": "spin-…",  "round_id": "rnd-…",  "session_id": "s-…",  "stake": {"amount": 1. 00, "currency": "EUR"},  "spin_type": "cash",  "idempotency_key": "spin-…"
}

Answer:

json
{
"spin_id": "spin-…",  "outcome": {
"win": {"amount": 3. 40, "currency": "EUR"},   "features": [{"type":"bonus_trigger","name":"FreeSpins","count":10}],   "symbols": "opaque-or-omitted"
},  "rgs_txns": [
{"type":"jackpot_contribution","amount":0. 01}
],  "telemetry_ref": "evt-…"
}

6. 3. Event Bus

json
POST /rgs/v1/events/batch
{
"events":[
{
"type":"spin_finished",    "ts":"2025-10-20T11:22:33. 123Z",    "spin_id":"spin-…",    "round_id":"rnd-…",    "stake":1. 00,"win":3. 40,"currency":"EUR",    "game_id":"g-…","build_hash":"sha256:…",    "player_id":"p-…","operator_id":"op-…",    "spin_type":"cash"
}
]
}

7) Versioning builds and market builds

'build _ hash '(SHA-256) - required at each event.

Global vs Market build: language, warnings, rate limits, RTP profile.

The platform validates: "is a build currently being played that matches the certificate of a given country."

Matrix: 'game_id × country × rtp_profile × build_hash'.

8) RNG, Math and Replay

RNG lives on RGS; business logic doesn't change the chances on the fly.

For forensics: 'seed/nonce' per round/spin + mechanic version.

Replay: by 'spin _ id '/' seed', RGS reproduces the outcome and gives an audit trail.

9) Responsible Gaming (RG) and compliance hooks

Hooks of time/limits: 'session _ time _ ms', "reminders," timeouts; 'rg _ event' in Event Bus.

Self-exclusion/block: with flag - immediate '403 RG_BLOCKED'.

UI invariants: the platform checks that the client shows warnings/age tags from the market build.

10) Bugs, Retrays and SLAs

Codes: '400' (validation), '401/403' (authentication/RG), '409' (idempotency conflict), '422' (business error), '429' (rate limit), '5xx' (temporary).

Retray policy: exponential, with an idempotent key and deduplication at the receiver.

SLA ≥99 API availability. 9%, p95 latency for 'spin' ≤200 -300 ms (regional), Event Bus - near-real-time <60 s.

11) Observability and audit

Logs: uncut server logs with correlation 'trace _ id'.

Metrics: p95/p99 latency, error rate by methods, deviations of RTP/bonus frequencies, proportion of "elastic spins."

Alerts: by SLA, by mathematics anomalies, by the increase in wallet failures.

Audit: WORM storage for betting/results events; export on demand.

12) Safety

mTLS + TLS 1. 2 +, HSTS, strict CORS on the client loader.

Key rotation, short TTL tokens, JTI/nonce checks.

Anti-tamper for client: asset signatures, integrity check, debugger protection.

Secrets - only in the secret manager; no "key in the config of the game."

13) Test environments and certification

Sandbox: fictitious wallets, deterministic RNG (fixed seed), auto-failure of RG scenarios.

Staging: a copy of prod-infra without real money.

Package for laboratories: GDD/mathematics, RNG dossier, log diagrams, repeatable build and hashes.

14) Promos and jackpots in API

Free Spins: packet transfer: 'grant _ free _ spins (count, bet_size, rtp_profile?)'; events are spent in the RGS and logged.

Tournaments: attribute 'spin _ type = tournament' + individual aggregates in Event Bus.

Jackpots: 'jackpot _ contribution' and 'jackpot _ win' as separate transactions; consistency through idempotency and "signed" events.

15) Reporting and Billing

Блоки выгрузок: `spins_total`, `eligible_spins`, `turnover`, `ggr`, `netwin`, `jackpot_contrib`, `bonus_cost`, `royalty_due`.

Per-spin/turnover-fee: account by'eligible _ spins' or 'Σ stake × rate'.

Rev-share: from 'NetWin' after 'waterfall' holds; quarterly true-up for FX/exceptions.

16) Typical sequences (word charts)

Spin (debit/credit):

Client → Platform: StartRound → Platform → RGS: Spin → RGS → Platform: Outcome → Platform → Wallet: Debit → Platform → Wallet: Credit → Platform → Client: Result → Platform → EventBus: spin_finished.

Free Spins:

Platform → RGS: GrantFreeSpins → Client: Start → RGS: Consume/Log each → EventBus: spin_finished (spin_type=free).

17) Change-management and interoperability

Contract-first: OpenAPI/Protobuf is a single source of schemas.

SemVer: only add fields; delete/modify - in/v2.

Feature flags-Enable options (Bonus Buy/Ante) through certified profiles only.

Rejection: announce → grace period → shutdown in inactive regions.

18) Checklists

Studio → Platform

OpenAPI/gRPC specs and sample payloads.
IDempotency 'spin/debit/credit/jackpot'.
'build _ hash' and market builds registry.
RNG replicas and audit log.
RG hooks and errors' 403 RG_BLOCKED'.
Sandbox with fix-seed, test wallet and auto scripts.

Platform → Studio

JWT signature with short TTL, allowlist IP, mTLS.
Validator of market builds and certificates.
Event Bus and dashboards (latency/error/RTP drift).
Quotas and rate-limits with honest feedback '429-Retry-After'.
SLAs/Incidents/Links 24 × 7.

19) 30-60-90 launch plan

0-30 days

Agree on API contracts and event schemes, choose a wallet model.

Raise sandbox: fixed-seed RNG, test wallet, autotests of idempotency.

Registry 'build _ hash' and primary matrix market builds.

31-60 days

Wallet and spin integration; enable Event Bus and dashboards.

Load tests (p95/p99), retrai/idempotency, network chaos scenarios.

Compliance: RG-hooks, locales, age-labels; package to the lab.

61-90 days

Pilot for 1-2 operators, A/B for promo (free spins/tournaments).

Entering true-up/reporting, RTP drift alerts/bonus-freq.

Preparing v2 improvements: batch events, gRPC for wallet, geo-routing.

20) Short FAQ

Where is RTP/version checked? On the platform: 'build _ hash' ↔ certificate ↔ country.

Can RTP be changed dynamically? No, it isn't. Only pre-certified profiles and only switching market build.

How to solve "double debit"? Idempotent key + storing transaction status; redo-Returns the outcome.

Do I need a gRPC? Useful for wallet/events at high volumes; REST remains for metadata/admin panel.

Stable integration is contracts + idempotency + observability. Transparent event schemes, build/market control, RG hooks and version discipline remove 90% of risks at the start. Further - automation of promo and reporting, hard SLA and careful development of API without "breaking" changes.