Create session
POST
/v1/sessions
Open a game for one of your players and get the URL to open it at.
SignedSandboxProduction
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| player_id | string | yes | Your reference, up to 120 characters. No player is created; it is what our wallet callbacks will name.Example: p-1 |
| currency | string | yes | ISO 4217, 3 to 10 characters. Fixed for the session.Example: EUR |
| game_id | string | yes | The catalogue id from GET /v1/games.Example: 6ddd5f30-0b1c-4c52-9f3e-2a7c1b8e4d10 |
| locale | string | no | en, ru-RU… translated to what the provider serves. |
| lobby_url | string | no | Where the game's "back to lobby" goes. |
| ttl_minutes | integer | no | 1..1440, default 240 (four hours). The launch is a bearer credential for a balance: keep it short. |
| player_country | string | no | ISO 3166-1 alpha-2, what you know of the player. Used only where the address says nothing. |
| player_ip | string | no | Send it. The player's own address, up to 45 characters; the country is read off it, and the game providers' country rules go by that.Example: 203.0.113.9 |
| player_device | string | no | desktop or mobile. |
| deposit_url | string | no | Up to 500 characters. Where a provider that supports it sends a player who ran out of money. |
| player_name | string | no | Up to 32 characters. The nickname other players see in multiplayer games (Callisto Minis tables and match feeds); other games ignore it. Never the player's real name. Absent, the game shows its own pseudonym; a changed nickname applies from the next session.Example: Ace_77 |
request
{
"player_id": "p-1",
"currency": "EUR",
"game_id": "6ddd5f30-0b1c-4c52-9f3e-2a7c1b8e4d10",
"locale": "en",
"lobby_url": "https://casino.example/lobby",
"player_ip": "203.0.113.9",
"player_device": "mobile"
}response 200
{
"session_id": "2222aaaa-5b6c-4d7e-8f90-a1b2c3d4e5f6",
"launch_url": "https://provider…/play?token=…",
"expires_at": "2026-09-29T16:00:00Z"
}Open the game at launch_url
Do not build a launch URL from a host and a game id. Providers move their launch hosts without notice, and a URL built from a list breaks the same day while looking like a broken game.Possible errors
| error | HTTP | Retry | When |
|---|---|---|---|
| VALIDATION_FAILED | 422 | no | A field is missing, out of range or of the wrong JSON type, or the body is not valid JSON. Every broken field is listed in fields with the rule it broke; "body" when the JSON does not parse. |
| GAME_UNAVAILABLE | 409 | no | The game is not in your window, whether or not it exists. |
| GAME_RESTRICTED_IN_COUNTRY | 409 | no | The game cannot be played in the player's country. |
| PLAYER_BLOCKED | 409 | no | The aggregator has stopped this player. No session opens until the block is lifted. |
Every endpoint can also answer UNAUTHORIZED, ADDRESS_NOT_ALLOWED, RATE_LIMITED and UPSTREAM_UNAVAILABLE. See the Error reference.
Notes
session_id and the token inside launch_url are different values: the token is a bearer credential, the id is what you may quote. Store session_id with the catalogue game_id you launched; wallet callbacks carry it.