Get Game URL

Request a game URL with a one-time login code for a player. You can use this URL within an iframe or redirect mobile players to it directly.

When embedding in an iframe, you can use our Iframe Events API to communicate with the game — refresh balance, listen for bet events, detect insufficient balance, and more.

Authentication

This endpoint is authenticated by IP whitelist — your server's outbound IP must match the address registered during onboarding. See Security for details. The X-Marbles-Signature header is not required and is ignored if sent.

Endpoint

POST https://api.marbles.xyz/game/game/url

The doubled /game is correct — every endpoint lives under the /game base path, and this endpoint's own path is /game/url. Staging: https://api.stagingmarbles.io/game/game/url.

Request

POST /game/game/url HTTP/1.1
Host: api.marbles.xyz
Content-Type: application/json

{
  "clientSessionId": "some-session-id",
  "clientPlayerId": "some-player-id",
  "operatorId": "operatorId",
  "partnerId": "my-casino",
  "gameId": "2469f711-2da6-46b7-8648-3313dfdc5bb5",
  "username": "unique-username",
  "currency": "USD",
  "platform": "MOBILE",
  "displayName": "Player Display Name",
  "lobbyUrl": "https://mylobby.url",
  "depositUrl": "https://mydeposit.url",
  "language": "en",
  "country": "US"
}

Parameters

Parameter	Type	Required	Description
`clientSessionId`	string	Yes	Your session identifier for this player
`clientPlayerId`	string	Yes	Your unique player identifier
`operatorId`	string	Yes	Your operator identifier (provided by 155.io)
`partnerId`	string	Yes	Your chosen identifier for the website/casino offering the game (you define this)
`gameId`	string	Yes	Game UUID from the `/game/games` endpoint, or the reserved lobby code to open our multi-game lobby. Never blank.
`username`	string	Yes	Unique username for the player
`currency`	string	Yes	ISO 4217 currency code (see Currencies)
`platform`	string	No	`"DESKTOP"`, `"MOBILE"` or `"TABLET"` — case-sensitive. Send `TABLET` for tablet sessions rather than coercing to `MOBILE`; we store it as reported, so your segmentation is preserved. Any other value rejects the launch (see Error Responses); omitting the field is allowed
`displayName`	string	No	Non-unique display name shown in game
`lobbyUrl`	string	No	Your lobby — where the player is sent when they exit our games. Must be an absolute URL including `https://`; a blank or malformed value is dropped and no return link is shown.
`depositUrl`	string	No	URL for player to make deposits
`language`	string	No	ISO 639-1 language code (see Languages)
`country`	string	No	ISO 3166-1 alpha-2 country code

Opening the lobby instead of a single game

gameId is always required — leaving it blank returns {"error": "Validation error", "details": "Property 'GameID' is required"}. To open our multi-game lobby, pass the reserved lobby code 33d7ad7d-0d36-42cb-b818-79865aa73010 and let the player pick a game from there. Unlike the individual game codes, it is the same value in test and production.

The URL we return for a lobby launch has no game segment — https://game.marbles.xyz?otl=...&country=US&language=en — which is expected. Open it exactly as returned.

Don't confuse this with the lobbyUrl parameter above: that one is your lobby, where we send the player when they leave our games.

Success Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "url": "https://game.marbles.xyz?otl=ABCDE...XYZ&country=US&language=en"
}

Response Fields

Field	Type	Description
`url`	string	Game URL with one-time login token

Fun Money Mode

Demo Mode

You can generate a demo link that lets players test the game with fun money by:

Omitting clientSessionId and clientPlayerId
Setting currency to XXX

username is still required in demo mode — only clientSessionId and clientPlayerId are omitted. This is useful for game previews or demo modes on your platform.

Example Fun Money Request

{
  "operatorId": "operatorId",
  "partnerId": "my-casino",
  "gameId": "2469f711-2da6-46b7-8648-3313dfdc5bb5",
  "username": "demo-player",
  "currency": "XXX",
  "platform": "DESKTOP"
}

Multi-brand & aggregators

One integration covers all brands under your umbrella — you do not file a separate application per brand. Distinguish brands at runtime with partnerId on each /game/game/url call:

It's a free-form value you choose (e.g. a brand name) and needs no pre-registration.
It is not the same as operatorId (your integration ID) — never set partnerId equal to operatorId.

All brands under one operator config share its settings (liability, limits, key, callback URL). A brand that needs a different max exposure/liability, bet limits, commercial rates, signing key, or callback URL needs its own operator config — see Multi-brand & operator configs.

Multi-currency is supported under a single clientPlayerId — do not append the currency to the player ID. Pass the currency on each /game/game/url call; each call opens an independent session in that currency for the same player.

Error Responses

All errors use the {"error", "details"} shape. The most common one is the 404:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "Game not found",
  "details": "game with ID 2469f711-2da6-46b7-8648-3313dfdc5bb5 not found"
}

"Game not found" usually means access, not a typo

This response also fires when the UUID is perfectly valid but the game is not enabled for your integration/operator/partner. Verify the id against your own POST /game/games response — if the game is missing there too, contact us to have it added to your allowed games.

Error	HTTP Code	`details`	When
Game not found	404	`game with ID <uuid> not found`	Game not enabled for your integration (or genuinely unknown id)
Validation error	400	`Property 'OperatorID' is required`	A required field is missing
Validation error	400	`Invalid GameID: <value>`	`gameId` is not a UUID
Validation error	400	`ClientSessionId and clientPlayerId should be provided or omitted together`	Only one of the session/player pair was sent (see Fun Money Mode)
Validation error	400	`XXX currency is only allowed for demo users` / `<CUR> currency is not allowed for demo users`	Demo currency rules — `XXX` only without a session/player pair, real currencies only with one
Validation error	400	`ValidationError: Platform '<value>' does not exist`	`platform` outside `DESKTOP`/`MOBILE`/`TABLET` (case-sensitive)
Invalid operator id	400	`OperatorConfig with ID <id> not found`	Unknown `operatorId`
Bad request	400	`Currency not supported: <CUR>. Supported currencies: …`	Currency not on the supported list (see Currencies)
Bad request	400	`Invalid request body`	Malformed JSON

A 403 HTML error page (not JSON) means the request never reached the API: either your source IP is not on the registered whitelist, or the path is wrong — the correct path is /game/game/url; the /game really is doubled. An invalid lobbyUrl never errors: it is silently dropped and no return link is shown.

On this page