Skip to main content

​
Overview

Integrating with Upside.win is simple. Your game runs in an iframe on our platform, receives player authentication via JWT, and interacts with the Upside backend through our SDK for bet placement and payout processing. Key principle: Your backend handles game logic and state (cards, winners, outcomes), while Upside handles all WIN token transactions.

​
Integration Flow

1

Contact B3 Team

2

Game Loads in Iframe

Players launch your game, which loads inside an iframe on upside.win. Your game receives: - JWT token for the player - Player authentication context - Access to the Upside SDK
3

Frontend: Receive JWT

Wrap your game with ParentProvider from the Upside SDK to receive the JWT.
import { ParentProvider } from "@b3dotfun/upside-sdk";

export default function GameApp() {
  return (
    <ParentProvider>
      <YourGameComponent />
    </ParentProvider>
  );
}
4

Backend: Place Bet

When a player starts playing, your backend calls placeBet to lock in their wager.
{ createB3Client } from "@b3dotfun/upside-sdk/server"; 

const b3Client = createB3Client(); 
const betResult = await
b3Client.placeBet(
  "coin-flip", // gameType 
  "100000000000000000" // betAmount in wei (1 token = 10^18 wei) 
);
5

Backend: Handle Game Logic

Your backend: - Determines game outcome (coin lands on heads/tails) - Stores game state in your database - Calculates payout amount - Prepares outcome data (player choice, result, outcome)
6

Backend: Process Payout

When game ends, send the result to Upside to credit the player’s WIN balance.
const payoutResult = await b3Client.processPayout(
  "coin-flip",      // gameType
  sessionId,        // unique game session ID
  payoutAmount,     // WIN tokens to award (0 if loss)
  // gameData
  {
    playerChoice: "heads",
    result: "heads",
    outcome: "win"
  }
);
7

Frontend: Show Result

Your game displays the outcome to the player.The Upside platform automatically:
  • Updates the player’s WIN balance
  • Adds the win/loss to leaderboards
  • Sends notifications

​
Installation

npm install @b3dotfun/upside-sdk
# or
pnpm add @b3dotfun/upside-sdk
# or
bun install @b3dotfun/upside-sdk

​
Next Steps

Frontend Integration

Set up the ParentProvider and use hooks to access player data

Backend Integration

Initialize the B3 client and implement game logic

Testing & Examples

Test your game locally and see complete examples