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 /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
`username`	string	Yes	Unique username for the player
`currency`	string	Yes	ISO 4217 currency code (see Currencies)
`platform`	string	Yes	`"MOBILE"` or `"DESKTOP"`
`displayName`	string	No	Non-unique display name shown in game
`lobbyUrl`	string	No	URL to redirect player back to lobby
`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

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/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/url call; each call opens an independent session in that currency for the same player.

On this page