Integrating Hyper into your platform

You can open Hyper inside an iframe on your platform. Hyper uses your existing login flow to authenticate your users, then handles the game and tournament experience inside the iframe.

Start with authentication. If you also want to display game and tournament cards on your platform, use the catalogue endpoints and launch URLs in this guide.

There are two ways to open Hyper:

• If your user is already signed in and you have their access token, open Hyper directly with the token.
• If you do not have a token yet, open the normal Hyper app URL. Hyper will send your user through your existing login flow when authentication is needed.

What we need to get started

What we will provide

We will give you:

What we need from you

Your configuration will look similar to this:

{
  "authInitUrl": "https://partner.example.com/hyper",
  "authVerifyUrl": "https://api.example.com/introspect",
  "baseAppUrl": "https://subdomain.example.hypergames.gg"
}

Use the Hyper app origin and API base URL we give you for your environment. The catalogue examples in this guide use the sandbox API.

Choose how to open Hyper

First, add the iframe to the page where you want Hyper to appear:

<iframe
  id="hyperFrame"
  title="Hyper Games"
  allow="autoplay; fullscreen"
></iframe>

Open Hyper directly with a token

Use this option when your user is already signed in to your platform and your frontend has their access token.

Build the launch URL and use it as the iframe source:

const HYPER_APP_ORIGIN = "https://subdomain.example.hypergames.gg";
const accessToken = getPartnerAccessToken();

const launchUrl = new URL("/auth/partner/launch", HYPER_APP_ORIGIN);
launchUrl.searchParams.set("token", accessToken);

document.querySelector("#hyperFrame").src = launchUrl.toString();

getPartnerAccessToken() represents the function you use to read the signed-in user's access token from your platform.

Hyper verifies the token through your authVerifyUrl, then continues with the authenticated user. You can go straight to Verify the access token below; the handoff page is only needed for the flow without a token.

Use a short-lived access token. Do not store or log the complete launch URL. Your refresh token should remain inside your platform.

Open Hyper without a token

Use this option if your user is not signed in yet or you want them to enter Hyper before authentication.

const HYPER_APP_ORIGIN = "https://subdomain.example.hypergames.gg";

document.querySelector("#hyperFrame").src = new URL(
  "/dashboard",
  HYPER_APP_ORIGIN
).toString();

When authentication is needed, Hyper navigates to your authInitUrl. That page uses your user's current session or completes your normal login flow, then returns to the launchUrl provided by Hyper.

Create your authentication handoff page

This step applies when you open Hyper without a token. Create a frontend route on your platform, such as /hyper, and send us its complete URL as your authInitUrl.

A loading message or spinner is enough. The page does not need to contain the Hyper iframe.

When Hyper needs your user's access token, it navigates to this page with state and launchUrl:

https://partner.example.com/hyper?state=<state>&launchUrl=<encoded-hyper-url>

When the page opens:

1. Check whether your user is signed in to your platform.
2. If they are signed in, read their current access token and continue to Send your user back to Hyper.
3. If they are not signed in, save the complete /hyper URL and start your normal login flow.
4. After login, return them to the saved URL so that state and launchUrl are still available.

The handoff page obtains the access token and returns the browser to Hyper. Our backend then calls your authVerifyUrl to verify the token.

Send your user back to Hyper

Once your user is signed in, add their access token to the supplied launchUrl as the token query parameter, then navigate to that URL.

const HYPER_APP_ORIGIN = "https://subdomain.example.hypergames.gg";

function returnToHyper() {
  const params = new URLSearchParams(window.location.search);
  const state = params.get("state");
  const launchUrl = params.get("launchUrl");
  const accessToken = getPartnerAccessToken();

  if (!state || !launchUrl || !accessToken) {
    throw new Error("Incomplete Hyper authentication request");
  }

  const target = new URL(launchUrl);

  if (target.origin !== HYPER_APP_ORIGIN) {
    throw new Error("Invalid Hyper launch URL");
  }

  target.searchParams.set("token", accessToken);
  window.location.replace(target.toString());
}

returnToHyper();

Replace the example origin with the one we give you. Check the origin before adding the token because launchUrl comes from the browser's query parameters. Keep the rest of the supplied URL unchanged so Hyper can continue the current request.

Verify the access token

Hyper calls your configured authVerifyUrl to verify the access token. For example, https://api.example.com/introspect.

If the token is valid, return the user:

{
  "userId": "42",
  "kycVerified": true,
  "currency": "USD",
  "firstName": "Ada",
  "lastName": "Okafor",
  "countryCode": "NG",
  "username": "ada@example.com",
  "metadata": {}
}

Only userId and currency are required. The other fields are optional.

Use the following status codes when verification fails:

Once we receive a valid user response, we complete the Hyper session and continue inside the iframe.

Get the games for your platform

