Game launch

Zero-Dash does not hand out static game URLs. You mint one per launch, bound to the player’s session token and IP address, and open it in the browser.

The flow

Note what happens at the end: the Player authorization callback fires after the launch URL is opened. If that endpoint is not working, the launch URL still returns 200 and the game still opens — and then fails to start. When a launch appears to hang, check your /player handler first.

Launching

Get the game slug

From List games, cached. Slugs are stable, human-readable identifiers such as lucky-duck.

Mint a session token

Unique, non-deterministic, valid for at least 2 hours. See Session token.

Request the launch URL

Call Obtain game launch URL with the token, the player’s currency and the player’s real IP address.

GET /api/v1/games/lucky-duck?ipAddress=1.2.3.4&freeToPlay=false&currency=USD&token=abc123&lang=en
X-Operator: your-operator-id
X-Zd-Signature: 0c8857b40faa035e…
X-Zd-Timestamp: 1778920901644

{
  "data": { "url": "https://games.zerodash.studio/lucky-duck?s=eyJhbGciOi..." }
}

Open it

A new tab or window is the supported path. An iframe works but carries requirements and caveats.

Call this endpoint at click time, not ahead of time. The URL is tied to the token and IP you passed in — pre-generating URLs for a whole catalogue page produces links that break as soon as anything about the session changes.

Launch parameters

Parameter	Required	Notes
`gameSlug` (path)	Yes	From the games list
`ipAddress`	Yes	The player’s browser IP, not your server’s — it drives country restrictions
`freeToPlay`	Yes	`false` for real money, `true` for demo mode
`currency`	Real money only	ISO-4217. Omit when `freeToPlay=true`
`token`	Real money only	Your session token. Omit when `freeToPlay=true`
`lang`	No	ISO 639-1. Autodetected when omitted

Behind a CDN or load balancer, ipAddress must be the leftmost trustworthy entry of X-Forwarded-For, not the socket peer. Send your own egress IP and every player looks like they are in your datacentre — country restrictions will apply to the wrong jurisdiction.

Opening the game

New tab — preferred
Iframe — not recommended

Best compatibility and the best experience on every device.

// Open the tab synchronously in the click handler, then navigate it.
// Doing the fetch first gets the popup blocked in Safari and Firefox.
function launchGame(slug) {
  const tab = window.open('', '_blank');
  fetch(`/api/games/${slug}/launch`, { method: 'POST' })
    .then((r) => r.json())
    .then(({ url }) => { tab.location.href = url; })
    .catch(() => tab.close());
}

The popup blocker only allows window.open during a user gesture. Open the blank tab first, resolve the URL after — the pattern above is the reason this works.

Supported, but you own the sizing and the browser quirks. Read Iframe integration before choosing this.

<iframe
  src="https://games.zerodash.studio/lucky-duck?s=..."
  allow="fullscreen"
  style="width: 100lvw; height: 95lvh; border: 0;"
></iframe>

Failure modes

404 on the launch URL request

The slug is unknown or the game is not enabled for your account. Refresh your cached catalogue; if the slug is there and still fails, the game is not provisioned for you — contact integrations.

Launch URL returns 200 but the game will not start

Almost always your /player callback: unreachable, returning a non-200, failing signature verification, or returning a balance in the wrong currency. Check your callback logs for a GET /player around the launch time.

The game opens for some players and not others

Country restrictions, driven by ipAddress. Check restrictedCountries on the game in your cached catalogue against where the affected players actually are.

The player is bounced back to the lobby mid-session

The session token expired or was invalidated. Tokens need at least 2 hours of validity and must survive a client reload. See Session token.

Get started

Launch games

Security

Wallet integration

Free rounds

Go live

The flow

Launching

Launch parameters

Opening the game

Failure modes

​The flow

​Launching

​Launch parameters

​Opening the game

​Failure modes

The flow

Launching

Launch parameters

Opening the game

Failure modes