Launch Game
Launch a player session with a starting balance, approved return URLs, and an idempotency key.
/v1/commandsgetGameIdempotency key requiredOn this page
Before launching#
getGame requires scope proxy:getGame or proxy:*, production activation, positive workspace GGR funding, currency/game access, and a configured callback. Both return URL origins must be allowlisted in Workspace Settings.
Reserve the player's starting funds in your own wallet before launch. The API does not debit that wallet for you. Keep the reservation attached to the operation until its outcome is known.
Request#
POST https://aggregatornetwork.com/v1/commands
X-API-Key: YOUR_APPLICATION_API_KEY
Idempotency-Key: launch-player1001-operation001
Content-Type: application/json{
"method": "getGame",
"lang": "en",
"user_username": "player-1001",
"gameid": "12/737",
"homeurl": "https://operator.example/lobby",
"cashierurl": "https://operator.example/cashier",
"currency": "USD",
"balance": 1000
}Replace the illustrative game ID with the exact catalogue identifier, and use your approved URLs and currency.
| Field | Required | Meaning and bounds |
|---|---|---|
user_username | Yes | Stable player identifier, 1–128 characters; no control characters |
gameid | Yes | Exact catalogue ID, up to 255 characters |
currency | Yes | Entitled three-letter uppercase code with provider/game coverage |
balance | Yes | Finite JSON number from 0 through 1000000000, in the game currency |
lang | Yes | Short language tag, 2–12 characters, such as en |
homeurl, cashierurl | Yes | Absolute HTTPS URLs without credentials; each origin must be allowed |
play_for_fun | No | Compatibility field 0 or 1, default 0; use getGameDemo for a demo |
logo | No | Public HTTPS PNG option for supported Bharat Matka launches |
rtp | No | Number from 0 to 100, for supported IG ORIGINALS launches |
balance must be a number, not a decimal string. Choose the amount using the currency's precision and avoid floating-point calculations that alter it.
Response#
{
"error": 0,
"response": "https://provider.example/temporary-launch-url",
"session_id": "request-id"
}Require HTTP success and error === 0. Open only the returned URL; it is temporary. Store the operation and request ID securely. Player mapping is automatic; createPlayer is optional.
Recovery#
Persist the idempotency key and exact request before dispatch. An identical replay may return a retained result; launch URLs are sensitive and are not guaranteed to remain replayable. Never generate a new key simply because the caller timed out.
For UPSTREAM_OUTCOME_UNKNOWN, IDEMPOTENCY_OUTCOME_UNKNOWN, or an unavailable/expired result, retain the wallet reservation and reconcile through Request Logs and support. See validation and settlements.