Section 1

Onboarding

Onboarding consists of an exchange of registration details with the platform team, followed by a single credential header on every request.

Registration details

Supplied by the game provider

Game name for each title.
frontendUrl: the https URL the player's browser is redirected to. It may carry fixed query parameters of its own.
Requested gameId per title: an integer greater than 100, unique across the platform.
Public IP addresses of the game backend, per environment, so the platform team can whitelist them.
Optional RSA public key (PEM, 2048 bits or more) to receive launch parameters encrypted. See encrypted launch parameters.

Issued by the platform

Game provider token: rly_<slug>_<secret>. Shown once. To be stored in a secret manager.
Relay base URL per environment, listed under Environments. Written as {RELAY_BASE_URL} in this guide.
Launcher URL that casinos use to launch the game.
Registered gameId(s) and the groupId.

Registration is performed by the platform team.

Game providers, tokens and games are created through admin-only endpoints that a game provider does not call. A leaked token is revoked and reissued by the platform team; several tokens can be active at once, so rotation requires no downtime.

Environments

Environment	Base URL	API reference
Development	https://api.euc1.relay.aviator.studio	api.euc1.relay.aviator.studio/api/docs
Staging	https://api.staging.relay.aviator.studio	api.staging.relay.aviator.studio/api/docs
Production	Issued by the platform team at go-live.

IP whitelisting is required.

The relay and the API reference pages only accept requests from IP addresses that the platform team has whitelisted. Before the first call, send the platform team the public IP addresses that the game backend uses for outgoing traffic, for each environment. If the servers sit behind a NAT gateway or a proxy, send the address of that gateway, because that is the address the relay sees. Requests from an address that is not on the list simply get no answer, which looks like a timeout.

Authentication

Every request to the relay carries the game provider token. Two header forms are accepted. The bearer form is preferred; the second exists for gateways that strip Authorization from forwarded requests.

Authorization: Bearer rly_acme_3fK9…      # preferred
x-service-token: rly_acme_3fK9…           # fallback

The token identifies the game provider, not a game. The game is taken from the session and must belong to the game provider. A token cannot move money for a game the game provider does not own, and cannot read another game provider's data.

Failure	Status	Code
Header missing, token unknown, revoked or past its expiry	403	AUTHENTICATION_FAILED
Game provider deactivated	403	GROUP_NOT_ACTIVE

Response formats

The relay uses two response formats. The format is determined by the path alone.

Wallet routes: raw body

/api/account, /api/balance/cash-out, /api/balance/cash-in, /api/balance/cash-in/retry and /api/round-ended return exactly what a casino wallet returns, without a wrapper. A game already written against a casino wallet can be repointed at the relay by changing one base URL.

200  { "id": "player-1", "balance": 100.5, "username": "player" }
403  { "error": "AUTHENTICATION_TOKEN_EXPIRED" }

Routes under /api/v1/: envelope

200  { "statusCode": 200, "message": "Session is valid", "data": { … } }
200  { "statusCode": 200, "message": "Rounds fetched successfully", "data": [ … ],
       "meta": { "total": 42, "page": 1, "limit": 20, "totalPages": 3 } }
403  { "statusCode": 403, "message": "invalid or expired service token",
       "data": null, "error": "AUTHENTICATION_FAILED" }

On an error the machine-readable code is in error. The message field is descriptive text and may change between versions.

Connectivity verification

1. Reachability

   No credential required. A 200 confirms network path and TLS.

   curl -i {RELAY_BASE_URL}/api/healthz

2. Token verification

   The casino id list is the simplest authenticated read. An empty array is a valid response when no casino is registered yet.

   curl {RELAY_BASE_URL}/api/v1/providers/ids \
     -H "Authorization: Bearer $RELAY_TOKEN"
   
   { "statusCode": 200, "message": "Provider ids fetched successfully",
     "data": [ { "providerId": "66ffba1337e994c3009ebf40", "createdAt": "2026-07-24T11:19:26.294Z" } ] }

3. Casino configuration

   curl {RELAY_BASE_URL}/api/v1/provider-catalog \
     -H "Authorization: Bearer $RELAY_TOKEN"

   The response is described in Casino configuration.

4. Test launch

   The platform team provides a test launch URL against a sandbox casino. Once the browser lands on the frontendUrl with a sessionId, the flow continues as described in Launch and sessions.

General conventions

• JSON request bodies with Content-Type: application/json.
• Money is a JSON number with at most two decimal places. A third decimal is rejected with 400. Balances returned by the relay are always rounded to two decimals.
• Currency comparisons are case-insensitive, but the session's currency is authoritative. Requests carry the currency the session was opened with.
• Timeouts. The relay waits up to 10 seconds for a casino. The client timeout towards the relay should be higher, around 15 seconds, so that the relay's 408 is received rather than pre-empted.
• Correlation. An x-correlation-id request header, when present, is logged and echoed back, and allows the platform team to trace a request across services.