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

# 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.



**Integration surface**

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/frontend-integration)**

Upside hosts the game page, wallet login, WIN balance display, match history, and modal/toast surfaces.
  **[WIN Ledger](/upside/game-actions-api)**

Bets spend WIN atomically, payouts credit WIN atomically, and sessions are recorded for history and recovery.
  **[Game Discovery](/upside/testing-and-examples)**

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

## What You Own

**[Game Client](/upside/frontend-integration)**

Your iframe renders the game UI, listens for the player token, and sends UI events back to Upside.
  **[Game Server](/upside/backend-integration)**

Your backend verifies the player request, places the bet, runs the game, and settles the payout.
  **[Fairness & State](/upside/security-and-ops)**

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

## Player Flow

**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.
  **Iframe announces readiness**

Your frontend sends `{ type: "ready" }` to `https://upside.win`. Upside responds with the player's current `balance`, `token`, and `locale`.
  **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.
  **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.
  **Backend settles the result**

Your backend runs game logic, stores the outcome, and calls `trigger: "processPayout"` exactly once for the session.
  **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





## Start Building

**[Quickstart](/upside/quickstart)**

Wire the iframe bridge and make your first signed backend call.
  **[Frontend Integration](/upside/frontend-integration)**

Receive player context and control Upside modals, toasts, balance refreshes, and history refreshes.
  **[Backend Integration](/upside/backend-integration)**

Sign HMAC requests from a game worker and settle a complete game session.
  **[FAQ](/upside/faq)**

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