Backend Integration

Initialize the B3 client in your backend to handle bet placement, game logic, and payout processing.

createB3Client

Initialize the B3 client in your backend to interact with Upside’s API.

Framework Support: Currently supports Hono with Cloudflare Workers.

import { createB3Client } from "@b3dotfun/upside-sdk/server";

// In your Hono route handler
app.post("/api/game/play", async c => {
  // Create B3Client from Hono context
  // Automatically extracts auth token from Authorization header
  const b3Client = createB3Client(c);

  // Now use b3Client for game operations
  const betResult = await b3Client.placeBet("coin-flip", "1000000000000000000");

  return c.json({ success: true, sessionId: betResult.sessionId });
});

Parameters:

• context (Hono Context): The Hono context object containing:
  • req.header(name: string): Method to extract request headers
  • env (optional): Cloudflare Workers environment

Returns:

• B3Client instance with authentication automatically configured from the Authorization header

Authentication: The Authorization header is automatically extracted from the incoming request:

Authorization: Bearer {player_token}

Core Functions

placeBet

Start a game session by placing a bet. This locks in the wager and creates a game session.

const betResult = await b3Client.placeBet(
  gameType, // string: "coin-flip", "dice", etc.
  betAmount, // string: bet in wei (e.g., "100000000000000000" = 1 token)
);

// Response:
// {
//   sessionId: "session_abc123",
//   gameId: "game_xyz789",
//   status: "active",
//   createdAt: "2024-01-15T10:30:00Z"
// }

Parameters:

• gameType (string): Your game’s identifier (e.g., “coin-flip”, “dice-roll”)
• betAmount (string): Bet amount in wei (1 token = 10^18 wei, e.g., “100000000000000000”)

Returns:

• sessionId: Unique identifier for this game session
• gameId: Game record identifier
• status: Current session status (“active”, “completed”, “failed”)
• createdAt: ISO timestamp of bet creation

Errors:

• Insufficient player balance
• Invalid game type
• Game not active/enabled
• Invalid bet amount

processPayout

Complete the game and credit the player’s winnings.

const payoutResult = await b3Client.processPayout(
  gameType, // string: "coin-flip", etc.
  sessionId, // string: from placeBet response
  payoutAmount, // string: WIN to award in wei (0 for loss)
  {
    playerChoice: "heads", // what player chose/predicted
    result: "heads", // actual game result
    outcome: "win", // "win" or "loss"
  },
);

// Response:
// {
//   status: "completed",
//   payoutAmount: "150000000000000000",
//   newBalance: "1350000000000000000",
//   updatedAt: "2024-01-15T10:30:30Z"
// }

Parameters:

• gameType (string): Same game type from placeBet
• sessionId (string): Session ID from placeBet response
• payoutAmount (string): WIN tokens to credit in wei (0 for losses, e.g., “150000000000000000” = 1.5 tokens)
• metadata (object):
  • playerChoice: What the player chose/predicted
  • result: The actual game outcome
  • outcome: “win” or “loss”

Returns:

• status: “completed”, “failed”, etc.
• payoutAmount: Amount credited in wei
• newBalance: Player’s updated WIN balance in wei
• updatedAt: ISO timestamp of completion

Errors:

• Session not found
• Session already completed (duplicate request)
• Payout exceeds pool limits
• Invalid bet amount format

Backend Example

import { Hono } from "hono";
import { createB3Client } from "@b3dotfun/upside-sdk/server";

const app = new Hono();

app.post("/api/game/coin-flip", async c => {
  const { prediction, betAmount } = await c.req.json();

  try {
    // Create B3Client from Hono context
    // Automatically extracts auth token from Authorization header
    const b3Client = createB3Client(c);

    // Step 1: Place the bet (amount in wei)
    const betResult = await b3Client.placeBet("coin-flip", betAmount);

    if (!betResult.sessionId) {
      return c.json({ error: "Failed to place bet" }, 400);
    }

    // Step 2: Game logic - flip coin
    const coin = Math.random() < 0.5 ? "heads" : "tails";
    const isWin = coin === prediction;
    // Calculate payout: 50% profit on win (betAmount * 1.5, in wei)
    const payout = isWin ? (BigInt(betAmount) * BigInt(150)) / BigInt(100) : "0";

    // Step 3: Store game in your database (D1, etc.)
    // await db.execute(
    //   "INSERT INTO games (sessionId, prediction, result, betAmount, payout) VALUES (?, ?, ?, ?, ?)",
    //   [betResult.sessionId, prediction, coin, betAmount, payout.toString()]
    // );

    // Step 4: Process payout
    const payoutResult = await b3Client.processPayout("coin-flip", betResult.sessionId, payout.toString(), {
      playerChoice: prediction,
      result: coin,
      outcome: isWin ? "win" : "loss",
    });

    // Step 5: Return result to frontend
    return c.json({
      sessionId: betResult.sessionId,
      prediction,
      result: coin,
      outcome: isWin ? "win" : "loss",
      payout: isWin ? payout.toString() : "0",
      newBalance: payoutResult.newBalance,
    });
  } catch (error) {
    console.error("Game error:", error);
    return c.json({ error: error.message }, 500);
  }
});

export default app;

Key Differences from Express:

• createB3Client(c) extracts auth automatically from Hono context
• Runs on Cloudflare Workers (serverless)
• No need for manual middleware - Hono context handles everything
• Response uses c.json() instead of res.json()

Environment Setup (wrangler.toml):

[env.production]
name = "upside-games"
route = "example.com/api/*"
zone_id = "..."
account_id = "..."

[[env.production.env.vars]]
# Add any environment variables here

Best Practices

Bet Placement

• Always validate amounts: Check bet is within player balance
• Use idempotency: Retry failed placeBet calls with the same sessionId
• Lock immediately: Once placeBet succeeds, prevent player from placing another bet

Game Logic

• Backend is source of truth: Never trust client-side game outcomes
• Store everything: Log all game events for audits and disputes
• Validate results: Ensure game outcome matches expected range
• Timeout games: Cancel bets if no payout is processed within 5 minutes

Payout Processing

• Process once: Only call processPayout once per game session
• Use correct amounts: Verify payout calculation before sending
• Handle duplicates: If processPayout returns “already completed”, that’s OK
• Handle failures: Retry failed payouts, but check if already paid first

Security

• Verify tokens: Always validate JWT in every backend request
• Use HTTPS: All communication must be encrypted
• Validate game types: Only allow known, approved game types
• Rate limit: Implement rate limiting to prevent abuse

Error Handling

async function safePlayGame(gameType, betAmount) {
  try {
    // Place bet
    let betResult;
    try {
      betResult = await b3Client.placeBet(gameType, betAmount);
    } catch (error) {
      if (error.message.includes("Insufficient balance")) {
        return { error: "Player balance too low" };
      }
      throw error;
    }

    // Run game logic
    const outcome = await runGameLogic();

    // Process payout
    try {
      const payout = outcome.isWin ? betAmount * 1.5 : "0";
      await b3Client.processPayout(gameType, betResult.sessionId, payout, {
        playerChoice: outcome.choice,
        result: outcome.result,
        outcome: outcome.isWin ? "win" : "loss",
      });
    } catch (error) {
      if (error.message.includes("already completed")) {
        console.log("Payout already processed for session");
      } else {
        throw error;
      }
    }

    return outcome;
  } catch (error) {
    console.error("Game error:", error);
    throw error;
  }
}