dubs-server 1.0.0

package/routes/gamesRoutes.js

@@ -0,0 +1,3028 @@
+/**
+ * Games Routes - Handle sports betting games
+ */
+
+const express = require('express');
+const router = express.Router();
+const { pool } = require('../services/db'); // Shared database pool
+const notificationCacheService = require('../services/notificationCacheService');
+const referralEarningsService = require('../services/referralEarningsService');
+const discordNotifications = require('../services/discordNotifications');
+const connect4GameService = require('../services/connect4GameService');
+const gamesCacheService = require('../services/gamesCacheService');
+
+// Matchup image generation (lazy loaded to avoid startup failures if canvas not installed)
+let matchupImageService = null;
+let s3Service = null;
+
+function getMatchupImageService() {
+  if (!matchupImageService) {
+    try {
+      matchupImageService = require('../services/matchupImageService');
+      console.log('🎨 Matchup image service loaded');
+    } catch (err) {
+      console.warn('⚠️ Matchup image service not available:', err.message);
+      console.warn('   Install canvas: npm install canvas');
+    }
+  }
+  return matchupImageService;
+}
+
+function getS3Service() {
+  if (!s3Service) {
+    try {
+      const S3Service = require('../services/s3Service');
+      s3Service = new S3Service();
+    } catch (err) {
+      console.warn('⚠️ S3 service not available:', err.message);
+    }
+  }
+  return s3Service;
+}
+
+/**
+ * Calculate correct pool amounts for games (handles legacy + pari-mutuel hybrid)
+ * For legacy players (not in player_amounts), uses buy_in
+ * For pari-mutuel players, uses their actual bet amount from player_amounts
+ */
+function calculatePoolAmounts(game) {
+  const buyIn = parseFloat(game.buy_in) || 0;
+  const playerAmounts = game.player_amounts || {};
+  const homePlayers = game.home_team_players || [];
+  const awayPlayers = game.away_team_players || [];
+  const drawPlayers = game.draw_team_players || [];
+
+  // Calculate pool for each team by summing player amounts
+  // Legacy players (not in playerAmounts) use the fixed buy_in
+  const calcTeamPool = (players) => {
+    return players.reduce((sum, wallet) => {
+      const amount = playerAmounts[wallet] !== undefined
+        ? parseFloat(playerAmounts[wallet])
+        : buyIn;
+      return sum + amount;
+    }, 0);
+  };
+
+  const homePool = calcTeamPool(homePlayers);
+  const awayPool = calcTeamPool(awayPlayers);
+  const drawPool = calcTeamPool(drawPlayers);
+  const totalPool = homePool + awayPool + drawPool;
+
+  return {
+    homePool: homePool || undefined,
+    awayPool: awayPool || undefined,
+    drawPool: drawPool || undefined,
+    totalPool: totalPool || undefined,
+  };
+}
+
+/**
+ * Get short nickname for EPL teams
+ * Maps full team names to commonly used short names
+ */
+const EPL_NICKNAMES = {
+  'manchester city': 'Man City',
+  'manchester united': 'Man Utd',
+  'wolverhampton wanderers': 'Wolves',
+  'tottenham hotspur': 'Spurs',
+  'nottingham forest': "Nott'm Forest",
+  'brighton and hove albion': 'Brighton',
+  'brighton & hove albion': 'Brighton',
+  'west ham united': 'West Ham',
+  'newcastle united': 'Newcastle',
+  'leeds united': 'Leeds',
+  'afc bournemouth': 'Bournemouth',
+  'crystal palace': 'Crystal Palace',
+  'aston villa': 'Aston Villa',
+  'leicester city': 'Leicester',
+  'sheffield united': 'Sheffield Utd',
+};
+
+function getTeamNickname(teamName) {
+  if (!teamName) return teamName;
+  const lowerName = teamName.toLowerCase().trim();
+  return EPL_NICKNAMES[lowerName] || teamName;
+}
+
+// Socket.IO will be injected
+let io = null;
+let chatNamespace = null;
+
+// Inject Socket.IO instance
+router.setSocketIO = (ioInstance, chatNS) => {
+  io = ioInstance;
+  chatNamespace = chatNS;
+  console.log('🔌 Socket.IO injected into games routes');
+};
+
+/**
+ * Enrich gameInvite with S3 matchup URL from games table
+ * Replaces data URLs with S3 URLs for better performance
+ * @param {Pool} pool - Database connection pool
+ * @param {Object} gameInvite - Game invite object (may have data URL)
+ * @returns {Promise<Object>} - Enriched gameInvite with S3 URL
+ */
+async function enrichGameInviteWithS3Url(pool, gameInvite) {
+  if (!gameInvite?.gameId) {
+    return gameInvite;
+  }
+
+  try {
+    const gameUrlResult = await pool.query(
+      'SELECT matchup_image_url FROM games WHERE game_id = $1',
+      [gameInvite.gameId]
+    );
+    
+    if (gameUrlResult.rows.length > 0 && gameUrlResult.rows[0].matchup_image_url) {
+      return {
+        ...gameInvite,
+        matchupImageUrl: gameUrlResult.rows[0].matchup_image_url,
+      };
+    }
+  } catch (error) {
+    console.error('[gamesRoutes] Error enriching gameInvite with S3 URL:', error.message);
+  }
+
+  return gameInvite; // Return original if enrichment fails
+}
+
+/**
+ * Generate matchup image and upload to S3
+ * Updates the game record with the matchup_image_url
+ * 
+ * @param {string} gameId - Game ID
+ * @param {Object} sportsEvent - Sports event data with team names and league
+ */
+async function generateAndUploadMatchupImage(gameId, sportsEvent) {
+  const league = sportsEvent.strLeague?.toUpperCase() || 'NHL';
+
+  // Extract just the league abbreviation from full name
+  // e.g., "National Hockey League" -> "NHL"
+  const leagueMap = {
+    'NATIONAL HOCKEY LEAGUE': 'NHL',
+    'NATIONAL BASKETBALL ASSOCIATION': 'NBA',
+    'NATIONAL FOOTBALL LEAGUE': 'NFL',
+    'MAJOR LEAGUE BASEBALL': 'MLB',
+    'ENGLISH PREMIER LEAGUE': 'EPL',
+    'ULTIMATE FIGHTING CHAMPIONSHIP': 'UFC',
+    'FIGHTING': 'UFC',
+    'NCAA DIVISION I BASKETBALL MENS': 'NCAAB',
+    'NCAA DIVISION 1 COLLEGE FOOTBALL': 'NCAAF',
+    'NHL': 'NHL',
+    'NBA': 'NBA',
+    'NFL': 'NFL',
+    'MLB': 'MLB',
+    'EPL': 'EPL',
+    'UFC': 'UFC',
+    'NCAAB': 'NCAAB',
+    'NCAAF': 'NCAAF'
+  };
+  const normalizedLeague = leagueMap[league.toUpperCase()] || league.toUpperCase();
+
+  // UFC now uses local fighter images just like other sports
+  // No special handling needed - falls through to standard matchup generation below
+
+  // For non-UFC leagues, we need the matchup image services
+  const matchupService = getMatchupImageService();
+  const s3 = getS3Service();
+
+  if (!matchupService || !s3 || !s3.isConfigured()) {
+    console.log(`[MatchupImage] Skipping for ${gameId} - services not available`);
+    return null;
+  }
+
+  const homeTeam = sportsEvent.strHomeTeam;
+  const awayTeam = sportsEvent.strAwayTeam;
+
+  if (!homeTeam || !awayTeam) {
+    console.log(`[MatchupImage] Skipping for ${gameId} - missing team names`);
+    return null;
+  }
+
+  // EPL and UFC use "Home vs Away" convention, US sports use "Away @ Home"
+  const isHomeFirst = normalizedLeague === 'EPL' || normalizedLeague === 'UFC';
+  const leftTeam = isHomeFirst ? homeTeam : awayTeam;
+  const rightTeam = isHomeFirst ? awayTeam : homeTeam;
+
+  console.log(`[MatchupImage] Generating for ${gameId}: ${leftTeam} vs ${rightTeam} (${normalizedLeague}) [HomeFirst=${isHomeFirst}]`);
+
+  try {
+    // Key uses left_right order to match the visual layout
+    const matchupKey = s3.getMatchupImageKey(leftTeam, rightTeam, normalizedLeague);
+
+    // For EPL, always regenerate (don't reuse old images that may have wrong team order)
+    // For other leagues, check if image already exists to allow reuse
+    const isEPL = normalizedLeague === 'EPL';
+    const exists = isEPL ? false : await s3.matchupImageExists(matchupKey);
+
+    let publicUrl;
+    if (exists) {
+      // Image already exists, reuse it (non-EPL only)
+      // Add cache-busting timestamp for consistency
+      const cacheBuster = Date.now();
+      publicUrl = `https://${s3.bucketName}.s3.${s3.region}.amazonaws.com/${matchupKey}?v=${cacheBuster}`;
+      console.log(`[MatchupImage] ♻️  Reusing existing image for ${leftTeam} vs ${rightTeam}`);
+    } else {
+      // Generate the image at full quality (600x315), will be resized to 300x158 on upload
+      const result = await matchupService.generateMatchupImage({
+        homeTeam,
+        awayTeam,
+        league: normalizedLeague,
+        width: 600,
+        height: 315
+      });
+
+      // Upload to S3 (force overwrite for EPL to replace bad images)
+      // Key uses left_right order to match the visual layout
+      const uploadResult = await s3.uploadMatchupImage(leftTeam, rightTeam, normalizedLeague, result.buffer, isEPL);
+      publicUrl = uploadResult.publicUrl;
+
+      if (uploadResult.wasReused && !isEPL) {
+        console.log(`[MatchupImage] ♻️  Image was created by another process, reusing it`);
+      }
+    }
+
+    // Update the game record with the URL
+    await pool.query(`
+      UPDATE games 
+      SET matchup_image_url = $1, updated_at = NOW()
+      WHERE game_id = $2
+    `, [publicUrl, gameId]);
+
+    console.log(`[MatchupImage] ✅ Saved for ${gameId}: ${publicUrl}`);
+
+    return publicUrl;
+  } catch (err) {
+    console.error(`[MatchupImage] ❌ Failed for ${gameId}:`, err.message);
+    throw err;
+  }
+}
+
+// Database connection - using shared pool from services/db.js
+
+// Initialize games tables
+async function initializeTables() {
+  try {
+    // Create games table
+    await pool.query(`
+      CREATE TABLE IF NOT EXISTS games (
+        id SERIAL PRIMARY KEY,
+        game_id VARCHAR(255) UNIQUE NOT NULL,
+        game_address VARCHAR(255) NOT NULL,
+        title VARCHAR(500),
+        image_url TEXT,
+        game_type VARCHAR(50),
+        buy_in DECIMAL(20, 9),
+        max_players INTEGER DEFAULT 0,
+        game_mode INTEGER,
+        created_by VARCHAR(255) NOT NULL,
+        sports_event JSONB,
+        home_team_players TEXT[] DEFAULT '{}',
+        away_team_players TEXT[] DEFAULT '{}',
+        lock_timestamp BIGINT,
+        is_locked BOOLEAN DEFAULT false,
+        is_resolved BOOLEAN DEFAULT false,
+        automatic_status VARCHAR(50),
+        lock_notification_sent_10min BOOLEAN DEFAULT false,
+        lock_notification_sent_now BOOLEAN DEFAULT false,
+        created_at TIMESTAMP DEFAULT NOW(),
+        updated_at TIMESTAMP DEFAULT NOW()
+      )
+    `);
+
+    // Create user_game_refs table (user-specific game data)
+    await pool.query(`
+      CREATE TABLE IF NOT EXISTS user_game_refs (
+        id SERIAL PRIMARY KEY,
+        wallet_address VARCHAR(255) NOT NULL,
+        game_id VARCHAR(255) NOT NULL,
+        role VARCHAR(50),
+        joined_at TIMESTAMP,
+        team_choice VARCHAR(10),
+        my_signature VARCHAR(255),
+        my_explorer_url TEXT,
+        status VARCHAR(50),
+        wallet_type VARCHAR(50),
+        claimed_at TIMESTAMP,
+        claim_signature TEXT,
+        claim_explorer_url TEXT,
+        amount_claimed DECIMAL(20, 9),
+        created_at TIMESTAMP DEFAULT NOW(),
+        updated_at TIMESTAMP DEFAULT NOW(),
+        UNIQUE(wallet_address, game_id)
+      )
+    `);
+
+    // Create audit_logs table
+    await pool.query(`
+      CREATE TABLE IF NOT EXISTS audit_logs (
+        id SERIAL PRIMARY KEY,
+        log_type VARCHAR(100),
+        method VARCHAR(100),
+        user_id VARCHAR(255),
+        metadata JSONB,
+        created_at TIMESTAMP DEFAULT NOW()
+      )
+    `);
+
+    console.log('✅ Games tables initialized');
+  } catch (error) {
+    console.error('Error initializing games tables:', error);
+  }
+}
+
+// Initialize tables on startup
+initializeTables();
+
+/**
+ * POST /api/auth/games/save
+ * Save a new game and user's game reference
+ */
+router.post('/save', async (req, res) => {
+  try {
+    const { walletAddress, gameId, sharedGameData, userGameRef } = req.body;
+
+    if (!walletAddress || !gameId || !userGameRef) {
+      return res.status(400).json({
+        success: false,
+        error: 'Wallet address, game ID, and user game reference are required'
+      });
+    }
+
+    // Verify transaction on-chain for Connect4 games before saving
+    // This prevents ghost records from failed transactions (e.g., insufficient funds)
+    if (gameId.startsWith('c4-') && userGameRef.mySignature) {
+      console.log(`[saveGame] 🔍 Verifying Connect4 transaction: ${userGameRef.mySignature.slice(0, 20)}...`);
+      const verification = await connect4GameService.verifyTransactionSuccess(userGameRef.mySignature);
+
+      if (!verification.success) {
+        console.log(`[saveGame] ❌ Transaction verification failed for ${gameId}: ${verification.error}`);
+        return res.status(400).json({
+          success: false,
+          error: verification.error || 'Transaction failed on-chain',
+          code: 'TRANSACTION_FAILED',
+          details: {
+            signature: userGameRef.mySignature,
+            gameId,
+          }
+        });
+      }
+      console.log(`[saveGame] ✅ Transaction verified for ${gameId}`);
+    }
+
+    // 1. Save shared game data (if provided - only creator sends this)
+    if (sharedGameData) {
+      const {
+        title: originalTitle,
+        imageUrl,
+        matchupImageUrl,
+        gameType,
+        gameAddress,
+        buyIn,
+        maxPlayers,
+        gameMode,
+        createdBy,
+        sportsEvent,
+        homeTeamPlayers,
+        awayTeamPlayers,
+        drawTeamPlayers,
+        lockTimestamp,
+        invitedPlayer,
+      } = sharedGameData;
+
+      // For sports games, reconstruct title based on league convention
+      // US Sports (NHL, NBA, NFL, MLB): "Away @ Home" format
+      // Soccer (EPL): "Home vs Away" format with short nicknames
+      let title = originalTitle;
+      if (gameMode === 4 && sportsEvent?.strHomeTeam && sportsEvent?.strAwayTeam) {
+        const league = sportsEvent.strLeague?.toUpperCase() || '';
+        const isEPL = league.includes('PREMIER') || league === 'EPL';
+
+        if (isEPL) {
+          // EPL: "Home vs Away" with short nicknames
+          const homeNick = getTeamNickname(sportsEvent.strHomeTeam);
+          const awayNick = getTeamNickname(sportsEvent.strAwayTeam);
+          title = `${homeNick} vs ${awayNick}`;
+        } else {
+          // US Sports: "Away @ Home" format
+          title = `${sportsEvent.strAwayTeam} @ ${sportsEvent.strHomeTeam}`;
+        }
+        console.log(`[saveGame] Reconstructed title: "${originalTitle}" -> "${title}" (EPL: ${isEPL})`);
+      }
+
+      // Calculate lock_timestamp from sportsEvent.strTimestamp if not provided
+      let finalLockTimestamp = lockTimestamp;
+      if (!finalLockTimestamp && gameMode === 4 && sportsEvent?.strTimestamp) {
+        // Convert ISO timestamp to Unix timestamp (seconds since epoch)
+        const lockDate = new Date(sportsEvent.strTimestamp + 'Z');
+        finalLockTimestamp = Math.floor(lockDate.getTime() / 1000);
+        console.log(`[saveGame] Calculated lock_timestamp from strTimestamp: ${sportsEvent.strTimestamp} -> ${finalLockTimestamp}`);
+      }
+
+      // Calculate initial pool amounts based on creator's team choice
+      const creatorTeamChoice = userGameRef?.teamChoice;
+      const initialHomePool = creatorTeamChoice === 'home' ? buyIn : 0;
+      const initialAwayPool = creatorTeamChoice === 'away' ? buyIn : 0;
+      const initialDrawPool = creatorTeamChoice === 'draw' ? buyIn : 0;
+      const initialTotalPool = buyIn || 0;
+      const initialPlayerAmounts = createdBy ? { [createdBy]: buyIn } : {};
+
+      await pool.query(`
+        INSERT INTO games (
+          game_id, game_address, title, image_url, game_type, buy_in,
+          max_players, game_mode, created_by, sports_event,
+          home_team_players, away_team_players, draw_team_players, lock_timestamp,
+          is_locked, is_resolved, automatic_status, matchup_image_url, connect4_current_turn, invited_player,
+          home_pool, away_pool, draw_pool, total_pool, player_amounts
+        ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, false, false, 'pending', $15, $16, $17, $18, $19, $20, $21, $22)
+        ON CONFLICT (game_id)
+        DO UPDATE SET
+          title = EXCLUDED.title,
+          game_type = COALESCE(EXCLUDED.game_type, games.game_type),
+          home_team_players = EXCLUDED.home_team_players,
+          away_team_players = EXCLUDED.away_team_players,
+          draw_team_players = EXCLUDED.draw_team_players,
+          lock_timestamp = COALESCE(EXCLUDED.lock_timestamp, games.lock_timestamp),
+          matchup_image_url = COALESCE(EXCLUDED.matchup_image_url, games.matchup_image_url),
+          connect4_current_turn = COALESCE(EXCLUDED.connect4_current_turn, games.connect4_current_turn),
+          invited_player = COALESCE(EXCLUDED.invited_player, games.invited_player),
+          home_pool = COALESCE(EXCLUDED.home_pool, games.home_pool),
+          away_pool = COALESCE(EXCLUDED.away_pool, games.away_pool),
+          draw_pool = COALESCE(EXCLUDED.draw_pool, games.draw_pool),
+          total_pool = COALESCE(EXCLUDED.total_pool, games.total_pool),
+          player_amounts = COALESCE(EXCLUDED.player_amounts, games.player_amounts),
+          updated_at = NOW()
+      `, [
+        gameId,
+        gameAddress,
+        title,
+        imageUrl,
+        gameType,
+        buyIn,
+        maxPlayers || 0,
+        gameMode,
+        createdBy,
+        JSON.stringify(sportsEvent),
+        homeTeamPlayers || [],
+        awayTeamPlayers || [],
+        drawTeamPlayers || [],
+        finalLockTimestamp,
+        matchupImageUrl || null,
+        gameType === 'connect4' ? 'home' : null,
+        invitedPlayer || null,
+        initialHomePool,
+        initialAwayPool,
+        initialDrawPool,
+        initialTotalPool,
+        JSON.stringify(initialPlayerAmounts),
+      ]);
+
+      console.log(`[saveGame] Saved shared game data for ${gameId} (lock_timestamp: ${finalLockTimestamp})`);
+    }
+
+    // 2. Save user-specific reference
+    const {
+      role,
+      joinedAt,
+      teamChoice,
+      mySignature,
+      myExplorerUrl,
+      status,
+      walletType,
+    } = userGameRef;
+
+    await pool.query(`
+      INSERT INTO user_game_refs (
+        wallet_address, game_id, role, joined_at, team_choice,
+        my_signature, my_explorer_url, status, wallet_type
+      ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+      ON CONFLICT (wallet_address, game_id)
+      DO UPDATE SET
+        team_choice = EXCLUDED.team_choice,
+        my_signature = COALESCE(EXCLUDED.my_signature, user_game_refs.my_signature),
+        my_explorer_url = COALESCE(EXCLUDED.my_explorer_url, user_game_refs.my_explorer_url),
+        status = EXCLUDED.status
+    `, [
+      walletAddress,
+      gameId,
+      role,
+      joinedAt || new Date().toISOString(),
+      teamChoice,
+      mySignature,
+      myExplorerUrl,
+      status,
+      walletType,
+    ]);
+
+    console.log(`[saveGame] Saved game reference ${gameId} for user ${walletAddress} (role: ${role})`);
+
+    // 2.5. Connect 4 join - start the game and notify creator when opponent joins
+    if (gameId.startsWith('c4-') && role === 'player' && teamChoice === 'away') {
+      try {
+        console.log(`[saveGame] 🔴 Connect 4 join detected - adding player to away_team and starting game...`);
+
+        // CRITICAL: Add the joiner to away_team_players first
+        await pool.query(`
+          UPDATE games
+          SET away_team_players = array_append(away_team_players, $1),
+              updated_at = NOW()
+          WHERE game_id = $2
+        `, [walletAddress, gameId]);
+        console.log(`[saveGame] 🟡 Added ${walletAddress} to away_team_players`);
+
+        // Start the Connect 4 game (sets status to 'playing', preserves board)
+        const startedGame = await connect4GameService.startGame(gameId);
+        console.log(`[saveGame] 🔴🟡 Connect 4 game ${gameId} started! Status: ${startedGame?.status}`);
+
+        // Look up the game to get creator info
+        const gameResult = await pool.query(
+          `SELECT g.game_id, g.created_by, g.buy_in, u.id as creator_user_id, u.username as creator_username
+           FROM games g
+           LEFT JOIN users u ON g.created_by = u.wallet_address
+           WHERE g.game_id = $1`,
+          [gameId]
+        );
+
+        if (gameResult.rows.length > 0) {
+          const game = gameResult.rows[0];
+          const creatorWallet = game.created_by;
+          const creatorUserId = game.creator_user_id;
+          const creatorUsername = game.creator_username;
+
+          // Look up joiner info
+          const joinerResult = await pool.query(
+            `SELECT id, username, avatar FROM users WHERE wallet_address = $1`,
+            [walletAddress]
+          );
+          const joiner = joinerResult.rows[0] || {};
+          const joinerUserId = joiner.id;
+          const joinerUsername = joiner.username || `${walletAddress.slice(0, 4)}...${walletAddress.slice(-4)}`;
+          const joinerAvatar = joiner.avatar || `https://api.dicebear.com/9.x/adventurer/svg?seed=${walletAddress}`;
+
+          // Emit WebSocket event to creator so their UI updates
+          if (chatNamespace && creatorUserId) {
+            const playerJoinedEvent = {
+              type: 'connect4_player_joined',
+              gameId,
+              player: {
+                walletAddress,
+                username: joinerUsername,
+                avatar: joinerAvatar,
+                teamChoice: 'away',
+                color: 'yellow',
+              },
+            };
+            chatNamespace.to(`user-${creatorUserId}`).emit('connect4_update', playerJoinedEvent);
+            console.log(`[saveGame] 🔴 Emitted connect4_player_joined to user-${creatorUserId} (${creatorUsername})`);
+
+            // Also emit the full game state so the creator's overlay updates
+            if (startedGame) {
+              chatNamespace.to(`user-${creatorUserId}`).emit('connect4_game_state', startedGame);
+              console.log(`[saveGame] 🔴 Emitted connect4_game_state to creator`);
+            }
+          }
+
+          // Also emit to the joiner's room so they get the updated game state
+          if (chatNamespace && joinerUserId && startedGame) {
+            chatNamespace.to(`user-${joinerUserId}`).emit('connect4_game_state', startedGame);
+            console.log(`[saveGame] 🟡 Emitted connect4_game_state to joiner user-${joinerUserId}`);
+          }
+
+          // Broadcast to the connect4 game room as well
+          if (chatNamespace && startedGame) {
+            chatNamespace.to(`connect4:${gameId}`).emit('connect4_game_state', startedGame);
+            console.log(`[saveGame] 🔴🟡 Emitted connect4_game_state to room connect4:${gameId}`);
+          }
+
+          // Send Telegram notification to creator
+          if (creatorUserId) {
+            const { forwardChatNotification } = require('../services/telegramNotifications');
+            const message = `${joinerUsername} joined your Connect 4 game! 🔴🟡\n\nBuy-in: ${game.buy_in} SOL\nThey're playing as Yellow.\n\nIt's your turn (Red)!`;
+            await forwardChatNotification(pool, creatorUserId, 'game_joined', joinerUsername, message, { gameId });
+            console.log(`[saveGame] 📱 Telegram notification sent to creator ${creatorUsername}`);
+          }
+        }
+      } catch (notifError) {
+        console.warn(`[saveGame] ⚠️ Connect 4 join notification failed:`, notifError.message);
+      }
+    }
+
+    // 3. Generate matchup image (BLOCKING for sports games so we can return the URL)
+    // Only for sports games (gameMode 4) with valid sportsEvent data
+    // For Connect4 and other games, use the matchupImageUrl from sharedGameData if provided
+    let matchupImageUrl = sharedGameData?.matchupImageUrl || null;
+    if (sharedGameData && sharedGameData.gameMode === 4 && sharedGameData.sportsEvent) {
+      try {
+        matchupImageUrl = await generateAndUploadMatchupImage(gameId, sharedGameData.sportsEvent);
+        console.log(`[saveGame] Matchup image generated for ${gameId}: ${matchupImageUrl}`);
+      } catch (err) {
+        console.warn(`[saveGame] Matchup image generation failed for ${gameId}:`, err.message);
+      }
+    }
+
+    // 4. Post to Discord (non-blocking) - only for new games (when sharedGameData is provided)
+    if (sharedGameData) {
+      // Look up creator's username
+      pool.query('SELECT username FROM users WHERE wallet_address = $1', [sharedGameData.createdBy])
+        .then(result => {
+          const creatorUsername = result.rows[0]?.username || null;
+          return discordNotifications.notifyNewGame({
+            gameId,
+            title: sharedGameData.title,
+            buyIn: sharedGameData.buyIn,
+            sportsEvent: sharedGameData.sportsEvent,
+            creatorUsername,
+            matchupImageUrl,
+            gameType: sharedGameData.gameType
+          });
+        })
+        .catch(err => console.warn(`[saveGame] Discord notification failed for ${gameId}:`, err.message));
+    }
+
+    // Cache game to Redis (non-blocking)
+    // When sharedGameData is null (joiner, not creator), fetch from DB to avoid caching empty fields
+    (async () => {
+      try {
+        let cacheSource = sharedGameData;
+        if (!cacheSource) {
+          const gameRow = await pool.query('SELECT * FROM games WHERE game_id = $1', [gameId]);
+          if (gameRow.rows[0]) {
+            const g = gameRow.rows[0];
+            cacheSource = {
+              gameAddress: g.game_address,
+              title: g.title,
+              imageUrl: g.image_url,
+              matchupImageUrl: g.matchup_image_url,
+              gameType: g.game_type,
+              buyIn: parseFloat(g.buy_in) || 0,
+              maxPlayers: g.max_players,
+              gameMode: g.game_mode,
+              createdBy: g.created_by,
+              sportsEvent: g.sports_event,
+              homeTeamPlayers: g.home_team_players || [],
+              awayTeamPlayers: g.away_team_players || [],
+              drawTeamPlayers: g.draw_team_players || [],
+              lockTimestamp: g.lock_timestamp,
+            };
+          }
+        }
+        await gamesCacheService.cacheGame(walletAddress, {
+          gameId,
+          gameAddress: cacheSource?.gameAddress || null,
+          title: cacheSource?.title || '',
+          imageUrl: cacheSource?.imageUrl || null,
+          matchupImageUrl: matchupImageUrl || cacheSource?.matchupImageUrl || null,
+          gameType: cacheSource?.gameType || '',
+          buyIn: cacheSource?.buyIn || 0,
+          maxPlayers: cacheSource?.maxPlayers || 0,
+          gameMode: cacheSource?.gameMode || 0,
+          createdBy: cacheSource?.createdBy || walletAddress,
+          sportsEvent: cacheSource?.sportsEvent || null,
+          homeTeamPlayers: cacheSource?.homeTeamPlayers || [],
+          awayTeamPlayers: cacheSource?.awayTeamPlayers || [],
+          drawTeamPlayers: cacheSource?.drawTeamPlayers || [],
+          lockTimestamp: cacheSource?.lockTimestamp || null,
+          isLocked: false,
+          isResolved: false,
+          automaticStatus: 'pending',
+          status: status || 'active',
+          role: role || 'creator',
+          joinedAt: joinedAt || new Date().toISOString(),
+          teamChoice: teamChoice || null,
+          mySignature: mySignature || null,
+          myExplorerUrl: myExplorerUrl || null,
+          walletType: walletType || null,
+        });
+      } catch (err) {
+        console.warn('[saveGame] Redis cache write failed:', err.message);
+      }
+    })();
+
+    res.status(200).json({
+      success: true,
+      message: 'Game saved successfully',
+      matchupImageUrl: matchupImageUrl
+    });
+
+  } catch (error) {
+    console.error('[saveGame] Error:', error);
+    res.status(500).json({
+      success: false,
+      error: error.message || 'Failed to save game'
+    });
+  }
+});
+
+/**
+ * POST /api/auth/games/:gameId/join
+ * Join an existing game
+ */
+router.post('/:gameId/join', async (req, res) => {
+  try {
+    const { gameId } = req.params;
+    const { walletAddress, userGameRef, teamChoice, amount } = req.body;
+
+    if (!walletAddress || !userGameRef) {
+      return res.status(400).json({
+        success: false,
+        error: 'Wallet address and user game reference are required'
+      });
+    }
+
+    // Parse amount (in SOL) - default to 0 if not provided (legacy support)
+    const betAmount = amount ? parseFloat(amount) : 0;
+
+    // 1. Update game with new player and pool amounts
+    if (teamChoice) {
+      // For automatic/sports games, add to appropriate team
+      const teamField = teamChoice === 'home' ? 'home_team_players'
+        : teamChoice === 'away' ? 'away_team_players'
+        : 'draw_team_players';
+
+      // Determine which pool to update
+      const poolField = teamChoice === 'home' ? 'home_pool'
+        : teamChoice === 'away' ? 'away_pool'
+        : 'draw_pool';
+
+      await pool.query(`
+        UPDATE games
+        SET ${teamField} = array_append(${teamField}, $1),
+            ${poolField} = COALESCE(${poolField}, 0) + $3,
+            total_pool = COALESCE(total_pool, 0) + $3,
+            player_amounts = COALESCE(player_amounts, '{}'::jsonb) || jsonb_build_object($1, $3),
+            updated_at = NOW()
+        WHERE game_id = $2
+      `, [walletAddress, gameId, betAmount]);
+
+      console.log(`[joinGame] Added ${walletAddress} to ${teamChoice} team in game ${gameId} with ${betAmount} SOL`);
+    }
+
+    // 2. Save user's game reference
+    const {
+      role,
+      joinedAt,
+      mySignature,
+      myExplorerUrl,
+      status,
+      walletType,
+    } = userGameRef;
+
+    await pool.query(`
+      INSERT INTO user_game_refs (
+        wallet_address, game_id, role, joined_at, team_choice,
+        my_signature, my_explorer_url, status, wallet_type
+      ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+      ON CONFLICT (wallet_address, game_id)
+      DO UPDATE SET
+        team_choice = EXCLUDED.team_choice,
+        my_signature = COALESCE(EXCLUDED.my_signature, user_game_refs.my_signature),
+        my_explorer_url = COALESCE(EXCLUDED.my_explorer_url, user_game_refs.my_explorer_url),
+        status = EXCLUDED.status
+    `, [
+      walletAddress,
+      gameId,
+      role || 'player',
+      joinedAt || new Date().toISOString(),
+      teamChoice,
+      mySignature,
+      myExplorerUrl,
+      status || 'active',
+      walletType,
+    ]);
+
+    console.log(`[joinGame] Saved game reference ${gameId} for user ${walletAddress}`);
+
+    // Get updated game data to broadcast
+    const gameResult = await pool.query('SELECT * FROM games WHERE game_id = $1', [gameId]);
+    const updatedGame = gameResult.rows[0];
+
+    // Broadcast player joined event to all connected clients
+    if (chatNamespace && updatedGame) {
+      chatNamespace.emit('game:player_joined', {
+        gameId: gameId,
+        walletAddress: walletAddress,
+        teamChoice: teamChoice,
+        homeTeamCount: updatedGame.home_team_players?.length || 0,
+        awayTeamCount: updatedGame.away_team_players?.length || 0,
+        drawTeamCount: updatedGame.draw_team_players?.length || 0,
+        totalPlayers: (updatedGame.home_team_players?.length || 0) + (updatedGame.away_team_players?.length || 0) + (updatedGame.draw_team_players?.length || 0),
+        timestamp: Date.now()
+      });
+      console.log(`[joinGame] 📡 Broadcasted game:player_joined event`);
+    }
+
+    // Cache: add the joining player's game entry + update existing players' team arrays
+    if (updatedGame) {
+      const allPlayers = [
+        ...(updatedGame.home_team_players || []),
+        ...(updatedGame.away_team_players || []),
+        ...(updatedGame.draw_team_players || []),
+      ];
+      const sportsEvent = updatedGame.sports_event;
+      gamesCacheService.addPlayerToGame(gameId, walletAddress, {
+        gameId,
+        gameAddress: updatedGame.game_address,
+        title: updatedGame.title,
+        imageUrl: updatedGame.image_url,
+        matchupImageUrl: updatedGame.matchup_image_url,
+        gameType: updatedGame.game_type,
+        buyIn: parseFloat(updatedGame.buy_in) || 0,
+        maxPlayers: updatedGame.max_players,
+        gameMode: updatedGame.game_mode,
+        createdBy: updatedGame.created_by,
+        sportsEvent,
+        homeTeamPlayers: updatedGame.home_team_players || [],
+        awayTeamPlayers: updatedGame.away_team_players || [],
+        drawTeamPlayers: updatedGame.draw_team_players || [],
+        lockTimestamp: updatedGame.lock_timestamp,
+        isLocked: updatedGame.is_locked,
+        isResolved: updatedGame.is_resolved,
+        automaticStatus: updatedGame.automatic_status,
+        status: status || 'active',
+        role: role || 'player',
+        joinedAt: joinedAt || new Date().toISOString(),
+        teamChoice,
+        mySignature,
+        myExplorerUrl,
+        walletType,
+      }, allPlayers).catch(err => console.warn('[joinGame] Redis cache write failed:', err.message));
+    }
+
+    res.status(200).json({
+      success: true,
+      message: 'Successfully joined game'
+    });
+
+  } catch (error) {
+    console.error('[joinGame] Error:', error);
+    res.status(500).json({
+      success: false,
+      error: error.message || 'Failed to join game'
+    });
+  }
+});
+
+/**
+ * GET /api/games/health
+ * Check server health (database connectivity, oracle status)
+ * NOTE: Must be BEFORE /:gameId route
+ */
+router.get('/health', async (req, res) => {
+  try {
+    const startTime = Date.now();
+    
+    // Test database connectivity
+    await pool.query('SELECT 1');
+    
+    const responseTime = Date.now() - startTime;
+    
+    // Check oracle health - look for recent resolutions
+    const oracleCheck = await pool.query(`
+      SELECT 
+        COUNT(*) as resolved_count,
+        MAX(updated_at) as last_resolution
+      FROM games 
+      WHERE is_resolved = true 
+        AND game_mode IN (4, 5)
+        AND updated_at > NOW() - INTERVAL '24 hours'
+    `);
+    
+    const resolvedLast24h = parseInt(oracleCheck.rows[0].resolved_count);
+    const lastResolution = oracleCheck.rows[0].last_resolution;
+    
+    // Oracle is healthy if it resolved games in last 24h OR there are no pending games to resolve
+    const pendingGamesCheck = await pool.query(`
+      SELECT COUNT(*) as count FROM games 
+      WHERE game_mode IN (4, 5) 
+        AND is_resolved = false 
+        AND is_locked = true
+    `);
+    const pendingGames = parseInt(pendingGamesCheck.rows[0].count);
+    
+    // Oracle considered healthy if:
+    // - It resolved games recently (last 24h), OR
+    // - There are no pending games to resolve
+    const oracleHealthy = resolvedLast24h > 0 || pendingGames === 0;
+    
+    res.status(200).json({
+      success: true,
+      health: {
+        status: 'healthy',
+        database: 'connected',
+        responseTime: `${responseTime}ms`,
+        oracle: {
+          status: oracleHealthy ? 'healthy' : 'delayed',
+          resolvedLast24h: resolvedLast24h,
+          lastResolution: lastResolution,
+          pendingGames: pendingGames
+        },
+        timestamp: new Date().toISOString()
+      }
+    });
+
+  } catch (error) {
+    console.error('[health] Error:', error);
+    res.status(503).json({
+      success: false,
+      health: {
+        status: 'unhealthy',
+        database: 'disconnected',
+        oracle: {
+          status: 'unknown'
+        },
+        error: error.message,
+        timestamp: new Date().toISOString()
+      }
+    });
+  }
+});
+
+/**
+ * GET /api/games/stats
+ * Get platform statistics (total games, total players, etc.)
+ * NOTE: Must be BEFORE /:gameId route to avoid "stats" being treated as a game ID
+ */
+router.get('/stats', async (req, res) => {
+  try {
+    // Count total games created
+    const totalGamesResult = await pool.query('SELECT COUNT(*) as count FROM games');
+    const totalGames = parseInt(totalGamesResult.rows[0].count);
+
+    // Count total unique players (from user_game_refs)
+    const totalPlayersResult = await pool.query('SELECT COUNT(DISTINCT wallet_address) as count FROM user_game_refs');
+    const totalPlayers = parseInt(totalPlayersResult.rows[0].count);
+
+    // Count resolved games
+    const resolvedGamesResult = await pool.query('SELECT COUNT(*) as count FROM games WHERE is_resolved = true');
+    const resolvedGames = parseInt(resolvedGamesResult.rows[0].count);
+
+    console.log('[getStats] Total games:', totalGames, 'Total players:', totalPlayers, 'Resolved:', resolvedGames);
+
+    res.status(200).json({
+      success: true,
+      stats: {
+        totalGames,
+        totalPlayers,
+        resolvedGames,
+        activeGames: totalGames - resolvedGames
+      }
+    });
+
+  } catch (error) {
+    console.error('[getStats] Error:', error);
+    res.status(500).json({
+      success: false,
+      error: error.message
+    });
+  }
+});
+
+/**
+ * GET /api/games/sports-event/:sportsEventId/existing
+ * Get existing bets for a specific sports event
+ * 
+ * Returns:
+ * - Your own existing bet on this event (if any)
+ * - Friend bets on this event that you can join
+ * 
+ * This helps users avoid creating duplicate bets and discover friend bets to join.
+ * 
+ * Requires authentication (JWT token)
+ * 
+ * NOTE: This route MUST be defined before /:gameId to avoid being caught by it
+ */
+router.get('/sports-event/:sportsEventId/existing', async (req, res) => {
+  const { sportsEventId } = req.params;
+  
+  // Get wallet address from Authorization header (JWT token)
+  const authHeader = req.headers.authorization;
+  if (!authHeader || !authHeader.startsWith('Bearer ')) {
+    return res.status(401).json({
+      success: false,
+      error: 'Authentication required'
+    });
+  }
+
+  try {
+    // Decode JWT to get user info
+    const token = authHeader.split(' ')[1];
+    const jwt = require('jsonwebtoken');
+    const decoded = jwt.verify(token, process.env.JWT_SECRET);
+    const userId = decoded.userId;
+    const walletAddress = decoded.walletAddress;
+
+    if (!userId || !walletAddress) {
+      return res.status(401).json({
+        success: false,
+        error: 'Invalid token'
+      });
+    }
+
+    console.log(`[existingBets] Looking for existing bets on event ${sportsEventId} for user ${userId} (${walletAddress})`);
+    
+    // Debug: Check friend counts and friend bets
+    const friendCountQuery = await pool.query(`
+      SELECT 
+        (SELECT COUNT(*) FROM user_relationships WHERE (user_id = $1 OR target_user_id = $1) AND relationship_type = 'friend') as user_rel_count,
+        (SELECT COUNT(*) FROM friends WHERE (user_wallet = $2 OR friend_wallet = $2) AND status = 'accepted') as friends_count
+    `, [userId, walletAddress]);
+    console.log(`[existingBets] Friend counts - user_relationships: ${friendCountQuery.rows[0].user_rel_count}, friends table: ${friendCountQuery.rows[0].friends_count}`);
+    
+    // Debug: Check all games for this sports event (regardless of creator)
+    // Match by idEvent (sports) OR pandascoreMatchId (esports)
+    const allGamesForEvent = await pool.query(`
+      SELECT
+        g.game_id,
+        g.created_by,
+        g.is_locked,
+        g.is_resolved,
+        g.home_team_players,
+        g.away_team_players,
+        g.draw_team_players,
+        creator.username as creator_username,
+        creator.id as creator_id
+      FROM games g
+      JOIN users creator ON g.created_by = creator.wallet_address
+      WHERE (g.sports_event->>'idEvent' = $1 OR g.sports_event->>'pandascoreMatchId' = $1)
+    `, [sportsEventId]);
+    console.log(`[existingBets] All games for this event: ${allGamesForEvent.rows.length}`);
+    allGamesForEvent.rows.forEach(g => {
+      const isInHome = g.home_team_players?.includes(walletAddress);
+      const isInAway = g.away_team_players?.includes(walletAddress);
+      const isInDraw = g.draw_team_players?.includes(walletAddress);
+      console.log(`  - Game ${g.game_id} by @${g.creator_username} (id:${g.creator_id}), locked:${g.is_locked}, resolved:${g.is_resolved}, userInHome:${isInHome}, userInAway:${isInAway}, userInDraw:${isInDraw}`);
+    });
+    
+    // Debug: Check if creator is friend of current user
+    if (allGamesForEvent.rows.length > 0) {
+      for (const game of allGamesForEvent.rows) {
+        const friendCheck = await pool.query(`
+          SELECT 
+            EXISTS(SELECT 1 FROM user_relationships WHERE user_id = $1 AND target_user_id = $2 AND relationship_type = 'friend') as is_friend_dir1,
+            EXISTS(SELECT 1 FROM user_relationships WHERE user_id = $2 AND target_user_id = $1 AND relationship_type = 'friend') as is_friend_dir2
+        `, [userId, game.creator_id]);
+        console.log(`  - Is @${game.creator_username} (id:${game.creator_id}) friend of user ${userId}? dir1:${friendCheck.rows[0].is_friend_dir1}, dir2:${friendCheck.rows[0].is_friend_dir2}`);
+      }
+    }
+
+    // Query 1: Find ALL bets the user is participating in for this event
+    const myBetsResult = await pool.query(`
+      SELECT
+        g.game_id,
+        g.game_address,
+        g.title,
+        g.image_url,
+        g.matchup_image_url,
+        g.buy_in,
+        g.sports_event,
+        g.home_team_players,
+        g.away_team_players,
+        g.draw_team_players,
+        g.lock_timestamp,
+        g.is_locked,
+        g.is_resolved,
+        g.created_by,
+        ugr.team_choice as my_team_choice,
+        creator.username as creator_username,
+        creator.avatar as creator_avatar,
+        creator.wallet_address as creator_wallet
+      FROM games g
+      JOIN user_game_refs ugr ON g.game_id = ugr.game_id
+      JOIN users creator ON g.created_by = creator.wallet_address
+      WHERE
+        (g.sports_event->>'idEvent' = $1 OR g.sports_event->>'pandascoreMatchId' = $1)
+        AND ugr.wallet_address = $2
+        AND g.is_resolved = false
+      ORDER BY g.created_at DESC
+      LIMIT 10
+    `, [sportsEventId, walletAddress]);
+
+    // Process my bets - separate into "mine" (created) and "joined" (participating but not created)
+    const myBets = myBetsResult.rows.map(row => ({
+      gameId: row.game_id,
+      gameAddress: row.game_address,
+      title: row.title,
+      imageUrl: row.image_url,
+      matchupImageUrl: row.matchup_image_url,
+      buyIn: parseFloat(row.buy_in),
+      sportsEvent: row.sports_event,
+      homeTeam: row.sports_event?.strHomeTeam,
+      awayTeam: row.sports_event?.strAwayTeam,
+      homeTeamBadge: row.sports_event?.strHomeTeamBadge,
+      awayTeamBadge: row.sports_event?.strAwayTeamBadge,
+      league: row.sports_event?.strLeague,
+      strTimestamp: row.sports_event?.strTimestamp,
+      homeTeamPlayers: row.home_team_players || [],
+      awayTeamPlayers: row.away_team_players || [],
+      drawTeamPlayers: row.draw_team_players || [],
+      totalPlayers: (row.home_team_players?.length || 0) + (row.away_team_players?.length || 0) + (row.draw_team_players?.length || 0),
+      lockTimestamp: row.lock_timestamp,
+      isLocked: row.is_locked,
+      isResolved: row.is_resolved,
+      isCreator: row.created_by === walletAddress,
+      myTeamChoice: row.my_team_choice,
+      creator: {
+        walletAddress: row.creator_wallet,
+        username: row.creator_username,
+        avatar: row.creator_avatar,
+      },
+    }));
+
+    // For backwards compatibility, return the first "own" bet as myBet
+    const myBet = myBets.find(b => b.isCreator) || myBets[0] || null;
+    console.log(`[existingBets] User has ${myBets.length} bet(s) on this event`);
+
+    // Query 2: Find FRIEND bets on this event (including ones user already joined)
+    // Check friendships in BOTH tables and BOTH directions:
+    // - user_relationships table (uses user IDs)
+    // - friends table (uses wallet addresses)
+    //
+    // UPDATED: Now checks if ANY PARTICIPANT is a friend, not just the creator
+    const friendBetsResult = await pool.query(`
+      SELECT
+        g.game_id,
+        g.game_address,
+        g.title,
+        g.image_url,
+        g.matchup_image_url,
+        g.buy_in,
+        g.sports_event,
+        g.home_team_players,
+        g.away_team_players,
+        g.draw_team_players,
+        g.lock_timestamp,
+        g.is_locked,
+        g.is_resolved,
+        g.created_by,
+        creator.username as creator_username,
+        creator.avatar as creator_avatar,
+        creator.wallet_address as creator_wallet,
+        -- Check if current user has already joined this game
+        ($3 = ANY(g.home_team_players) OR $3 = ANY(g.away_team_players) OR $3 = ANY(g.draw_team_players)) as user_already_joined
+      FROM games g
+      JOIN users creator ON g.created_by = creator.wallet_address
+      WHERE
+        -- Match by sports event ID (idEvent for sports, pandascoreMatchId for esports)
+        (g.sports_event->>'idEvent' = $1 OR g.sports_event->>'pandascoreMatchId' = $1)
+        -- Only active games
+        AND g.is_resolved = false
+        AND g.is_locked = false
+        -- Game has a friend participating (creator OR any participant)
+        AND (
+          -- OPTION 1: Creator is a friend (original logic)
+          -- Check user_relationships table (user IDs) - both directions
+          creator.id IN (
+            SELECT target_user_id
+            FROM user_relationships
+            WHERE user_id = $2 AND relationship_type = 'friend'
+          )
+          OR
+          creator.id IN (
+            SELECT user_id
+            FROM user_relationships
+            WHERE target_user_id = $2 AND relationship_type = 'friend'
+          )
+          -- Check friends table (wallet addresses) - both directions
+          OR
+          creator.wallet_address IN (
+            SELECT friend_wallet
+            FROM friends
+            WHERE user_wallet = $3 AND status = 'accepted'
+          )
+          OR
+          creator.wallet_address IN (
+            SELECT user_wallet
+            FROM friends
+            WHERE friend_wallet = $3 AND status = 'accepted'
+          )
+
+          -- OPTION 2: Any participant is a friend (NEW LOGIC)
+          -- Check if any home team player is a friend (via friends table)
+          OR
+          EXISTS (
+            SELECT 1
+            FROM unnest(g.home_team_players) AS player_wallet
+            WHERE player_wallet IN (
+              SELECT friend_wallet
+              FROM friends
+              WHERE user_wallet = $3 AND status = 'accepted'
+            )
+            OR player_wallet IN (
+              SELECT user_wallet
+              FROM friends
+              WHERE friend_wallet = $3 AND status = 'accepted'
+            )
+          )
+          -- Check if any away team player is a friend (via friends table)
+          OR
+          EXISTS (
+            SELECT 1
+            FROM unnest(g.away_team_players) AS player_wallet
+            WHERE player_wallet IN (
+              SELECT friend_wallet
+              FROM friends
+              WHERE user_wallet = $3 AND status = 'accepted'
+            )
+            OR player_wallet IN (
+              SELECT user_wallet
+              FROM friends
+              WHERE friend_wallet = $3 AND status = 'accepted'
+            )
+          )
+          -- Check if any participant is a friend (via user_relationships table)
+          OR
+          EXISTS (
+            SELECT 1
+            FROM unnest(g.home_team_players || g.away_team_players || COALESCE(g.draw_team_players, '{}')) AS player_wallet
+            JOIN users player_user ON player_user.wallet_address = player_wallet
+            WHERE player_user.id IN (
+              SELECT target_user_id
+              FROM user_relationships
+              WHERE user_id = $2 AND relationship_type = 'friend'
+            )
+            OR player_user.id IN (
+              SELECT user_id
+              FROM user_relationships
+              WHERE target_user_id = $2 AND relationship_type = 'friend'
+            )
+          )
+        )
+      ORDER BY g.created_at DESC
+      LIMIT 10
+    `, [sportsEventId, userId, walletAddress]);
+
+    // Get game IDs already in myBets to avoid duplicates
+    const myBetGameIds = new Set(myBets.map(b => b.gameId));
+    
+    const friendBets = friendBetsResult.rows
+      // Filter out games already in myBets (to avoid showing same game twice)
+      .filter(row => !myBetGameIds.has(row.game_id))
+      .map(row => ({
+        gameId: row.game_id,
+        gameAddress: row.game_address,
+        title: row.title,
+        imageUrl: row.image_url,
+        matchupImageUrl: row.matchup_image_url,
+        buyIn: parseFloat(row.buy_in),
+        sportsEvent: row.sports_event,
+        homeTeam: row.sports_event?.strHomeTeam,
+        awayTeam: row.sports_event?.strAwayTeam,
+        homeTeamBadge: row.sports_event?.strHomeTeamBadge,
+        awayTeamBadge: row.sports_event?.strAwayTeamBadge,
+        league: row.sports_event?.strLeague,
+        strTimestamp: row.sports_event?.strTimestamp,
+        homeTeamPlayers: row.home_team_players || [],
+        awayTeamPlayers: row.away_team_players || [],
+        drawTeamPlayers: row.draw_team_players || [],
+        totalPlayers: (row.home_team_players?.length || 0) + (row.away_team_players?.length || 0) + (row.draw_team_players?.length || 0),
+        lockTimestamp: row.lock_timestamp,
+        isLocked: row.is_locked,
+        isResolved: row.is_resolved,
+        userAlreadyJoined: row.user_already_joined,
+        creator: {
+          walletAddress: row.creator_wallet,
+          username: row.creator_username,
+          avatar: row.creator_avatar,
+        },
+        creatorTeam: row.home_team_players?.includes(row.created_by) ? 'home' : row.away_team_players?.includes(row.created_by) ? 'away' : 'draw',
+      }));
+
+    console.log(`[existingBets] Found ${friendBets.length} friend bet(s) for event ${sportsEventId}`);
+
+    // Debug: Log friend bet creators
+    if (friendBets.length > 0) {
+      console.log(`[existingBets] Friend bets from: ${friendBets.map(b => b.creator.username).join(', ')}`);
+    }
+
+    // Query 3: Find PUBLIC bets (from non-friends) that user hasn't joined
+    // These are joinable bets from anyone
+    const friendBetGameIds = new Set(friendBets.map(b => b.gameId));
+    const excludedGameIds = [...myBetGameIds, ...friendBetGameIds];
+
+    const publicBetsResult = await pool.query(`
+      SELECT
+        g.game_id,
+        g.game_address,
+        g.title,
+        g.image_url,
+        g.matchup_image_url,
+        g.buy_in,
+        g.sports_event,
+        g.home_team_players,
+        g.away_team_players,
+        g.draw_team_players,
+        g.lock_timestamp,
+        g.is_locked,
+        g.is_resolved,
+        g.created_by,
+        creator.username as creator_username,
+        creator.avatar as creator_avatar,
+        creator.wallet_address as creator_wallet
+      FROM games g
+      JOIN users creator ON g.created_by = creator.wallet_address
+      WHERE
+        (g.sports_event->>'idEvent' = $1 OR g.sports_event->>'pandascoreMatchId' = $1)
+        AND g.is_resolved = false
+        AND g.is_locked = false
+        AND g.created_by != $2
+        ${excludedGameIds.length > 0 ? `AND g.game_id NOT IN (${excludedGameIds.map((_, i) => `$${i + 3}`).join(', ')})` : ''}
+      ORDER BY g.created_at DESC
+      LIMIT 10
+    `, [sportsEventId, walletAddress, ...excludedGameIds]);
+
+    const publicBets = publicBetsResult.rows.map(row => ({
+      gameId: row.game_id,
+      gameAddress: row.game_address,
+      title: row.title,
+      imageUrl: row.image_url,
+      matchupImageUrl: row.matchup_image_url,
+      buyIn: parseFloat(row.buy_in),
+      sportsEvent: row.sports_event,
+      homeTeam: row.sports_event?.strHomeTeam,
+      awayTeam: row.sports_event?.strAwayTeam,
+      homeTeamBadge: row.sports_event?.strHomeTeamBadge,
+      awayTeamBadge: row.sports_event?.strAwayTeamBadge,
+      league: row.sports_event?.strLeague,
+      strTimestamp: row.sports_event?.strTimestamp,
+      homeTeamPlayers: row.home_team_players || [],
+      awayTeamPlayers: row.away_team_players || [],
+      drawTeamPlayers: row.draw_team_players || [],
+      totalPlayers: (row.home_team_players?.length || 0) + (row.away_team_players?.length || 0) + (row.draw_team_players?.length || 0),
+      lockTimestamp: row.lock_timestamp,
+      isLocked: row.is_locked,
+      isResolved: row.is_resolved,
+      creator: {
+        walletAddress: row.creator_wallet,
+        username: row.creator_username,
+        avatar: row.creator_avatar,
+      },
+      creatorTeam: row.home_team_players?.includes(row.created_by) ? 'home' : row.away_team_players?.includes(row.created_by) ? 'away' : 'draw',
+    }));
+
+    console.log(`[existingBets] Found ${publicBets.length} public bet(s) for event ${sportsEventId}`);
+
+    res.json({
+      success: true,
+      myBet,
+      myBets, // All bets user is participating in
+      friendBets,
+      publicBets, // Joinable bets from non-friends
+      hasMyBet: !!myBet,
+      hasFriendBets: friendBets.length > 0,
+      hasPublicBets: publicBets.length > 0,
+      totalExistingBets: myBets.length + friendBets.length + publicBets.length,
+    });
+
+  } catch (error) {
+    console.error('[existingBets] Error:', error);
+    res.status(500).json({
+      success: false,
+      error: error.message
+    });
+  }
+});
+
+/**
+ * GET /api/games/:gameId
+ * Get game data by ID (public endpoint for sharing links)
+ */
+router.get('/:gameId', async (req, res) => {
+  try {
+    const { gameId } = req.params;
+    const { walletAddress } = req.query; // Optional: to get user-specific claim status
+
+    const result = await pool.query(`
+      SELECT * FROM games WHERE game_id = $1
+    `, [gameId]);
+
+    if (result.rows.length === 0) {
+      return res.status(404).json({
+        success: false,
+        error: 'Game not found'
+      });
+    }
+
+    const game = result.rows[0];
+
+    // Build participants array from team players with user data
+    const participants = [];
+    
+    // Get user data for all participants AND creator
+    const allWallets = [
+      ...(game.home_team_players || []),
+      ...(game.away_team_players || []),
+      game.created_by // Include creator wallet
+    ].filter(Boolean);
+    
+    let creatorUsername = null;
+    let creatorAvatar = null;
+    
+    if (allWallets.length > 0) {
+      const usersResult = await pool.query(
+        'SELECT id, wallet_address, username, avatar, telegram_user_id FROM users WHERE wallet_address = ANY($1)',
+        [allWallets]
+      );
+      
+      const userMap = {};
+      usersResult.rows.forEach(u => {
+        userMap[u.wallet_address] = u;
+      });
+      
+      // Get creator info
+      if (game.created_by && userMap[game.created_by]) {
+        creatorUsername = userMap[game.created_by].username;
+        creatorAvatar = userMap[game.created_by].avatar;
+      }
+      
+      // Build participants with team choice
+      (game.home_team_players || []).forEach(wallet => {
+        const user = userMap[wallet];
+        participants.push({
+          walletAddress: wallet,
+          teamChoice: 'home',
+          username: user?.username,
+          telegramUserId: user?.telegram_user_id
+        });
+      });
+      
+      (game.away_team_players || []).forEach(wallet => {
+        const user = userMap[wallet];
+        participants.push({
+          walletAddress: wallet,
+          teamChoice: 'away',
+          username: user?.username,
+          telegramUserId: user?.telegram_user_id
+        });
+      });
+    }
+
+    // Extract team info from sportsEvent for convenience
+    const sportsEvent = game.sports_event;
+
+    // If walletAddress provided, get user's claim status
+    let userClaimData = null;
+    if (walletAddress) {
+      const userRefResult = await pool.query(
+        'SELECT claimed_at, claim_signature, amount_claimed, team_choice FROM user_game_refs WHERE wallet_address = $1 AND game_id = $2',
+        [walletAddress, gameId]
+      );
+      if (userRefResult.rows.length > 0) {
+        const ref = userRefResult.rows[0];
+        userClaimData = {
+          claimedAt: ref.claimed_at,
+          claimSignature: ref.claim_signature,
+          amountClaimed: ref.amount_claimed ? parseFloat(ref.amount_claimed) : null,
+          teamChoice: ref.team_choice,
+        };
+      }
+    }
+
+    res.status(200).json({
+      gameId: game.game_id,
+      gameAddress: game.game_address,
+      title: game.title,
+      imageUrl: game.image_url,
+      matchupImageUrl: game.matchup_image_url, // Pre-generated matchup image
+      gameType: game.game_type,
+      buyIn: parseFloat(game.buy_in),
+      maxPlayers: game.max_players,
+      gameMode: game.game_mode,
+      createdBy: game.created_by,
+      creatorWallet: game.created_by, // created_by IS the creator wallet
+      creatorUsername: creatorUsername,
+      creatorAvatar: creatorAvatar,
+      sportsEvent: sportsEvent,
+      // Top-level team info for easy access (extracted from sportsEvent)
+      homeTeam: sportsEvent?.strHomeTeam,
+      awayTeam: sportsEvent?.strAwayTeam,
+      league: sportsEvent?.strLeague,
+      homeTeamBadge: sportsEvent?.strHomeTeamBadge,
+      awayTeamBadge: sportsEvent?.strAwayTeamBadge,
+      strTimestamp: sportsEvent?.strTimestamp,
+      homeTeamPlayers: game.home_team_players || [],
+      awayTeamPlayers: game.away_team_players || [],
+      drawTeamPlayers: game.draw_team_players || [],
+      participants: participants,
+      // Pool amounts for pari-mutuel display
+      // For hybrid games (legacy + pari-mutuel), calculate correct totals
+      ...calculatePoolAmounts(game),
+      playerAmounts: game.player_amounts || {},
+      lockTimestamp: game.lock_timestamp,
+      isLocked: game.is_locked,
+      isResolved: game.is_resolved,
+      automaticStatus: game.automatic_status,
+      createdAt: game.created_at,
+      // User-specific claim data (if walletAddress was provided)
+      claimedAt: userClaimData?.claimedAt || null,
+      claimSignature: userClaimData?.claimSignature || null,
+      amountClaimed: userClaimData?.amountClaimed || null,
+      userTeamChoice: userClaimData?.teamChoice || null,
+    });
+
+  } catch (error) {
+    console.error('[getGame] Error:', error);
+    res.status(500).json({
+      success: false,
+      error: error.message
+    });
+  }
+});
+
+/**
+ * POST /api/auth/games/:gameId/claim
+ * Mark a game as claimed by the user
+ */
+router.post('/:gameId/claim', async (req, res) => {
+  try {
+    const { gameId } = req.params;
+    const { walletAddress, claimedAt, claimSignature, claimExplorerUrl, amountClaimed } = req.body;
+
+    if (!walletAddress) {
+      return res.status(400).json({
+        success: false,
+        error: 'Wallet address is required'
+      });
+    }
+
+    console.log(`[claimGame] Marking game ${gameId} as claimed by ${walletAddress}`);
+
+    // Update user's game reference with claim information
+    const result = await pool.query(`
+      UPDATE user_game_refs
+      SET claimed_at = $1,
+          claim_signature = $2,
+          claim_explorer_url = $3,
+          amount_claimed = $4,
+          updated_at = NOW()
+      WHERE wallet_address = $5 AND game_id = $6
+      RETURNING *
+    `, [claimedAt, claimSignature, claimExplorerUrl, amountClaimed, walletAddress, gameId]);
+
+    if (result.rows.length === 0) {
+      console.log(`[claimGame] ⚠️ No user_game_ref found for ${walletAddress} in game ${gameId}`);
+      return res.status(404).json({
+        success: false,
+        error: 'User game reference not found - did you join this game?'
+      });
+    }
+
+    // Also mark the game as resolved in the games table
+    await pool.query(`
+      UPDATE games SET is_resolved = TRUE, updated_at = NOW() WHERE game_id = $1
+    `, [gameId]);
+
+    console.log(`[claimGame] Game ${gameId} marked as claimed for user ${walletAddress}`);
+
+    // Update Redis cache for this user's game
+    gamesCacheService.updateGame(walletAddress, gameId, {
+      claimedAt: claimedAt || new Date().toISOString(),
+      claimSignature: claimSignature || null,
+      claimExplorerUrl: claimExplorerUrl || null,
+      amountClaimed: amountClaimed || null,
+    }).catch(err => console.warn('[claimGame] Redis cache update failed:', err.message));
+
+    // Broadcast claim event to all connected clients
+    if (chatNamespace) {
+      chatNamespace.emit('game:claimed', {
+        gameId: gameId,
+        walletAddress: walletAddress,
+        amountClaimed: amountClaimed,
+        claimedAt: claimedAt || new Date().toISOString(),
+        timestamp: Date.now()
+      });
+      console.log(`[claimGame] 📡 Broadcasted game:claimed event`);
+    }
+
+    res.status(200).json({
+      success: true,
+      message: 'Game marked as claimed'
+    });
+
+  } catch (error) {
+    console.error('[claimGame] Error:', error);
+    res.status(500).json({
+      success: false,
+      error: error.message
+    });
+  }
+});
+
+/**
+ * POST /api/games/notify-join
+ * Send notification to ALL game participants when someone joins
+ */
+router.post('/notify-join', async (req, res) => {
+  try {
+    const { creatorWallet, joinerWallet, joinerUsername, teamChoice, gameInvite, betAmount } = req.body;
+
+    if (!joinerWallet || !gameInvite?.gameId) {
+      return res.status(400).json({
+        success: false,
+        error: 'Joiner wallet and gameId are required'
+      });
+    }
+
+    // Use the shared pool connection (already has SSL configured)
+    const notifPool = pool;
+
+    // Get joiner's user ID
+    const joinerResult = await notifPool.query(
+      'SELECT id FROM users WHERE wallet_address = $1',
+      [joinerWallet]
+    );
+    const joinerUserId = joinerResult.rows.length > 0 ? joinerResult.rows[0].id : null;
+
+    // Get all current participants from the game (BEFORE the joiner was added)
+    // We'll notify everyone except the joiner themselves
+    const gameResult = await notifPool.query(
+      'SELECT home_team_players, away_team_players, draw_team_players, created_by FROM games WHERE game_id = $1',
+      [gameInvite.gameId]
+    );
+
+    if (gameResult.rows.length === 0) {
+      console.log(`[notifyJoin] ⚠️ Game ${gameInvite.gameId} not found in database`);
+      return res.status(404).json({
+        success: false,
+        error: 'Game not found'
+      });
+    }
+
+    const game = gameResult.rows[0];
+
+    // Collect all participant wallet addresses (including creator)
+    const allParticipantWallets = new Set([
+      ...(game.home_team_players || []),
+      ...(game.away_team_players || []),
+      ...(game.draw_team_players || []),
+      game.created_by // Always include creator
+    ].filter(Boolean));
+
+    // Remove the joiner from the set (don't notify them about their own join)
+    allParticipantWallets.delete(joinerWallet);
+
+    console.log(`[notifyJoin] 📬 Notifying ${allParticipantWallets.size} participant(s) about ${joinerUsername} joining game ${gameInvite.gameId}`);
+
+    if (allParticipantWallets.size === 0) {
+      console.log('[notifyJoin] No other participants to notify');
+      return res.status(200).json({
+        success: true,
+        message: 'No participants to notify (first joiner or creator only)'
+      });
+    }
+
+    // Get user IDs for all participants
+    const participantsResult = await notifPool.query(
+      'SELECT id, wallet_address, username FROM users WHERE wallet_address = ANY($1)',
+      [Array.from(allParticipantWallets)]
+    );
+
+    const participantMap = {};
+    participantsResult.rows.forEach(u => {
+      participantMap[u.wallet_address] = { id: u.id, username: u.username };
+    });
+
+    // Track notification results
+    const notificationResults = {
+      sent: [],
+      failed: [],
+      skipped: []
+    };
+
+    // Send notifications to each participant
+    const { forwardChatNotification } = require('../services/telegramNotifications');
+    
+    for (const participantWallet of allParticipantWallets) {
+      const participant = participantMap[participantWallet];
+      
+      if (!participant) {
+        console.log(`[notifyJoin] ⏭️ Participant ${participantWallet.slice(0, 8)} not found in users table - skipping`);
+        notificationResults.skipped.push(participantWallet);
+        continue;
+      }
+
+      const participantUserId = participant.id;
+      const isCreator = participantWallet === game.created_by;
+
+      try {
+        // Enrich gameInvite with S3 URL from games table
+        const enrichedGameInvite = await enrichGameInviteWithS3Url(notifPool, gameInvite);
+
+        // Create notification in database
+        const insertResult = await notifPool.query(
+          `INSERT INTO chat_notifications (
+            user_id, sender_user_id, notification_type, notification_data, read, created_at
+          ) VALUES ($1, $2, 'game_joined', $3, false, NOW())
+          RETURNING id, created_at`,
+          [
+            participantUserId,
+            joinerUserId,
+            JSON.stringify({
+              joinerUsername,
+              teamChoice,
+              gameInvite: enrichedGameInvite, // Use enriched gameInvite with S3 URL
+              isCreator, // Flag to customize message on frontend if needed
+              amount: betAmount, // Actual bet amount for pari-mutuel
+            })
+          ]
+        );
+
+        const notificationId = insertResult.rows[0].id;
+        const notificationCreatedAt = insertResult.rows[0].created_at;
+
+        console.log(`📬 Sent game_joined notification to ${isCreator ? 'creator' : 'participant'} ${participantWallet.slice(0, 8)} (ID: ${notificationId})`);
+
+        // Send real-time notification via WebSocket
+        if (chatNamespace) {
+          const notification = {
+            id: notificationId,
+            type: 'game_joined',
+            senderUsername: joinerUsername,
+            senderWallet: joinerWallet,
+            message: teamChoice,
+            gameInvite: enrichedGameInvite,
+            createdAt: notificationCreatedAt.toISOString(),
+            read: false,
+            amount: betAmount, // Actual bet amount for pari-mutuel
+          };
+
+          chatNamespace.to(`user-${participantUserId}`).emit('notification', notification);
+          console.log(`🔔 Real-time notification sent to user-${participantUserId} (${participant.username || participantWallet.slice(0, 8)})`);
+        }
+
+        // Cache notification to Redis (non-blocking)
+        notificationCacheService.cacheNotification(participantUserId, {
+          id: notificationId,
+          type: 'game_joined',
+          read: false,
+          messageId: null,
+          message: teamChoice,
+          senderUsername: joinerUsername,
+          senderWallet: joinerWallet,
+          senderAvatar: null,
+          createdAt: notificationCreatedAt,
+          gameInvite: enrichedGameInvite,
+          amount: betAmount, // Actual bet amount for pari-mutuel
+        }).catch(err => console.error('[gamesRoutes] Failed to cache game_joined notification:', err.message));
+
+        // Forward to Telegram if participant has it connected (with CTA button)
+        try {
+          const teamName = teamChoice === 'home' 
+            ? (gameInvite.homeTeam?.split(' ').pop() || 'Home')
+            : (gameInvite.awayTeam?.split(' ').pop() || 'Away');
+          
+          // Customize message based on whether they're the creator or another participant
+          const message = isCreator
+            ? `${joinerUsername} joined your ${gameInvite.title} bet! They're backing ${teamName}`
+            : `${joinerUsername} joined the ${gameInvite.title} bet you're in! They're backing ${teamName}`;
+          
+          // Pass gameId in metadata for the CTA button
+          await forwardChatNotification(notifPool, participantUserId, 'game_joined', joinerUsername, message, { gameId: gameInvite.gameId });
+          console.log(`📱 Telegram notification sent to ${participant.username || participantWallet.slice(0, 8)} with CTA`);
+        } catch (telegramError) {
+          console.log(`⚠️ Telegram forward failed for ${participantWallet.slice(0, 8)}:`, telegramError.message);
+        }
+
+        notificationResults.sent.push(participantWallet);
+
+      } catch (notifError) {
+        console.error(`[notifyJoin] ❌ Failed to notify ${participantWallet.slice(0, 8)}:`, notifError.message);
+        notificationResults.failed.push(participantWallet);
+      }
+    }
+
+    console.log(`[notifyJoin] ✅ Complete: ${notificationResults.sent.length} sent, ${notificationResults.failed.length} failed, ${notificationResults.skipped.length} skipped`);
+
+    res.status(200).json({
+      success: true,
+      message: `Notifications sent to ${notificationResults.sent.length} participant(s)`,
+      results: notificationResults
+    });
+
+  } catch (error) {
+    console.error('[notifyJoin] Error:', error);
+    res.status(500).json({
+      success: false,
+      error: error.message
+    });
+  }
+});
+
+/**
+ * POST /api/games/invite
+ * Send game invitation to a friend
+ */
+router.post('/invite', async (req, res) => {
+  try {
+    const { inviterWallet, inviteeWallet, inviterUsername, gameInvite } = req.body;
+
+    if (!inviterWallet || !inviteeWallet || !gameInvite) {
+      return res.status(400).json({
+        success: false,
+        error: 'Inviter wallet, invitee wallet, and game invite data are required'
+      });
+    }
+
+    // Don't allow inviting yourself
+    if (inviterWallet === inviteeWallet) {
+      return res.status(400).json({
+        success: false,
+        error: 'Cannot invite yourself'
+      });
+    }
+
+    // Use the shared pool connection
+    const notifPool = pool;
+
+    // Get inviter's user ID and username
+    const inviterResult = await notifPool.query(
+      'SELECT id, username FROM users WHERE wallet_address = $1',
+      [inviterWallet]
+    );
+
+    if (inviterResult.rows.length === 0) {
+      return res.status(404).json({
+        success: false,
+        error: 'Inviter not found'
+      });
+    }
+
+    const inviterUserId = inviterResult.rows[0].id;
+    // Use database username, fall back to passed-in username, then wallet
+    const resolvedInviterUsername = inviterResult.rows[0].username || inviterUsername || inviterWallet.slice(0, 8);
+
+    // Get invitee's user ID
+    const inviteeResult = await notifPool.query(
+      'SELECT id FROM users WHERE wallet_address = $1',
+      [inviteeWallet]
+    );
+
+    if (inviteeResult.rows.length === 0) {
+      return res.status(404).json({
+        success: false,
+        error: 'Invitee not found - they may not have an account yet'
+      });
+    }
+
+    const inviteeUserId = inviteeResult.rows[0].id;
+
+    // Enrich gameInvite with S3 URL from games table
+    const enrichedGameInvite = await enrichGameInviteWithS3Url(notifPool, gameInvite);
+
+    // Create notification and get the inserted ID
+    const insertResult = await notifPool.query(
+      `INSERT INTO chat_notifications (
+        user_id, sender_user_id, notification_type, notification_data, read, created_at
+      ) VALUES ($1, $2, 'game_invite', $3, false, NOW())
+      RETURNING id, created_at`,
+      [
+        inviteeUserId,
+        inviterUserId,
+        JSON.stringify({
+          gameInvite: enrichedGameInvite, // Use enriched gameInvite with S3 URL
+        })
+      ]
+    );
+
+    const notificationId = insertResult.rows[0].id;
+    const notificationCreatedAt = insertResult.rows[0].created_at;
+
+    console.log(`📨 Sent game_invite notification from ${inviterWallet.slice(0, 8)} to ${inviteeWallet.slice(0, 8)} (ID: ${notificationId})`);
+
+    // Send real-time notification via WebSocket
+    if (chatNamespace) {
+      const notification = {
+        id: notificationId, // ✅ Use actual database ID for duplicate detection
+        type: 'game_invite',
+        senderUsername: resolvedInviterUsername,
+        senderWallet: inviterWallet,
+        message: '', // Empty for game invites
+        gameInvite: enrichedGameInvite, // Use enriched gameInvite with S3 URL
+        createdAt: notificationCreatedAt.toISOString(),
+        read: false,
+      };
+
+      console.log('[gameInvite] Emitting to user-' + inviteeUserId, notification);
+      // Emit to invitee's socket
+      chatNamespace.to(`user-${inviteeUserId}`).emit('notification', notification);
+      console.log(`🔔 Real-time game invite sent to user-${inviteeUserId}`);
+    } else {
+      console.warn('⚠️ chatNamespace not available - notification will only appear after refresh');
+    }
+
+    // Cache notification to Redis (non-blocking)
+    notificationCacheService.cacheNotification(inviteeUserId, {
+      id: notificationId,
+      type: 'game_invite',
+      read: false,
+      messageId: null,
+      message: '',
+      senderUsername: resolvedInviterUsername,
+      senderWallet: inviterWallet,
+      senderAvatar: null,
+      createdAt: notificationCreatedAt,
+      gameInvite: enrichedGameInvite,
+    }).catch(err => console.error('[gamesRoutes] Failed to cache game_invite notification:', err.message));
+
+    // Forward to Telegram if invitee has it connected (with CTA button)
+    try {
+      const { forwardChatNotification } = require('../services/telegramNotifications');
+      const message = `${resolvedInviterUsername} invited you to join their ${gameInvite.title} bet! ${gameInvite.buyIn} SOL buy-in`;
+      // Pass gameId in metadata for the CTA button
+      await forwardChatNotification(notifPool, inviteeUserId, 'game_invite', resolvedInviterUsername, message, { gameId: gameInvite.gameId });
+      console.log('📱 Game invite notification forwarded to Telegram with CTA button');
+    } catch (telegramError) {
+      console.log('⚠️ Telegram forward failed:', telegramError.message);
+    }
+
+    // For Connect4 games, update the invited_player field to make this a private game
+    // This ensures only the invited player sees the game in "Waiting for You" tab
+    if (gameInvite.gameType === 'connect4' && gameInvite.gameId) {
+      try {
+        const updateResult = await notifPool.query(
+          `UPDATE games
+           SET invited_player = $1, updated_at = NOW()
+           WHERE game_id = $2 AND invited_player IS NULL`,
+          [inviteeWallet, gameInvite.gameId]
+        );
+        if (updateResult.rowCount > 0) {
+          console.log(`🔴🟡 [Connect4] Set invited_player=${inviteeWallet.slice(0, 8)} for game ${gameInvite.gameId}`);
+        } else {
+          console.log(`🔴🟡 [Connect4] Game ${gameInvite.gameId} already has an invited_player set`);
+        }
+      } catch (updateErr) {
+        console.error(`[Connect4] Failed to update invited_player:`, updateErr.message);
+        // Don't fail the invite - notification was still sent
+      }
+    }
+
+    // For Connect4 games, emit a connect4_game_created event so invitee's Connect4 tab auto-refreshes
+    if (gameInvite.gameType === 'connect4' && chatNamespace) {
+      chatNamespace.to(`user-${inviteeUserId}`).emit('connect4_update', {
+        type: 'connect4_game_created',
+        gameId: gameInvite.gameId,
+        creatorUsername: resolvedInviterUsername,
+        buyIn: gameInvite.buyIn,
+      });
+      console.log(`🔴🟡 [Connect4] Emitted connect4_game_created to user-${inviteeUserId} for game ${gameInvite.gameId}`);
+    }
+
+    res.status(200).json({
+      success: true,
+      message: 'Invitation sent'
+    });
+
+  } catch (error) {
+    console.error('[gameInvite] Error:', error);
+    res.status(500).json({
+      success: false,
+      error: error.message
+    });
+  }
+});
+
+/**
+ * GET /api/games/:gameId/invites
+ * Get list of wallet addresses that have been invited to this game
+ */
+router.get('/:gameId/invites', async (req, res) => {
+  try {
+    const { gameId } = req.params;
+
+    if (!gameId) {
+      return res.status(400).json({
+        success: false,
+        error: 'Game ID is required'
+      });
+    }
+
+    // Query notifications table for game_invite notifications for this game
+    // The gameId is nested inside gameInvite object in notification_data
+    const result = await pool.query(`
+      SELECT DISTINCT u.wallet_address
+      FROM chat_notifications cn
+      JOIN users u ON cn.user_id = u.id
+      WHERE cn.notification_type = 'game_invite'
+      AND cn.notification_data->'gameInvite'->>'gameId' = $1
+    `, [gameId]);
+
+    const invitedWallets = result.rows.map(row => row.wallet_address);
+
+    console.log(`[gameInvites] Found ${invitedWallets.length} invited wallets for game ${gameId}`);
+
+    res.status(200).json({
+      success: true,
+      gameId,
+      invitedWallets
+    });
+
+  } catch (error) {
+    console.error('[gameInvites] Error:', error);
+    res.status(500).json({
+      success: false,
+      error: error.message
+    });
+  }
+});
+
+/**
+ * POST /api/audit/log
+ * Log audit events
+ */
+router.post('/audit', async (req, res) => {
+  try {
+    const { type, method, userId, metadata } = req.body;
+
+    await pool.query(`
+      INSERT INTO audit_logs (log_type, method, user_id, metadata)
+      VALUES ($1, $2, $3, $4)
+    `, [type, method, userId, JSON.stringify(metadata)]);
+
+    console.log(`[audit] Logged ${type} for user ${userId}`);
+
+    res.status(200).json({
+      success: true,
+      message: 'Event logged'
+    });
+
+  } catch (error) {
+    console.error('[audit] Error:', error);
+    res.status(500).json({
+      success: false,
+      error: error.message
+    });
+  }
+});
+
+/**
+ * GET /api/games
+ * Get all games (used by oracle for notification checking)
+ */
+router.get('/', async (req, res) => {
+  try {
+    // Get all automatic (gameMode = 4) games that are not resolved
+    const result = await pool.query(`
+      SELECT * FROM games
+      WHERE game_mode IN (4, 5)
+        AND is_resolved = false
+      ORDER BY created_at DESC
+    `);
+
+    const games = result.rows.map(row => {
+      const sportsEvent = row.sports_event;
+      return {
+        gameId: row.game_id,
+        gameAddress: row.game_address,
+        title: row.title,
+        imageUrl: row.image_url,
+        matchupImageUrl: row.matchup_image_url, // Pre-generated S3 matchup image
+        gameType: row.game_type,
+        buyIn: parseFloat(row.buy_in),
+        maxPlayers: row.max_players,
+        gameMode: row.game_mode,
+        createdBy: row.created_by,
+        sportsEvent: sportsEvent,
+        // Top-level team info for easy access
+        homeTeam: sportsEvent?.strHomeTeam,
+        awayTeam: sportsEvent?.strAwayTeam,
+        league: sportsEvent?.strLeague,
+        homeTeamBadge: sportsEvent?.strHomeTeamBadge,
+        awayTeamBadge: sportsEvent?.strAwayTeamBadge,
+        strTimestamp: sportsEvent?.strTimestamp,
+        homeTeamPlayers: row.home_team_players || [],
+        awayTeamPlayers: row.away_team_players || [],
+        drawTeamPlayers: row.draw_team_players || [],
+        participants: [
+          ...(row.home_team_players || []).map(wallet => ({ walletAddress: wallet, teamChoice: 'home' })),
+          ...(row.away_team_players || []).map(wallet => ({ walletAddress: wallet, teamChoice: 'away' })),
+          ...(row.draw_team_players || []).map(wallet => ({ walletAddress: wallet, teamChoice: 'draw' }))
+        ],
+        lockTimestamp: row.lock_timestamp,
+        lockTime: row.lock_timestamp ? { _seconds: row.lock_timestamp } : null,
+        isLocked: row.is_locked,
+        isResolved: row.is_resolved,
+        automaticStatus: row.automatic_status,
+        createdAt: row.created_at,
+        lockNotificationSent_10min: row.lock_notification_sent_10min || false,
+        lockNotificationSent_now: row.lock_notification_sent_now || false,
+      };
+    });
+
+    console.log(`[getAllGames] Found ${games.length} unresolved automatic game(s)`);
+
+    res.status(200).json({
+      success: true,
+      games: games
+    });
+
+  } catch (error) {
+    console.error('[getAllGames] Error:', error);
+    res.status(500).json({
+      success: false,
+      error: error.message
+    });
+  }
+});
+
+/**
+ * GET /api/games/automatic/pending
+ * Get pending automatic games (oracle endpoint)
+ */
+router.get('/automatic/pending', async (req, res) => {
+  try {
+    // Get all automatic (gameMode = 4) games that are:
+    // 1. Not resolved yet (is_resolved = false)
+    // 2. Game has started (lock_timestamp < now)
+    // 3. Status is still 'pending' or 'locked' or 'in_progress'
+    const result = await pool.query(`
+      SELECT * FROM games
+      WHERE game_mode IN (4, 5)
+        AND is_resolved = false
+        AND (automatic_status IN ('pending', 'locked', 'in_progress') OR automatic_status IS NULL)
+      ORDER BY created_at DESC
+    `);
+
+    const games = result.rows.map(row => {
+      const sportsEvent = row.sports_event;
+      return {
+        gameId: row.game_id,
+        gameAddress: row.game_address,
+        title: row.title,
+        imageUrl: row.image_url,
+        matchupImageUrl: row.matchup_image_url, // Pre-generated S3 matchup image
+        gameType: row.game_type,
+        buyIn: parseFloat(row.buy_in),
+        maxPlayers: row.max_players,
+        gameMode: row.game_mode,
+        createdBy: row.created_by,
+        sportsEvent: sportsEvent,
+        // Top-level team info for easy access
+        homeTeam: sportsEvent?.strHomeTeam,
+        awayTeam: sportsEvent?.strAwayTeam,
+        league: sportsEvent?.strLeague,
+        homeTeamBadge: sportsEvent?.strHomeTeamBadge,
+        awayTeamBadge: sportsEvent?.strAwayTeamBadge,
+        strTimestamp: sportsEvent?.strTimestamp,
+        homeTeamPlayers: row.home_team_players || [],
+        awayTeamPlayers: row.away_team_players || [],
+        drawTeamPlayers: row.draw_team_players || [],
+        lockTimestamp: row.lock_timestamp,
+        lockTime: row.lock_timestamp ? { _seconds: row.lock_timestamp } : null, // Oracle expects this format
+        isLocked: row.is_locked,
+        isResolved: row.is_resolved,
+        automaticStatus: row.automatic_status,
+        createdAt: row.created_at,
+      };
+    });
+
+    console.log(`[getPendingGames] Found ${games.length} pending automatic game(s)`);
+
+    res.status(200).json({
+      success: true,
+      games: games
+    });
+
+  } catch (error) {
+    console.error('[getPendingGames] Error:', error);
+    res.status(500).json({
+      success: false,
+      error: error.message
+    });
+  }
+});
+
+/**
+ * POST /api/games/:gameId/update-notification-flags
+ * Update notification sent flags (oracle endpoint)
+ */
+router.post('/:gameId/update-notification-flags', async (req, res) => {
+  try {
+    const { gameId } = req.params;
+    const { lockNotificationSent_10min, lockNotificationSent_now } = req.body;
+
+    const updates = [];
+    const values = [];
+    let paramIndex = 1;
+
+    if (lockNotificationSent_10min !== undefined) {
+      updates.push(`lock_notification_sent_10min = $${paramIndex}`);
+      values.push(lockNotificationSent_10min);
+      paramIndex++;
+    }
+
+    if (lockNotificationSent_now !== undefined) {
+      updates.push(`lock_notification_sent_now = $${paramIndex}`);
+      values.push(lockNotificationSent_now);
+      paramIndex++;
+    }
+
+    if (updates.length === 0) {
+      return res.json({ success: true, message: 'No updates to make' });
+    }
+
+    values.push(gameId);
+
+    await pool.query(`
+      UPDATE games
+      SET ${updates.join(', ')},
+          updated_at = NOW()
+      WHERE game_id = $${paramIndex}
+    `, values);
+
+    console.log(`[updateNotificationFlags] Updated flags for ${gameId}:`, req.body);
+
+    res.json({
+      success: true,
+      message: 'Notification flags updated'
+    });
+
+  } catch (error) {
+    console.error('[updateNotificationFlags] Error:', error);
+    res.status(500).json({
+      success: false,
+      error: error.message
+    });
+  }
+});
+
+/**
+ * POST /api/games/:gameId/lock
+ * Lock a game when it starts (oracle endpoint)
+ */
+router.post('/:gameId/lock', async (req, res) => {
+  try {
+    const { gameId } = req.params;
+    const { lockedAt, lockedBy } = req.body;
+
+    console.log(`[lockGame] 🔒 Locking game: ${gameId}`);
+
+    // Update game status in PostgreSQL
+    const result = await pool.query(`
+      UPDATE games
+      SET 
+        is_locked = true,
+        automatic_status = 'locked',
+        updated_at = NOW()
+      WHERE game_id = $1 AND is_locked = false
+      RETURNING *
+    `, [gameId]);
+
+    if (result.rows.length === 0) {
+      console.log(`[lockGame] ℹ️  Game already locked or not found: ${gameId}`);
+      return res.status(200).json({
+        success: true,
+        message: 'Game already locked or not found'
+      });
+    }
+
+    console.log(`[lockGame] ✅ Successfully locked game ${gameId}`);
+
+    // Update Redis cache for all players in this game
+    const lockedGame = result.rows[0];
+    const allPlayers = [
+      ...(lockedGame.home_team_players || []),
+      ...(lockedGame.away_team_players || []),
+      ...(lockedGame.draw_team_players || []),
+    ];
+    gamesCacheService.updateGameForAllUsers(gameId, allPlayers, {
+      isLocked: true,
+      automaticStatus: 'locked',
+    }).catch(err => console.warn('[lockGame] Redis cache update failed:', err.message));
+
+    // Broadcast game locked event to all connected clients
+    if (chatNamespace) {
+      chatNamespace.emit('game:locked', {
+        gameId: gameId,
+        isLocked: true,
+        lockedAt: lockedAt || new Date().toISOString(),
+        lockedBy: lockedBy || 'oracle',
+        timestamp: Date.now()
+      });
+      console.log(`[lockGame] 📡 Broadcasted game:locked event to all clients`);
+    }
+
+    res.status(200).json({
+      success: true,
+      message: 'Game locked successfully',
+      game: result.rows[0]
+    });
+
+  } catch (error) {
+    console.error('[lockGame] ❌ Error:', error);
+    res.status(500).json({
+      success: false,
+      error: error.message
+    });
+  }
+});
+
+/**
+ * POST /api/games/:gameId/resolve
+ * Resolve a game (oracle endpoint)
+ */
+router.post('/:gameId/resolve', async (req, res) => {
+  try {
+    const { gameId } = req.params;
+    const { winner, homeScore, awayScore, resolvedAt, resolvedBy, resolveSignature } = req.body;
+
+    console.log(`[resolveGame] 🎯 Attempting to resolve game: ${gameId}`);
+    console.log(`[resolveGame]    Winner: ${winner === null ? 'null (REFUND)' : winner}, Score: ${homeScore}-${awayScore}`);
+    console.log(`[resolveGame]    Resolve signature: ${resolveSignature || 'NOT PROVIDED ⚠️'}`);
+
+    // Note: winner can be null for refund scenarios (no competition)
+    if (winner === undefined) {
+      console.error('[resolveGame] ❌ No winner provided (undefined)');
+      return res.status(400).json({
+        success: false,
+        error: 'Winner is required (use null for refunds)'
+      });
+    }
+
+    // First check if game exists
+    const checkResult = await pool.query(`
+      SELECT game_id, is_resolved, automatic_status FROM games WHERE game_id = $1
+    `, [gameId]);
+
+    console.log(`[resolveGame] 📊 Found ${checkResult.rows.length} game(s) with ID: ${gameId}`);
+    if (checkResult.rows.length > 0) {
+      console.log(`[resolveGame]    Current status: is_resolved=${checkResult.rows[0].is_resolved}, automatic_status=${checkResult.rows[0].automatic_status}`);
+    }
+
+    // Update game status in PostgreSQL (including claim_signature for transaction linking)
+    const result = await pool.query(`
+      UPDATE games
+      SET
+        is_resolved = true,
+        automatic_status = 'resolved',
+        claim_signature = COALESCE($3, claim_signature),
+        sports_event = COALESCE(sports_event, '{}'::jsonb) || $1::jsonb,
+        updated_at = NOW()
+      WHERE game_id = $2
+      RETURNING *
+    `, [
+      JSON.stringify({
+        finalScore: {
+          winner,
+          homeScore,
+          awayScore,
+          resolvedAt: resolvedAt || new Date().toISOString(),
+          resolvedBy: resolvedBy || 'oracle'
+        }
+      }),
+      gameId,
+      resolveSignature || null
+    ]);
+
+    if (resolveSignature) {
+      console.log(`[resolveGame] 💾 Saved claim_signature: ${resolveSignature.slice(0, 20)}...`);
+    }
+
+    if (result.rows.length === 0) {
+      console.error(`[resolveGame] ❌ Game not found in UPDATE: ${gameId}`);
+      return res.status(404).json({
+        success: false,
+        error: 'Game not found'
+      });
+    }
+
+    console.log(`[resolveGame] ✅ Successfully resolved game ${gameId} - Winner: ${winner} (${homeScore}-${awayScore})`);
+    console.log(`[resolveGame]    Updated status: is_resolved=${result.rows[0].is_resolved}, automatic_status=${result.rows[0].automatic_status}`);
+
+    // Update Redis cache for all players in this game
+    const resolvedGame = result.rows[0];
+    const resolveAllPlayers = [
+      ...(resolvedGame.home_team_players || []),
+      ...(resolvedGame.away_team_players || []),
+      ...(resolvedGame.draw_team_players || []),
+    ];
+    gamesCacheService.updateGameForAllUsers(gameId, resolveAllPlayers, {
+      isResolved: true,
+      automaticStatus: 'resolved',
+      finalScoreWinner: winner,
+      finalScoreHome: homeScore,
+      finalScoreAway: awayScore,
+    }).catch(err => console.warn('[resolveGame] Redis cache update failed:', err.message));
+
+    // 🎯 Update winners' user_game_refs with claim_signature for transaction history linking
+    if (resolveSignature && winner !== null) {
+      try {
+        // Determine winning team column based on winner
+        const winnerColumn = winner === 'home' ? 'home_team_players'
+                          : winner === 'away' ? 'away_team_players'
+                          : winner === 'draw' ? 'draw_team_players' : null;
+
+        if (winnerColumn) {
+          const winnersResult = await pool.query(`
+            UPDATE user_game_refs
+            SET claim_signature = $1, updated_at = NOW()
+            WHERE game_id = $2
+              AND wallet_address = ANY(
+                SELECT unnest(${winnerColumn}) FROM games WHERE game_id = $2
+              )
+            RETURNING wallet_address
+          `, [resolveSignature, gameId]);
+
+          console.log(`[resolveGame] 🎯 Updated ${winnersResult.rows.length} winner(s) with claim_signature`);
+        }
+      } catch (winnerUpdateError) {
+        console.error('[resolveGame] ⚠️ Error updating winners claim_signature:', winnerUpdateError.message);
+      }
+    }
+
+    // 💰 Process referral commission for GAME CREATOR's referrer ONLY
+    // The person who referred the game creator earns 1% of the ENTIRE POT
+    // Other players' referrers get NOTHING from this game
+    try {
+      // Get total pot size from game
+      const potResult = await pool.query(`
+        SELECT COALESCE(SUM(buy_in), 0) as total_pot 
+        FROM user_game_refs 
+        WHERE game_id = $1
+      `, [gameId]);
+      
+      const potSizeSOL = parseFloat(potResult.rows[0].total_pot) || 0;
+      const potSizeLamports = Math.floor(potSizeSOL * 1_000_000_000);
+      
+      if (potSizeLamports > 0) {
+        const gameType = result.rows[0].game_type || 'sports';
+        const referralResult = await referralEarningsService.processGameCommissions(
+          gameId,
+          gameType,
+          potSizeLamports
+        );
+        
+        if (referralResult.commissions.length > 0) {
+          const commission = referralResult.commissions[0]; // Only one commission per game
+          console.log(`[resolveGame] 💰 Game creator's referrer earns ${commission.commissionSOL.toFixed(4)} SOL (1% of ${potSizeSOL} SOL pot)`);
+          
+          // Notify the referrer in real-time via WebSocket
+          if (chatNamespace && global.onlineUsers) {
+            // Look up referrer's user ID
+            const referrerUserResult = await pool.query(
+              'SELECT id FROM users WHERE wallet_address = $1',
+              [commission.referrerWallet]
+            );
+            
+            if (referrerUserResult.rows.length > 0) {
+              const referrerUserId = referrerUserResult.rows[0].id;
+              const targetSocketId = global.onlineUsers.get(referrerUserId);
+              
+              if (targetSocketId) {
+                chatNamespace.to(targetSocketId).emit('referral:earning', {
+                  gameId: gameId,
+                  gameCreatorUsername: commission.refereeUsername,
+                  commissionSOL: commission.commissionSOL,
+                  potSizeSOL: potSizeSOL,
+                  message: `You earned ${commission.commissionSOL.toFixed(4)} SOL from ${commission.refereeUsername}'s game! (1% of ${potSizeSOL} SOL pot)`,
+                  timestamp: Date.now()
+                });
+                console.log(`[resolveGame] 📡 Sent referral:earning notification to ${commission.referrerWallet.slice(0, 8)}`);
+              }
+            }
+          }
+        } else {
+          console.log(`[resolveGame] 💰 No referral commission - game creator has no referrer`);
+        }
+      }
+    } catch (referralError) {
+      // Don't fail the resolution if referral processing fails
+      console.error('[resolveGame] ⚠️ Error processing referral commission (game still resolved):', referralError.message);
+    }
+
+    // Broadcast game resolved event to all connected clients
+    if (chatNamespace) {
+      chatNamespace.emit('game:resolved', {
+        gameId: gameId,
+        isResolved: true,
+        winner: winner,
+        homeScore: homeScore,
+        awayScore: awayScore,
+        resolvedAt: resolvedAt || new Date().toISOString(),
+        resolvedBy: resolvedBy || 'oracle',
+        timestamp: Date.now()
+      });
+      console.log(`[resolveGame] 📡 Broadcasted game:resolved event to all clients`);
+    }
+
+    res.status(200).json({
+      success: true,
+      message: 'Game resolved successfully',
+      game: result.rows[0]
+    });
+
+  } catch (error) {
+    console.error('[resolveGame] ❌ Error:', error);
+    res.status(500).json({
+      success: false,
+      error: error.message
+    });
+  }
+});
+
+/**
+ * GET /api/auth/games/user/:walletAddress
+ * Get games for a user.
+ *
+ * Pagination (opt-in): pass ?limit=10 to enable paginated mode.
+ *   - Redis-first: serves from cache with zero DB hits.
+ *   - Falls back to PostgreSQL with LIMIT on cache miss, then warms cache.
+ *   - Returns { games, nextCursor, hasMore }
+ *
+ * Without ?limit: returns ALL games (legacy behavior for other callers).
+ */
+router.get('/user/:walletAddress', async (req, res) => {
+  try {
+    const { walletAddress } = req.params;
+    const rawLimit = req.query.limit;
+    const paginated = rawLimit !== undefined;
+    const limit = paginated ? Math.min(parseInt(rawLimit) || 10, 50) : null;
+    const cursor = req.query.cursor || null;
+
+    // 1. Paginated mode: try Redis cache first
+    if (paginated) {
+      const cached = await gamesCacheService.getGames(walletAddress, { limit, cursor });
+      if (cached) {
+        console.log(`[getUserGames] Cache hit for ${walletAddress.slice(0, 8)}... (${cached.games.length} games)`);
+        return res.status(200).json({
+          success: true,
+          games: cached.games,
+          nextCursor: cached.nextCursor,
+          hasMore: cached.hasMore,
+        });
+      }
+    }
+
+    // 2. PostgreSQL query (with optional LIMIT for paginated mode)
+    if (paginated) {
+      console.log(`[getUserGames] Cache miss for ${walletAddress.slice(0, 8)}... — querying PostgreSQL (limit=${limit})`);
+    }
+
+    let queryText = `
+      SELECT
+        ugr.*,
+        g.game_address,
+        g.title,
+        g.image_url,
+        g.matchup_image_url,
+        g.game_type,
+        g.buy_in,
+        g.max_players,
+        g.game_mode,
+        g.created_by,
+        g.sports_event,
+        g.home_team_players,
+        g.away_team_players,
+        g.draw_team_players,
+        g.lock_timestamp,
+        g.is_locked,
+        g.is_resolved,
+        g.automatic_status,
+        g.connect4_winner,
+        g.game_status
+      FROM user_game_refs ugr
+      LEFT JOIN games g ON ugr.game_id = g.game_id
+      WHERE ugr.wallet_address = $1
+    `;
+    const queryParams = [walletAddress];
+
+    if (paginated && cursor) {
+      queryText += ` AND ugr.joined_at < $2 ORDER BY ugr.joined_at DESC LIMIT $3`;
+      queryParams.push(new Date(parseInt(cursor)).toISOString(), limit + 1);
+    } else if (paginated) {
+      queryText += ` ORDER BY ugr.joined_at DESC LIMIT $2`;
+      queryParams.push(limit + 1);
+    } else {
+      queryText += ` ORDER BY ugr.joined_at DESC`;
+    }
+
+    const result = await pool.query(queryText, queryParams);
+
+    // Determine hasMore (only relevant in paginated mode)
+    const hasMore = paginated ? result.rows.length > limit : false;
+    const rows = hasMore ? result.rows.slice(0, limit) : result.rows;
+
+    // For billiards games, we need to fetch players from user_game_refs
+    const billiardsGameIds = rows
+      .filter(row => row.game_type === 'billiards')
+      .map(row => row.game_id);
+
+    let billiardsPlayersMap = {};
+    if (billiardsGameIds.length > 0) {
+      const playersResult = await pool.query(`
+        SELECT
+          ugr.game_id,
+          ugr.wallet_address,
+          u.username,
+          u.avatar
+        FROM user_game_refs ugr
+        LEFT JOIN users u ON ugr.wallet_address = u.wallet_address
+        WHERE ugr.game_id = ANY($1)
+      `, [billiardsGameIds]);
+
+      playersResult.rows.forEach(row => {
+        if (!billiardsPlayersMap[row.game_id]) {
+          billiardsPlayersMap[row.game_id] = [];
+        }
+        billiardsPlayersMap[row.game_id].push({
+          walletAddress: row.wallet_address,
+          username: row.username || row.wallet_address?.slice(0, 6),
+          avatar: row.avatar || `https://api.dicebear.com/7.x/avataaars/svg?seed=${row.wallet_address}`,
+        });
+      });
+    }
+
+    const games = rows.map(row => {
+      const sportsEvent = row.sports_event;
+      let finalScore = sportsEvent?.finalScore || null;
+
+      let connect4Winner = null;
+      if (row.game_type === 'connect4' && row.connect4_winner) {
+        connect4Winner = row.connect4_winner;
+        finalScore = {
+          winner: row.connect4_winner,
+          homeScore: row.connect4_winner === 'home' ? 1 : 0,
+          awayScore: row.connect4_winner === 'away' ? 1 : 0,
+        };
+      }
+
+      let gameStatus = row.status;
+      if (row.game_type === 'connect4') {
+        if (row.game_status === 'cancelled') {
+          gameStatus = 'cancelled';
+        } else if (row.game_status === 'completed' || row.connect4_winner) {
+          gameStatus = 'completed';
+        } else if (row.game_status === 'playing' || row.game_status === 'in_progress') {
+          gameStatus = 'playing';
+        } else {
+          gameStatus = 'waiting';
+        }
+      }
+
+      const isBilliards = row.game_type === 'billiards';
+      const players = isBilliards ? (billiardsPlayersMap[row.game_id] || []) : [];
+
+      return {
+        gameId: row.game_id,
+        gameAddress: row.game_address,
+        title: row.title,
+        imageUrl: row.image_url,
+        matchupImageUrl: row.matchup_image_url,
+        gameType: row.game_type,
+        buyIn: parseFloat(row.buy_in),
+        maxPlayers: row.max_players,
+        gameMode: row.game_mode,
+        createdBy: row.created_by,
+        sportsEvent: sportsEvent,
+        homeTeam: sportsEvent?.strHomeTeam,
+        awayTeam: sportsEvent?.strAwayTeam,
+        league: sportsEvent?.strLeague,
+        homeTeamBadge: sportsEvent?.strHomeTeamBadge,
+        awayTeamBadge: sportsEvent?.strAwayTeamBadge,
+        strTimestamp: sportsEvent?.strTimestamp,
+        homeTeamPlayers: row.home_team_players || [],
+        awayTeamPlayers: row.away_team_players || [],
+        drawTeamPlayers: row.draw_team_players || [],
+        players: players,
+        roomName: isBilliards ? row.title : undefined,
+        lockTimestamp: row.lock_timestamp,
+        isLocked: row.is_locked,
+        isResolved: row.is_resolved,
+        automaticStatus: row.automatic_status,
+        finalScore: finalScore,
+        winner: connect4Winner,
+        status: gameStatus,
+        role: row.role,
+        joinedAt: row.joined_at,
+        teamChoice: row.team_choice,
+        mySignature: row.my_signature,
+        myExplorerUrl: row.my_explorer_url,
+        walletType: row.wallet_type,
+        claimedAt: row.claimed_at,
+        claimSignature: row.claim_signature,
+        claimExplorerUrl: row.claim_explorer_url,
+        amountClaimed: row.amount_claimed ? parseFloat(row.amount_claimed) : null,
+      };
+    });
+
+    // 3. Warm cache in background (non-blocking) — only in paginated mode on first page
+    if (paginated && !cursor && games.length > 0) {
+      gamesCacheService.warmCache(walletAddress, games)
+        .catch(err => console.warn('[getUserGames] Cache warm failed:', err.message));
+    }
+
+    // 4. Compute nextCursor from last game's joinedAt timestamp
+    let nextCursor = null;
+    if (hasMore && games.length > 0) {
+      const lastGame = games[games.length - 1];
+      nextCursor = new Date(lastGame.joinedAt).getTime().toString();
+    }
+
+    // Return response — include pagination fields only when paginated
+    const response = { success: true, games };
+    if (paginated) {
+      response.nextCursor = nextCursor;
+      response.hasMore = hasMore;
+    }
+    res.status(200).json(response);
+
+  } catch (error) {
+    console.error('[getUserGames] Error:', error);
+    res.status(500).json({
+      success: false,
+      error: error.message
+    });
+  }
+});
+
+/**
+ * GET /api/games/:gameId/state
+ * Get game state including current user's participation (protected endpoint)
+ */
+router.get('/:gameId/state', async (req, res) => {
+  try {
+    const { gameId } = req.params;
+    const walletAddress = req.headers['x-wallet-address']; // Optional
+
+    // Get game data
+    const gameResult = await pool.query('SELECT * FROM games WHERE game_id = $1', [gameId]);
+    
+    if (gameResult.rows.length === 0) {
+      return res.status(404).json({
+        success: false,
+        error: 'Game not found'
+      });
+    }
+
+    const game = gameResult.rows[0];
+    
+    // Build response
+    const response = {
+      gameId: game.game_id,
+      isLocked: game.is_locked,
+      isResolved: game.is_resolved,
+      homeTeamCount: game.home_team_players?.length || 0,
+      awayTeamCount: game.away_team_players?.length || 0,
+      drawTeamCount: game.draw_team_players?.length || 0,
+      totalPlayers: (game.home_team_players?.length || 0) + (game.away_team_players?.length || 0) + (game.draw_team_players?.length || 0),
+      totalPool: parseFloat(game.total_pool) || 0,
+      automaticStatus: game.automatic_status,
+    };
+
+    // If resolved, include winner and scores
+    if (game.is_resolved && game.sports_event?.finalScore) {
+      response.winner = game.sports_event.finalScore.winner;
+      response.homeScore = game.sports_event.finalScore.homeScore;
+      response.awayScore = game.sports_event.finalScore.awayScore;
+    }
+
+    // If wallet address provided, include user's participation
+    if (walletAddress) {
+      const userRefResult = await pool.query(
+        'SELECT team_choice, claimed_at FROM user_game_refs WHERE wallet_address = $1 AND game_id = $2',
+        [walletAddress, gameId]
+      );
+      
+      if (userRefResult.rows.length > 0) {
+        response.userTeamChoice = userRefResult.rows[0].team_choice;
+        response.userParticipated = true;
+        response.userClaimed = userRefResult.rows[0].claimed_at !== null; // Check if claimed
+        
+        // Determine if user won
+        if (game.is_resolved && game.sports_event?.finalScore) {
+          response.userWon = userRefResult.rows[0].team_choice === game.sports_event.finalScore.winner;
+        }
+      } else {
+        response.userParticipated = false;
+      }
+    }
+
+    res.json(response);
+  } catch (error) {
+    console.error('[getGameState] Error:', error);
+    res.status(500).json({
+      success: false,
+      error: error.message
+    });
+  }
+});
+
+/**
+ * POST /api/games/notify-participant
+ * Send notification to a game participant (used by oracle for game start notifications)
+ */
+router.post('/notify-participant', async (req, res) => {
+  try {
+    const { walletAddress, notificationType, message, gameInvite, finalScore } = req.body;
+
+    if (!walletAddress || !notificationType) {
+      return res.status(400).json({
+        success: false,
+        error: 'Missing required fields: walletAddress, notificationType'
+      });
+    }
+
+    // Get user ID from wallet address
+    const userResult = await pool.query(
+      'SELECT id, username FROM users WHERE wallet_address = $1',
+      [walletAddress]
+    );
+
+    if (userResult.rows.length === 0) {
+      // User not registered in web app, skip
+      return res.json({
+        success: true,
+        message: 'User not registered, notification skipped'
+      });
+    }
+
+    const userId = userResult.rows[0].id;
+    const username = userResult.rows[0].username;
+
+    // Enrich gameInvite with S3 URL from games table
+    const enrichedGameInvite = gameInvite 
+      ? await enrichGameInviteWithS3Url(pool, gameInvite)
+      : null;
+
+    // Build notification data
+    const notificationData = {
+      message,
+      gameInvite: enrichedGameInvite, // Use enriched gameInvite with S3 URL
+    };
+    
+    // Add finalScore for game result notifications
+    if (finalScore) {
+      notificationData.finalScore = finalScore;
+    }
+
+    console.log(`[notify-participant] Creating ${notificationType} notification:`, {
+      userId,
+      username,
+      hasGameInvite: !!gameInvite,
+      gameInviteTitle: gameInvite?.title,
+      hasFinalScore: !!finalScore
+    });
+
+    // Insert notification into database
+    const notifResult = await pool.query(
+      `INSERT INTO chat_notifications (
+        user_id, notification_type, notification_data, read, created_at
+      ) VALUES ($1, $2, $3, false, NOW())
+      RETURNING id`,
+      [
+        userId,
+        notificationType,
+        JSON.stringify(notificationData)
+      ]
+    );
+
+    const notificationId = notifResult.rows[0].id;
+
+    // Send real-time notification via WebSocket
+    if (chatNamespace) {
+      const notification = {
+        id: notificationId,
+        type: notificationType,
+        senderUsername: 'Dubs', // System notification
+        senderWallet: 'system',
+        message: message,
+        gameInvite: enrichedGameInvite, // Use enriched gameInvite with S3 URL
+        createdAt: new Date().toISOString(),
+        read: false,
+      };
+      
+      // Add finalScore for game result notifications
+      if (finalScore) {
+        notification.finalScore = finalScore;
+      }
+
+      chatNamespace.to(`user-${userId}`).emit('notification', notification);
+      console.log(`🔔 ${notificationType} notification sent to user-${userId} (${username})`);
+    }
+
+    // Cache notification to Redis (non-blocking)
+    notificationCacheService.cacheNotification(userId, {
+      id: notificationId,
+      type: notificationType,
+      read: false,
+      messageId: null,
+      message: message,
+      senderUsername: 'Dubs',
+      senderWallet: 'system',
+      senderAvatar: null,
+      createdAt: new Date(),
+      gameInvite: enrichedGameInvite,
+      finalScore: finalScore || null,
+    }).catch(err => console.error(`[gamesRoutes] Failed to cache ${notificationType} notification:`, err.message));
+
+    res.json({
+      success: true,
+      notificationId
+    });
+
+  } catch (error) {
+    console.error('Error sending participant notification:', error);
+    res.status(500).json({
+      success: false,
+      error: error.message
+    });
+  }
+});
+
+/**
+ * GET /api/games/:gameId/creator-referrer
+ * Get the referrer wallet of the game creator (for on-chain commission payout)
+ * 
+ * This is called by the oracle when resolving a game to determine
+ * if the game creator was referred by someone who should receive 1% commission.
+ * 
+ * Returns:
+ * - referrerWallet: The wallet address of the referrer (or null)
+ * - creatorWallet: The game creator's wallet
+ * - referrerUsername: The referrer's username (for logging)
+ */
+router.get('/:gameId/creator-referrer', async (req, res) => {
+  const { gameId } = req.params;
+  const logPrefix = `[CREATOR-REFERRER:${gameId.slice(-8)}]`;
+
+  console.log(`${logPrefix} 🔍 Incoming request to find game creator's referrer`);
+  console.log(`${logPrefix}    Full gameId: ${gameId}`);
+
+  try {
+    // Query to find the game creator and their referrer
+    // 1. Find the game's creator (created_by wallet)
+    // 2. Join to users table to find who referred the creator
+    console.log(`${logPrefix}    Executing database query...`);
+    const result = await pool.query(`
+      SELECT
+        g.game_id,
+        g.created_by as creator_wallet,
+        creator.id as creator_user_id,
+        creator.username as creator_username,
+        creator.referral_code as used_referral_code,
+        referrer.id as referrer_user_id,
+        referrer.wallet_address as referrer_wallet,
+        referrer.username as referrer_username,
+        referrer.my_referral_code as referrer_my_code
+      FROM games g
+      JOIN users creator ON g.created_by = creator.wallet_address
+      LEFT JOIN users referrer ON creator.referral_code = referrer.my_referral_code
+      WHERE g.game_id = $1
+    `, [gameId]);
+
+    console.log(`${logPrefix}    Query returned ${result.rows.length} row(s)`);
+
+    if (result.rows.length === 0) {
+      console.log(`${logPrefix} ⚠️ Game not found or creator not registered in users table`);
+      return res.json({
+        success: true,
+        referrerWallet: null,
+        message: 'Game not found or creator not registered'
+      });
+    }
+
+    const row = result.rows[0];
+    console.log(`${logPrefix}    Game creator: ${row.creator_username || 'unknown'} (${row.creator_wallet?.slice(0, 8)}...)`);
+    console.log(`${logPrefix}    Creator's referral_code: ${row.used_referral_code || 'NULL'}`);
+
+    if (!row.referrer_wallet) {
+      console.log(`${logPrefix} ℹ️ Creator has no referrer`);
+      if (row.used_referral_code) {
+        console.log(`${logPrefix}    ⚠️ Creator has referral_code="${row.used_referral_code}" but no matching referrer found!`);
+        console.log(`${logPrefix}    This could mean: referrer deleted, code typo, or referrer's my_referral_code changed`);
+      } else {
+        console.log(`${logPrefix}    Creator never signed up with a referral code`);
+      }
+      return res.json({
+        success: true,
+        referrerWallet: null,
+        creatorWallet: row.creator_wallet,
+        creatorUsername: row.creator_username,
+        message: 'Game creator has no referrer'
+      });
+    }
+
+    console.log(`${logPrefix} ✅ FOUND REFERRER!`);
+    console.log(`${logPrefix}    Referrer: ${row.referrer_username || 'unknown'} (${row.referrer_wallet})`);
+    console.log(`${logPrefix}    Referrer's my_referral_code: ${row.referrer_my_code}`);
+    console.log(`${logPrefix}    Match: creator.referral_code(${row.used_referral_code}) = referrer.my_referral_code(${row.referrer_my_code})`);
+
+    res.json({
+      success: true,
+      referrerWallet: row.referrer_wallet,
+      referrerUsername: row.referrer_username,
+      creatorWallet: row.creator_wallet,
+      creatorUsername: row.creator_username
+    });
+
+  } catch (error) {
+    console.error(`${logPrefix} ❌ ERROR in creator-referrer lookup:`);
+    console.error(`${logPrefix}    Message: ${error.message}`);
+    console.error(`${logPrefix}    Stack: ${error.stack}`);
+    res.status(500).json({
+      success: false,
+      error: error.message
+    });
+  }
+});
+
+module.exports = router;
+