> ## Documentation Index
> Fetch the complete documentation index at: https://docs.smatvirtual.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Game Launch Sequence

> How to generate a secure, authenticated URL to launch smatvirtual games.

The Launch Sequence is the final step in the integration. Your backend requests a signed URL from the **smatvirtual** gateway, which you then use to redirect the player into the game interface.

## The Workflow

1. **Request:** Your server calls the `launch-url` endpoint with player and game metadata.
2. **Validation:** We verify your `sv-api-key` and check player details via your [Details URL](/webhooks/player-details).
3. **Resolution:** Our gateway generates a secure, time-limited link.
4. **Redirect:** You send the player to that link.

## Currency Synchronization

When initiating a launch request, it is vital to ensure that your player's wallet currency aligns with your account configuration.

<Note>
  **Important:** Currently, both the player's currency and the operator's base
  currency of operation must match exactly (e.g., if your operator account is
  set to NGN, the player must also be playing in NGN).
</Note>

### Multi-Currency Roadmap

We are currently developing a robust multi-currency engine that will allow players to play in any currency regardless of the operator's base setting.

> **Experimental Phase:** This feature is currently in an experimental phase. Our engineering team is testing the automated conversion and settlement logic. All merchants and partners will receive an official notification once this restriction is lifted and multi-currency support is globally available.

***

## The Launch Request

**Endpoint:** `GET /operator-api/games/generate-launch-url`\
**Base URL:** `https://api.smatvirtual.com/api/v1.1`

### Query Parameters

| Parameter          | Type      | Required | Description                                                               |
| :----------------- | :-------- | :------- | :------------------------------------------------------------------------ |
| `gameId`           | `string`  | **Yes**  | The unique slug for the game (e.g., `spin-win`, `odd-even`).              |
| `playerId`         | `string`  | **Yes**  | Your internal unique identifier for the player.                           |
| `sessionId`        | `string`  | **Yes**  | A unique string for this specific session (used for tracking).            |
| `mode`             | `string`  | No       | Use `real` for money play or `demo` for free play. Defaults to `real`.    |
| `disableGameLobby` | `boolean` | No       | Set to `true` to skip the selection screen and go straight to the game.   |
| `currency`         | `string`  | No       | ISO code (e.g., `USD`). If omitted, we use the player's default currency. |

***

## Implementation Example

Your backend should construct the request as follows. Ensure your **sv-api-key** is included in the headers.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.smatvirtual.com/api/v1.1/operator-api/games/generate-launch-url?gameId=spin-win&playerId=user_99&sessionId=sess_unique_123&disableGameLobby=true&mode=real' \
    --header 'sv-api-key: SV.pk_live_xxxx.smatvirtual-slug'
  ```

  ```javascript index.js theme={null}
  const axios = require("axios");

  async function getLaunchLink() {
    const response = await axios.get(
      "https://api.smatvirtual.com/api/v1.1/operator-api/games/generate-launch-url",
      {
        params: {
          gameId: "spin-win",
          playerId: "user_99",
          sessionId: "unique_session_001",
          disableGameLobby: true,
          mode: "real",
        },
        headers: { "sv-api-key": "SV.pk_live_xxxx.smatvirtual-slug" },
      },
    );

    // Redirect the user to the returned URL
    return response.data.url;
  }
  ```
</CodeGroup>

## Understanding the Response

A successful request returns a JSON object containing the url.

<CodeGroup>
  ```JSON theme={null}

  {
    "success": true,
    "url": "https://instant.smatvirtual.com/v1/play?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpX..."
  }
  ```
</CodeGroup>

## Important Considerations

<CardGroup cols={2}>
  <Card title="Token Expiry" icon="clock">
    Launch URLs are time-sensitive. You should redirect the player immediately
    after receiving the URL. Do not cache these links.
  </Card>

  <Card title="Iframe vs. Redirect" icon="window-maximize">
    You can either redirect the player's browser or embed the URL in an
    \<iframe>. If using an iframe, ensure it is set to 100% width and
    height for the best experience.
  </Card>
</CardGroup>

## Troubleshooting common errors

| Error Code       | Meaning         | Solution                                                       |
| ---------------- | --------------- | -------------------------------------------------------------- |
| 401 Unauthorized | Invalid API Key | Check your sv-api-key format (Prefix.Key.Slug).                |
| 404 Not Found    | Invalid gameId  | Verify the game id matches one from the /games list.           |
| 504 Timeout      | Wallet Timeout  | Your Details URL took too long to return the player's balance. |

<Note>
  Next Step: Once the player is in the game, all bets and wins will be
  communicated to your system via Webhooks.
</Note>