Upside Integration

Build iframe games for Upside.win with the frontend bridge, signed backend API, and WIN credit settlement flow.

Build games for Upside.win

Upside turns staked or deposited assets into WIN credits players can use across casino-style games. Game partners bring the gameplay, rules, animations, and outcome logic. Upside provides the player shell, authentication token, WIN balance, game session ledger, payout settlement, match history, and player-facing win/loss UI.

Upside game lobby

The current integration is an iframe bridge plus a signed backend API. Your frontend receives the player JWT from Upside by postMessage; your backend signs POST /upside/game-actions requests with HMAC credentials issued for your game.

What Upside Owns

Player Shell

Upside hosts the game page, wallet login, WIN balance display, match history, and modal/toast surfaces.

Learn More
WIN Ledger

Bets spend WIN atomically, payouts credit WIN atomically, and sessions are recorded for history and recovery.

Learn More
Game Discovery

Approved games appear in the Upside lobby and can also be tested through a localhost iframe route.

Learn More

What You Own

Game Client

Your iframe renders the game UI, listens for the player token, and sends UI events back to Upside.

Learn More
Game Server

Your backend verifies the player request, places the bet, runs the game, and settles the payout.

Learn More
Fairness & State

Your backend is the source of truth for random outcomes, session state, retry handling, and abuse controls.

Learn More

Player Flow

1

Player opens your game inside Upside

Upside loads the approved workerUrl in an iframe at /games/{slug}. For local development, the test route loads a base64-encoded localhost URL.

2

Iframe announces readiness

Your frontend sends { type: "ready" } to https://upside.win. Upside responds with the player's current balance, token, and locale.

3

Frontend calls your backend

Your iframe sends player choices and bet size to your backend with Authorization: Bearer {token}. Do not call the Upside game-actions API directly from the browser.

4

Backend places the bet

Your backend signs an HMAC request to POST /upside/game-actions with trigger: "placeBet". Upside atomically spends the player's WIN and creates a game session.

5

Backend settles the result

Your backend runs game logic, stores the outcome, and calls trigger: "processPayout" exactly once for the session.

6

Frontend refreshes the Upside shell

Your iframe posts showWinModal, showLossModal, refetchBalance, or refreshMatchHistory so the parent shell stays in sync.

Architecture

mermaid
sequenceDiagram
  participant Player
  participant Upside as Upside.win parent shell
  participant GameUI as Your iframe frontend
  participant GameAPI as Your game backend
  participant B3API as B3 API /upside/game-actions

  Player->>Upside: Open /games/{slug}
  Upside->>GameUI: Load approved workerUrl iframe
  GameUI->>Upside: postMessage({ type: "ready" })
  Upside->>GameUI: postMessage({ token, balance, locale })
  GameUI->>GameAPI: POST /play with Bearer token
  GameAPI->>B3API: HMAC placeBet + B3-JWT
  B3API-->>GameAPI: sessionId, gameId, userBalance
  GameAPI->>GameAPI: Resolve game outcome
  GameAPI->>B3API: HMAC processPayout + B3-JWT
  B3API-->>GameAPI: updated userBalance
  GameAPI-->>GameUI: result payload
  GameUI->>Upside: showWinModal / showLossModal
  GameUI->>Upside: refetchBalance + refreshMatchHistory

Visual Tour

Upside game page iframe shell Upside leaderboard

Start Building

Quickstart

Wire the iframe bridge and make your first signed backend call.

Learn More
Frontend Integration

Receive player context and control Upside modals, toasts, balance refreshes, and history refreshes.

Learn More
Backend Integration

Sign HMAC requests from a game worker and settle a complete game session.

Learn More
FAQ

Answers for token units, localhost testing, duplicate payouts, max bets, and launch readiness.

Learn More
Next Quickstart
Ask a question... ⌘I