Use this endpoint to get the games enabled for your platform:

GET https://hyper-sandbox-api.mvm.fyi/games/partners/{partner}/games?page=1&limit=20
Accept: application/json
x-api-key: <your-api-key>

The response contains a records array and pagination information. Display the games in records.

Use slug from the response when opening a game. Do not create a slug from its display name.

You can find the request and response details in Get games for partner.

Get the tournaments for your platform

Use this endpoint to get the multiplayer tournaments available for your platform:

GET https://hyper-sandbox-api.mvm.fyi/tournaments/partners/{partner}/tournaments?page=1&limit=20
Accept: application/json
x-api-key: <your-api-key>

Each tournament in records includes the following information:

The request details are in Get tournaments for partner.

Display the tournament status

Each tournament returned for your platform has one of three statuses:

Starting soon

Show Starting soon and a countdown such as Starts in 15 minutes. You can also show the scheduled start time using startDate in the user's local timezone.

If availableSlots is 0, show Full as an additional label. A full tournament can still be starting soon; capacity and status are separate pieces of information.

Use a View tournament button to open the tournament in Hyper. Hyper will show your user the entry options available to them.

Ongoing

Show Ongoing and a countdown such as Ends in 25 minutes. Use endDate if you also want to display the scheduled end time.

Keep a View tournament button available so your users can open the tournament details. Hyper will check whether the user can join or play and show the appropriate action.

Ended

Show Ended and stop the countdown. Do not show a button that invites the user to join or start a new entry.

You can keep a View tournament button for the details page. This status tells you that the tournament has ended. Results and reward information are shown separately inside Hyper.

Keep the status up to date

Use the returned status as the source of truth. You can decrease timeLeft locally to display a countdown, but refresh the list when the countdown reaches zero instead of changing the status yourself.

Also refresh when your user returns to the page. You can refresh periodically while the tournament section is visible to keep the status and available slots up to date. We will confirm the API limits with you for your integration.

Open the selected game or tournament

Use the game's slug from the API response to open the selected game or tournament. All paths below are relative to the Hyper app origin we give you.

For example, if your Hyper app origin is https://subdomain.example.hypergames.gg, the path /auth/partner/launch?token=<access-token>&game=<game-slug> becomes https://subdomain.example.hypergames.gg/auth/partner/launch?token=<access-token>&game=<game-slug>.

For the token launch, you can supply the slug in either the game query parameter or the launch path. If you supply both, the game query parameter takes precedence. You can also add tournament=<tournament-id> to the launch path version to select a tournament.

Open the selected item with a token

Use the iframe and access token from the authentication setup above.

For a game, add its slug as the game query parameter. For a tournament, add both game.slug and the tournament id:

const HYPER_APP_ORIGIN = "https://subdomain.example.hypergames.gg";

function openHyper({ accessToken, gameSlug, tournamentId }) {
  if (!accessToken || !gameSlug) {
    throw new Error("An access token and game slug are required");
  }

  const launchUrl = new URL("/auth/partner/launch", HYPER_APP_ORIGIN);
  launchUrl.searchParams.set("token", accessToken);
  launchUrl.searchParams.set("game", gameSlug);

  if (tournamentId) {
    launchUrl.searchParams.set("tournament", tournamentId);
  }

  document.querySelector("#hyperFrame").src = launchUrl.toString();
}

// From a game card:
openHyper({ accessToken, gameSlug: game.slug });

// From a tournament card:
openHyper({
  accessToken,
  gameSlug: tournament.game.slug,
  tournamentId: tournament.id,
});

Replace the example origin with the Hyper app origin we give you. The game slug and tournament ID should come directly from the selected record. A tournament ID by itself is not enough to select the tournament through the launch URL.

After authentication, Hyper continues to the selected game or tournament. If onboarding is required, Hyper keeps that destination for afterwards.

Open the selected page without a token

Use these direct URLs if your integration allows users to reach Hyper before authentication. They do not pass or verify an access token. If you want users to authenticate before entering Hyper, use the token launch URLs above.

Set the iframe source to the selected page on your Hyper app origin:

const HYPER_APP_ORIGIN = "https://subdomain.example.hypergames.gg";

function openHyperPage({ gameSlug, tournamentId }) {
  if (!gameSlug) {
    throw new Error("A game slug is required");
  }

  const gamePath = `/games/${encodeURIComponent(gameSlug)}`;
  const path = tournamentId
    ? `${gamePath}/tournaments/${encodeURIComponent(tournamentId)}`
    : `${gamePath}/play`;

  document.querySelector("#hyperFrame").src = new URL(
    path,
    HYPER_APP_ORIGIN
  ).toString();
}

When authentication is needed, Hyper uses the authentication handoff described above. Return to the supplied launchUrl so your user continues to the selected game or tournament.