dubs-server 1.0.0

package/routes/developerRoutes.js

@@ -0,0 +1,4201 @@
+/**
+ * 🔧 Developer API Routes
+ *
+ * Public developer API for third-party apps to integrate Dubs betting.
+ * Two sections:
+ *   1. Portal routes (JWT auth) — developer account/app/key management
+ *   2. Public API routes (API key auth) — game lifecycle, sports data
+ *
+ * Mounted at:
+ *   /api/developer       — Portal management (JWT auth)
+ *   /api/developer/v1    — Public API (API key auth)
+ */
+
+const express = require('express');
+const crypto = require('crypto');
+const axios = require('axios');
+const nacl = require('tweetnacl');
+const bs58 = require('bs58').default;
+const { PublicKey, Connection, Transaction } = require('@solana/web3.js');
+
+// Solana connection for transaction simulation
+const RPC_URL = process.env.SOLANA_NETWORK || 'http://127.0.0.1:8899';
+const connection = new Connection(RPC_URL, 'confirmed');
+const { pool } = require('../services/db');
+const { authenticate, generateToken, createSession, deleteSession, hashToken, JWT_EXPIRES_IN } = require('../middleware/authenticate');
+const { apiKeyAuth, hashApiKey, logApiCall } = require('../middleware/apiKeyAuth');
+const { developerUserAuth } = require('../middleware/developerUserAuth');
+const { fetchScoresForLeague, fetchUFCScores, ESPN_URLS } = require('../controllers/livescoresController');
+const { normalizeLeague } = require('../services/automaticGameOracle');
+const { getCustomGameResolver } = require('../services/customGameResolver');
+const PortfolioService = require('../services/portfolioService');
+const expoPushService = require('../services/expoPushService');
+
+// Singleton for SOL balance lookups (uses Alchemy RPC with 30s Redis cache)
+const portfolioService = new PortfolioService();
+
+// Two routers: one for portal (JWT), one for public API (API key)
+const portalRouter = express.Router();
+const apiRouter = express.Router();
+
+// ============================================================
+// UNIFIED EVENTS — Constants and Mappings
+// ============================================================
+
+const BASE_URL_INTERNAL = `http://localhost:${process.env.PORT || 3001}`;
+const ALL_SPORTS_LEAGUES = ['NBA', 'NHL', 'MLB', 'NFL', 'EPL', 'UFC', 'NCAAF', 'NCAAB'];
+const ALL_ESPORTS_VIDEOGAMES = ['cs-go', 'valorant'];
+
+/** Map from `game` query param to internal source identifier. Accepts slugs and aliases. */
+const GAME_PARAM_MAP = {
+  'nba': { type: 'sports', league: 'NBA' },
+  'nhl': { type: 'sports', league: 'NHL' },
+  'mlb': { type: 'sports', league: 'MLB' },
+  'nfl': { type: 'sports', league: 'NFL' },
+  'epl': { type: 'sports', league: 'EPL' },
+  'ufc': { type: 'sports', league: 'UFC' },
+  'ncaaf': { type: 'sports', league: 'NCAAF' },
+  'ncaab': { type: 'sports', league: 'NCAAB' },
+  'cs-go': { type: 'esports', videogame: 'cs-go' },
+  'cs2': { type: 'esports', videogame: 'cs-go' },
+  'counter-strike': { type: 'esports', videogame: 'cs-go' },
+  'valorant': { type: 'esports', videogame: 'valorant' },
+  'codmw': { type: 'esports', videogame: 'codmw' },
+};
+
+const LEAGUE_TO_GAME = {
+  'NBA': 'Basketball', 'NHL': 'Ice Hockey', 'MLB': 'Baseball',
+  'NFL': 'American Football', 'EPL': 'Soccer', 'UFC': 'Fighting',
+  'NCAAF': 'American Football', 'NCAAB': 'Basketball',
+};
+
+// Maps league abbreviation → value stored in sports_event.strLeague
+const LEAGUE_ABBREV_TO_DB = {
+  NBA: 'NBA', NHL: 'NHL', MLB: 'MLB', NFL: 'NFL',
+  EPL: 'English Premier League', UFC: 'UFC',
+  NCAAB: 'NCAAB', NCAAF: 'NCAAF',
+};
+
+/** Map internal DB status to public API status */
+function publicGameStatus(s) {
+  return s === 'pending' ? 'open' : s;
+}
+
+/** Normalize a raw games DB row into the public API GameListItem shape */
+function normalizeGameRow(g) {
+  const se = g.sports_event || {};
+  return {
+    gameId: g.game_id,
+    title: g.title,
+    buyIn: parseFloat(g.buy_in),
+    gameMode: g.game_mode,
+    isLocked: g.is_locked,
+    isResolved: g.is_resolved,
+    status: publicGameStatus(g.automatic_status),
+    totalPool: parseFloat(g.total_pool) || 0,
+    league: se.strLeague || null,
+    lockTimestamp: g.lock_timestamp,
+    createdAt: g.created_at,
+    opponents: [
+      { name: se.strHomeTeam || null, imageUrl: se.strHomeTeamBadge || null },
+      { name: se.strAwayTeam || null, imageUrl: se.strAwayTeamBadge || null },
+    ],
+    media: {
+      poster: g.matchup_image_url || se.strPoster || null,
+      thumbnail: g.matchup_image_url || se.strThumb || null,
+    },
+  };
+}
+
+// ============================================================
+// UNIFIED NORMALIZERS — Single shape for all event types
+// ============================================================
+
+function normalizeTimestamp(ts) {
+  if (!ts) return null;
+  if (ts.endsWith('Z') || /[+-]\d{2}:\d{2}$/.test(ts)) return ts;
+  return ts + 'Z';
+}
+
+function normalizeSportsStatus(strStatus) {
+  if (!strStatus) return 'upcoming';
+  const s = strStatus.toLowerCase().trim();
+  if (['ns', 'not started'].includes(s)) return 'upcoming';
+  if (['ft', 'match finished', 'aet', 'ap'].includes(s)) return 'finished';
+  if (['postponed', 'canceled', 'cancelled', 'abandoned'].includes(s)) return 'canceled';
+  return 'live';
+}
+
+function normalizeEsportsStatus(status) {
+  if (!status) return 'upcoming';
+  switch (status) {
+    case 'not_started': return 'upcoming';
+    case 'running': return 'live';
+    case 'finished': return 'finished';
+    case 'canceled':
+    case 'postponed': return 'canceled';
+    default: return 'upcoming';
+  }
+}
+
+/** TheSportsDB event → unified shape */
+function normalizeToUnifiedSportsEvent(raw, leagueAbbrev) {
+  return {
+    id: `sports:${leagueAbbrev}:${raw.idEvent}`,
+    type: 'sports',
+    title: raw.strEvent,
+    league: raw.strLeague || leagueAbbrev,
+    game: raw.strSport || LEAGUE_TO_GAME[leagueAbbrev] || null,
+    startTime: normalizeTimestamp(raw.strTimestamp),
+    status: normalizeSportsStatus(raw.strStatus),
+    tier: null,
+    venue: raw.strVenue || null,
+    opponents: [
+      { name: raw.strHomeTeam, imageUrl: raw.strHomeTeamBadge || null, score: raw.intHomeScore != null ? parseInt(raw.intHomeScore) : null },
+      { name: raw.strAwayTeam, imageUrl: raw.strAwayTeamBadge || null, score: raw.intAwayScore != null ? parseInt(raw.intAwayScore) : null },
+    ],
+    media: {
+      poster: raw.strPoster || null,
+      thumbnail: raw.strThumb || null,
+      streams: [],
+    },
+    meta: {
+      matchType: null,
+      numberOfGames: null,
+      tournament: null,
+      country: raw.strCountry || null,
+    },
+  };
+}
+
+/** Esports upcoming match (already normalized by dubs-server) → unified shape */
+function normalizeToUnifiedEsportsEvent(raw) {
+  return {
+    id: `esports:${raw.id}`,
+    type: 'esports',
+    title: raw.name,
+    league: raw.league || null,
+    game: raw.videogameName || raw.videogame || null,
+    startTime: normalizeTimestamp(raw.scheduledAt),
+    status: normalizeEsportsStatus(raw.status || 'not_started'),
+    tier: raw.tier || null,
+    venue: null,
+    opponents: (raw.opponents || []).map(o => ({
+      name: o.name,
+      imageUrl: o.imageUrl || null,
+      score: null,
+    })),
+    media: {
+      poster: null,
+      thumbnail: null,
+      streams: (raw.streams || []).map(s => {
+        if (typeof s === 'string') return { url: s, language: null };
+        return { url: s.raw_url || s.url || null, language: s.language || null };
+      }),
+    },
+    meta: {
+      matchType: raw.matchType || null,
+      numberOfGames: raw.numberOfGames || null,
+      tournament: raw.tournament || null,
+      country: null,
+    },
+  };
+}
+
+/**
+ * Transform raw PandaScore match detail (single match endpoint) into clean shape.
+ * Used only by GET /v1/esports/matches/:matchId (detail view).
+ */
+function transformEsportsMatchDetail(raw) {
+  const opponents = (raw.opponents || []).map(slot => {
+    const o = slot.opponent || slot;
+    return {
+      id: o.id,
+      name: o.name,
+      acronym: o.acronym || null,
+      imageUrl: o.image_url || o.imageUrl || null,
+    };
+  });
+
+  return {
+    matchId: raw.id,
+    title: raw.name,
+    status: raw.status,
+    videogame: raw.videogame?.name || raw.videogame || null,
+    league: raw.league?.name || null,
+    serie: raw.serie?.full_name || raw.serie?.name || null,
+    tournament: raw.tournament?.name || null,
+    tier: raw.tournament?.tier || raw.serie?.tier || null,
+    startTime: raw.scheduled_at || raw.begin_at,
+    endTime: raw.end_at || null,
+    matchType: raw.match_type || null,
+    numberOfGames: raw.number_of_games || null,
+    opponents,
+    results: (raw.results || []).map(r => ({
+      teamId: r.team_id,
+      score: r.score,
+    })),
+    winnerId: raw.winner_id || null,
+  };
+}
+
+// ============================================================
+// INTERNAL FETCHERS — Reusable localhost proxy calls
+// ============================================================
+
+async function fetchSportsEvents(league) {
+  try {
+    const response = await axios.get(`${BASE_URL_INTERNAL}/api/sports/events/${league}`, { timeout: 15000 });
+    const rawData = response.data;
+    return rawData?.data?.events || rawData?.events || [];
+  } catch (error) {
+    console.error(`[DevAPI] Error fetching sports events for ${league}:`, error.message);
+    return [];
+  }
+}
+
+async function fetchEsportsMatches(videogame) {
+  try {
+    const params = new URLSearchParams();
+    if (videogame) params.set('videogame', videogame);
+    params.set('per_page', '50');
+    params.set('page', '1');
+    const response = await axios.get(`${BASE_URL_INTERNAL}/api/esports/games/upcoming?${params.toString()}`, { timeout: 15000 });
+    return response.data?.data || [];
+  } catch (error) {
+    console.error(`[DevAPI] Error fetching esports matches:`, error.message);
+    return [];
+  }
+}
+
+// ============================================================
+// PORTAL ROUTES — JWT auth (developer dashboard management)
+// ============================================================
+
+/**
+ * POST /api/developer/account
+ * Create or get developer account (called on first portal login)
+ */
+portalRouter.post('/account', authenticate, async (req, res) => {
+  try {
+    const walletAddress = req.user.walletAddress;
+    const { displayName, email, commissionWallet } = req.body;
+
+    // Use the developer's own wallet for commission by default
+    const finalCommissionWallet = commissionWallet || walletAddress;
+
+    const result = await pool.query(`
+      INSERT INTO developer_accounts (wallet_address, display_name, email, commission_wallet)
+      VALUES ($1, $2, $3, $4)
+      ON CONFLICT (wallet_address)
+      DO UPDATE SET
+        display_name = COALESCE(EXCLUDED.display_name, developer_accounts.display_name),
+        email = COALESCE(EXCLUDED.email, developer_accounts.email),
+        commission_wallet = COALESCE(EXCLUDED.commission_wallet, developer_accounts.commission_wallet),
+        updated_at = NOW()
+      RETURNING *
+    `, [walletAddress, displayName || null, email || null, finalCommissionWallet]);
+
+    res.json({ success: true, account: result.rows[0] });
+  } catch (error) {
+    console.error('[Developer] Error creating account:', error.message);
+    res.status(500).json({ success: false, error: 'Failed to create developer account' });
+  }
+});
+
+/**
+ * GET /api/developer/account
+ * Get current developer account
+ */
+portalRouter.get('/account', authenticate, async (req, res) => {
+  try {
+    const result = await pool.query(
+      'SELECT * FROM developer_accounts WHERE wallet_address = $1',
+      [req.user.walletAddress]
+    );
+
+    if (result.rows.length === 0) {
+      return res.status(404).json({ success: false, error: 'Developer account not found' });
+    }
+
+    res.json({ success: true, account: result.rows[0] });
+  } catch (error) {
+    console.error('[Developer] Error fetching account:', error.message);
+    res.status(500).json({ success: false, error: 'Failed to fetch developer account' });
+  }
+});
+
+/**
+ * PATCH /api/developer/account
+ * Update developer account (display name, email, commission wallet)
+ */
+portalRouter.patch('/account', authenticate, async (req, res) => {
+  try {
+    const { displayName, email, commissionWallet } = req.body;
+
+    const result = await pool.query(`
+      UPDATE developer_accounts
+      SET display_name = COALESCE($2, display_name),
+          email = COALESCE($3, email),
+          commission_wallet = COALESCE($4, commission_wallet),
+          updated_at = NOW()
+      WHERE wallet_address = $1
+      RETURNING *
+    `, [req.user.walletAddress, displayName, email, commissionWallet]);
+
+    if (result.rows.length === 0) {
+      return res.status(404).json({ success: false, error: 'Developer account not found' });
+    }
+
+    res.json({ success: true, account: result.rows[0] });
+  } catch (error) {
+    console.error('[Developer] Error updating account:', error.message);
+    res.status(500).json({ success: false, error: 'Failed to update developer account' });
+  }
+});
+
+// ── Apps ──
+
+/**
+ * POST /api/developer/apps
+ * Create a new app
+ */
+portalRouter.post('/apps', authenticate, async (req, res) => {
+  try {
+    const { appName, description, websiteUrl } = req.body;
+
+    if (!appName) {
+      return res.status(400).json({ success: false, error: 'appName is required' });
+    }
+
+    // Look up developer account
+    const dev = await pool.query(
+      'SELECT id FROM developer_accounts WHERE wallet_address = $1',
+      [req.user.walletAddress]
+    );
+
+    if (dev.rows.length === 0) {
+      return res.status(404).json({ success: false, error: 'Create a developer account first' });
+    }
+
+    const developerId = dev.rows[0].id;
+
+    const resolutionSecret = crypto.randomBytes(32).toString('hex');
+
+    const result = await pool.query(`
+      INSERT INTO developer_apps (developer_id, app_name, description, website_url, resolution_secret)
+      VALUES ($1, $2, $3, $4, $5)
+      RETURNING *
+    `, [developerId, appName, description || null, websiteUrl || null, resolutionSecret]);
+
+    res.json({ success: true, app: result.rows[0] });
+  } catch (error) {
+    console.error('[Developer] Error creating app:', error.message);
+    res.status(500).json({ success: false, error: 'Failed to create app' });
+  }
+});
+
+/**
+ * GET /api/developer/apps
+ * List all apps for current developer
+ */
+portalRouter.get('/apps', authenticate, async (req, res) => {
+  try {
+    const result = await pool.query(`
+      SELECT a.* FROM developer_apps a
+      JOIN developer_accounts d ON a.developer_id = d.id
+      WHERE d.wallet_address = $1 AND a.status != 'deleted'
+      ORDER BY a.created_at DESC
+    `, [req.user.walletAddress]);
+
+    res.json({ success: true, apps: result.rows });
+  } catch (error) {
+    console.error('[Developer] Error listing apps:', error.message);
+    res.status(500).json({ success: false, error: 'Failed to list apps' });
+  }
+});
+
+/**
+ * GET /api/developer/apps/:appId
+ * Get a single app with its API keys (hints only)
+ */
+portalRouter.get('/apps/:appId', authenticate, async (req, res) => {
+  try {
+    const { appId } = req.params;
+
+    const appResult = await pool.query(`
+      SELECT a.* FROM developer_apps a
+      JOIN developer_accounts d ON a.developer_id = d.id
+      WHERE a.id = $1 AND d.wallet_address = $2
+    `, [appId, req.user.walletAddress]);
+
+    if (appResult.rows.length === 0) {
+      return res.status(404).json({ success: false, error: 'App not found' });
+    }
+
+    // Get API keys (hints only, never full keys)
+    const keysResult = await pool.query(`
+      SELECT id, key_prefix, key_hint, environment, is_active, created_at, last_used_at
+      FROM developer_api_keys
+      WHERE app_id = $1
+      ORDER BY created_at DESC
+    `, [appId]);
+
+    res.json({
+      success: true,
+      app: appResult.rows[0],
+      apiKeys: keysResult.rows,
+    });
+  } catch (error) {
+    console.error('[Developer] Error fetching app:', error.message);
+    res.status(500).json({ success: false, error: 'Failed to fetch app' });
+  }
+});
+
+/**
+ * PATCH /api/developer/apps/:appId
+ * Update app details
+ */
+portalRouter.patch('/apps/:appId', authenticate, async (req, res) => {
+  try {
+    const { appId } = req.params;
+    const { appName, description, websiteUrl, networkMode, uiConfig } = req.body;
+
+    // Validate networkMode if provided
+    if (networkMode && !['open', 'private'].includes(networkMode)) {
+      return res.status(400).json({ success: false, error: 'networkMode must be "open" or "private"' });
+    }
+
+    const result = await pool.query(`
+      UPDATE developer_apps
+      SET app_name = COALESCE($3, app_name),
+          description = COALESCE($4, description),
+          website_url = COALESCE($5, website_url),
+          network_mode = COALESCE($6, network_mode),
+          ui_config = COALESCE($7, ui_config),
+          updated_at = NOW()
+      FROM developer_accounts d
+      WHERE developer_apps.id = $1
+        AND developer_apps.developer_id = d.id
+        AND d.wallet_address = $2
+      RETURNING developer_apps.*
+    `, [appId, req.user.walletAddress, appName, description, websiteUrl, networkMode, uiConfig ? JSON.stringify(uiConfig) : null]);
+
+    if (result.rows.length === 0) {
+      return res.status(404).json({ success: false, error: 'App not found' });
+    }
+
+    res.json({ success: true, app: result.rows[0] });
+  } catch (error) {
+    console.error('[Developer] Error updating app:', error.message);
+    res.status(500).json({ success: false, error: 'Failed to update app' });
+  }
+});
+
+/**
+ * DELETE /api/developer/apps/:appId
+ * Soft-delete an app (sets status to 'deleted', deactivates all keys)
+ */
+portalRouter.delete('/apps/:appId', authenticate, async (req, res) => {
+  try {
+    const { appId } = req.params;
+
+    // Verify ownership
+    const appResult = await pool.query(`
+      SELECT a.id FROM developer_apps a
+      JOIN developer_accounts d ON a.developer_id = d.id
+      WHERE a.id = $1 AND d.wallet_address = $2
+    `, [appId, req.user.walletAddress]);
+
+    if (appResult.rows.length === 0) {
+      return res.status(404).json({ success: false, error: 'App not found' });
+    }
+
+    // Deactivate all keys
+    await pool.query('UPDATE developer_api_keys SET is_active = FALSE WHERE app_id = $1', [appId]);
+
+    // Soft delete the app
+    await pool.query(
+      "UPDATE developer_apps SET status = 'deleted', updated_at = NOW() WHERE id = $1",
+      [appId]
+    );
+
+    res.json({ success: true, message: 'App deleted' });
+  } catch (error) {
+    console.error('[Developer] Error deleting app:', error.message);
+    res.status(500).json({ success: false, error: 'Failed to delete app' });
+  }
+});
+
+// ── API Keys ──
+
+/**
+ * Generate a random API key with prefix
+ * Returns: { fullKey, keyHash, keyHint, keyPrefix }
+ */
+function generateApiKey(environment) {
+  const prefix = environment === 'production' ? 'dubs_live_' : 'dubs_test_';
+  const randomPart = crypto.randomBytes(24).toString('hex'); // 48 hex chars
+  const fullKey = prefix + randomPart;
+  const keyHash = hashApiKey(fullKey);
+  const keyHint = randomPart.slice(-4);
+
+  return { fullKey, keyHash, keyHint, keyPrefix: prefix };
+}
+
+/**
+ * POST /api/developer/apps/:appId/keys
+ * Generate a new API key for an app
+ * Body: { environment: 'sandbox' | 'production' }
+ * Returns full key ONCE — never shown again
+ */
+portalRouter.post('/apps/:appId/keys', authenticate, async (req, res) => {
+  try {
+    const { appId } = req.params;
+    const { environment = 'sandbox' } = req.body;
+
+    if (!['sandbox', 'production'].includes(environment)) {
+      return res.status(400).json({ success: false, error: 'environment must be sandbox or production' });
+    }
+
+    // Verify ownership
+    const appResult = await pool.query(`
+      SELECT a.id FROM developer_apps a
+      JOIN developer_accounts d ON a.developer_id = d.id
+      WHERE a.id = $1 AND d.wallet_address = $2 AND a.status = 'active'
+    `, [appId, req.user.walletAddress]);
+
+    if (appResult.rows.length === 0) {
+      return res.status(404).json({ success: false, error: 'App not found or not active' });
+    }
+
+    const { fullKey, keyHash, keyHint, keyPrefix } = generateApiKey(environment);
+
+    await pool.query(`
+      INSERT INTO developer_api_keys (app_id, key_prefix, key_hash, key_hint, environment)
+      VALUES ($1, $2, $3, $4, $5)
+    `, [appId, keyPrefix, keyHash, keyHint, environment]);
+
+    res.json({
+      success: true,
+      apiKey: fullKey,
+      hint: keyHint,
+      environment,
+      message: 'Save this key — it will not be shown again',
+    });
+  } catch (error) {
+    console.error('[Developer] Error generating API key:', error.message);
+    res.status(500).json({ success: false, error: 'Failed to generate API key' });
+  }
+});
+
+/**
+ * DELETE /api/developer/keys/:keyId
+ * Revoke an API key
+ */
+portalRouter.delete('/keys/:keyId', authenticate, async (req, res) => {
+  try {
+    const { keyId } = req.params;
+
+    const result = await pool.query(`
+      UPDATE developer_api_keys
+      SET is_active = FALSE
+      FROM developer_apps a
+      JOIN developer_accounts d ON a.developer_id = d.id
+      WHERE developer_api_keys.id = $1
+        AND developer_api_keys.app_id = a.id
+        AND d.wallet_address = $2
+      RETURNING developer_api_keys.id
+    `, [keyId, req.user.walletAddress]);
+
+    if (result.rows.length === 0) {
+      return res.status(404).json({ success: false, error: 'Key not found' });
+    }
+
+    res.json({ success: true, message: 'API key revoked' });
+  } catch (error) {
+    console.error('[Developer] Error revoking key:', error.message);
+    res.status(500).json({ success: false, error: 'Failed to revoke key' });
+  }
+});
+
+// ── Analytics / Earnings ──
+
+/**
+ * GET /api/developer/stats
+ * Get developer stats (total games, total volume, earnings)
+ */
+portalRouter.get('/stats', authenticate, async (req, res) => {
+  try {
+    const devResult = await pool.query(
+      'SELECT id FROM developer_accounts WHERE wallet_address = $1',
+      [req.user.walletAddress]
+    );
+
+    if (devResult.rows.length === 0) {
+      return res.status(404).json({ success: false, error: 'Developer account not found' });
+    }
+
+    const developerId = devResult.rows[0].id;
+
+    // Total games attributed to this developer
+    const gamesResult = await pool.query(
+      'SELECT COUNT(*) as total_games FROM developer_game_attributions WHERE developer_id = $1',
+      [developerId]
+    );
+
+    // Total API calls
+    const apiCallsResult = await pool.query(`
+      SELECT COUNT(*) as total_calls
+      FROM developer_api_logs l
+      JOIN developer_apps a ON l.app_id = a.id
+      WHERE a.developer_id = $1
+    `, [developerId]);
+
+    // Apps count
+    const appsResult = await pool.query(
+      "SELECT COUNT(*) as total_apps FROM developer_apps WHERE developer_id = $1 AND status = 'active'",
+      [developerId]
+    );
+
+    res.json({
+      success: true,
+      stats: {
+        totalGames: parseInt(gamesResult.rows[0].total_games),
+        totalApiCalls: parseInt(apiCallsResult.rows[0].total_calls),
+        totalApps: parseInt(appsResult.rows[0].total_apps),
+      }
+    });
+  } catch (error) {
+    console.error('[Developer] Error fetching stats:', error.message);
+    res.status(500).json({ success: false, error: 'Failed to fetch stats' });
+  }
+});
+
+/**
+ * GET /api/developer/apps/:appId/usage
+ * Get API usage stats for an app (last 30 days)
+ */
+portalRouter.get('/apps/:appId/usage', authenticate, async (req, res) => {
+  try {
+    const { appId } = req.params;
+
+    // Verify ownership
+    const appResult = await pool.query(`
+      SELECT a.id FROM developer_apps a
+      JOIN developer_accounts d ON a.developer_id = d.id
+      WHERE a.id = $1 AND d.wallet_address = $2
+    `, [appId, req.user.walletAddress]);
+
+    if (appResult.rows.length === 0) {
+      return res.status(404).json({ success: false, error: 'App not found' });
+    }
+
+    // Daily API calls for last 30 days
+    const usageResult = await pool.query(`
+      SELECT
+        DATE(created_at) as date,
+        COUNT(*) as calls,
+        AVG(response_time_ms)::int as avg_response_ms
+      FROM developer_api_logs
+      WHERE app_id = $1 AND created_at > NOW() - INTERVAL '30 days'
+      GROUP BY DATE(created_at)
+      ORDER BY date DESC
+    `, [appId]);
+
+    // Games attributed to this app
+    const gamesResult = await pool.query(
+      'SELECT COUNT(*) as total_games FROM developer_game_attributions WHERE app_id = $1',
+      [appId]
+    );
+
+    res.json({
+      success: true,
+      usage: usageResult.rows,
+      totalGames: parseInt(gamesResult.rows[0].total_games),
+    });
+  } catch (error) {
+    console.error('[Developer] Error fetching usage:', error.message);
+    res.status(500).json({ success: false, error: 'Failed to fetch usage stats' });
+  }
+});
+
+
+// ============================================================
+// WEBHOOK MANAGEMENT ROUTES (Portal — JWT auth)
+// ============================================================
+
+/**
+ * POST /api/developer/apps/:appId/webhooks
+ * Register a new webhook for an app
+ */
+portalRouter.post('/apps/:appId/webhooks', authenticate, async (req, res) => {
+  try {
+    const { appId } = req.params;
+    const { url, events, description } = req.body;
+
+    // Verify ownership
+    const appResult = await pool.query(
+      `SELECT da.id FROM developer_apps da
+       JOIN developer_accounts dac ON da.developer_id = dac.id
+       WHERE da.id = $1 AND dac.wallet_address = $2`,
+      [appId, req.user.walletAddress]
+    );
+    if (appResult.rows.length === 0) {
+      return res.status(404).json({ success: false, error: 'App not found' });
+    }
+
+    if (!url) return res.status(400).json({ success: false, error: 'url is required' });
+    if (!events || !Array.isArray(events) || events.length === 0) {
+      return res.status(400).json({ success: false, error: 'events array is required' });
+    }
+
+    // Validate URL (HTTPS or localhost for dev)
+    try {
+      const parsed = new URL(url);
+      if (parsed.protocol !== 'https:' && parsed.hostname !== 'localhost' && parsed.hostname !== '127.0.0.1') {
+        return res.status(400).json({ success: false, error: 'Webhook URL must use HTTPS (localhost allowed for development)' });
+      }
+    } catch {
+      return res.status(400).json({ success: false, error: 'Invalid URL' });
+    }
+
+    // Validate events
+    const invalid = events.filter(e => !ALLOWED_WEBHOOK_EVENTS.includes(e));
+    if (invalid.length > 0) {
+      return res.status(400).json({ success: false, error: `Invalid events: ${invalid.join(', ')}. Allowed: ${ALLOWED_WEBHOOK_EVENTS.join(', ')}` });
+    }
+
+    // Generate signing secret
+    const secret = crypto.randomBytes(32).toString('hex');
+
+    const result = await pool.query(
+      `INSERT INTO developer_webhooks (app_id, url, secret, events, description)
+       VALUES ($1, $2, $3, $4, $5)
+       RETURNING id, url, events, is_active, description, created_at`,
+      [appId, url, secret, events, description || null]
+    );
+
+    const webhook = result.rows[0];
+
+    res.json({
+      success: true,
+      webhook: {
+        id: webhook.id,
+        url: webhook.url,
+        events: webhook.events,
+        isActive: webhook.is_active,
+        description: webhook.description,
+        secret,  // Shown only once on creation
+        createdAt: webhook.created_at,
+      },
+      message: 'Save the secret — it will not be shown again.',
+    });
+  } catch (error) {
+    console.error('[Developer] Error creating webhook:', error.message);
+    res.status(500).json({ success: false, error: 'Failed to create webhook' });
+  }
+});
+
+/**
+ * GET /api/developer/apps/:appId/webhooks
+ * List all webhooks for an app
+ */
+portalRouter.get('/apps/:appId/webhooks', authenticate, async (req, res) => {
+  try {
+    const { appId } = req.params;
+
+    // Verify ownership
+    const appResult = await pool.query(
+      `SELECT da.id FROM developer_apps da
+       JOIN developer_accounts dac ON da.developer_id = dac.id
+       WHERE da.id = $1 AND dac.wallet_address = $2`,
+      [appId, req.user.walletAddress]
+    );
+    if (appResult.rows.length === 0) {
+      return res.status(404).json({ success: false, error: 'App not found' });
+    }
+
+    const result = await pool.query(
+      `SELECT id, url, events, is_active, description, secret, created_at, updated_at
+       FROM developer_webhooks WHERE app_id = $1 ORDER BY created_at DESC`,
+      [appId]
+    );
+
+    res.json({
+      success: true,
+      webhooks: result.rows.map(w => ({
+        id: w.id,
+        url: w.url,
+        events: w.events,
+        isActive: w.is_active,
+        description: w.description,
+        secretHint: '••••' + w.secret.slice(-4),
+        createdAt: w.created_at,
+        updatedAt: w.updated_at,
+      })),
+    });
+  } catch (error) {
+    console.error('[Developer] Error listing webhooks:', error.message);
+    res.status(500).json({ success: false, error: 'Failed to list webhooks' });
+  }
+});
+
+/**
+ * GET /api/developer/apps/:appId/users
+ * List users who have authenticated through this app, with SOL balances.
+ * Supports pagination (limit/offset) and search by username or wallet address.
+ */
+portalRouter.get('/apps/:appId/users', authenticate, async (req, res) => {
+  try {
+    const { appId } = req.params;
+    const limit = Math.min(20, Math.max(1, parseInt(req.query.limit) || 20));
+    const offset = Math.max(0, parseInt(req.query.offset) || 0);
+    const search = (req.query.search || '').trim();
+
+    // Verify ownership and get app environment
+    const appResult = await pool.query(
+      `SELECT da.id, da.environment FROM developer_apps da
+       JOIN developer_accounts dac ON da.developer_id = dac.id
+       WHERE da.id = $1 AND dac.wallet_address = $2`,
+      [appId, req.user.walletAddress]
+    );
+    if (appResult.rows.length === 0) {
+      return res.status(404).json({ success: false, error: 'App not found' });
+    }
+
+    const network = appResult.rows[0].environment === 'production' ? 'mainnet-beta' : 'devnet';
+
+    // Build WHERE clause with optional search
+    const whereClauses = ['dau.developer_app_id = $1'];
+    const params = [appId];
+
+    if (search) {
+      params.push(`%${search}%`);
+      whereClauses.push(`(u.username ILIKE $${params.length} OR u.wallet_address ILIKE $${params.length})`);
+    }
+
+    const whereSQL = whereClauses.join(' AND ');
+
+    // Count total
+    const countResult = await pool.query(
+      `SELECT COUNT(*) FROM developer_app_users dau
+       JOIN users u ON dau.user_id = u.id
+       WHERE ${whereSQL}`,
+      params
+    );
+    const total = parseInt(countResult.rows[0].count);
+
+    // Stats: active in last 7 days, new in last 7 days
+    const statsResult = await pool.query(
+      `SELECT
+         COUNT(*) FILTER (WHERE dau.last_seen_at > NOW() - INTERVAL '7 days') AS active_7d,
+         COUNT(*) FILTER (WHERE dau.first_seen_at > NOW() - INTERVAL '7 days') AS new_7d
+       FROM developer_app_users dau
+       WHERE dau.developer_app_id = $1`,
+      [appId]
+    );
+
+    // Fetch page of users
+    const usersResult = await pool.query(`
+      SELECT
+        u.wallet_address,
+        u.username,
+        u.avatar,
+        u.created_at,
+        dau.first_seen_at,
+        dau.last_seen_at,
+        dau.device_info
+      FROM developer_app_users dau
+      JOIN users u ON dau.user_id = u.id
+      WHERE ${whereSQL}
+      ORDER BY dau.last_seen_at DESC
+      LIMIT $${params.length + 1} OFFSET $${params.length + 2}
+    `, [...params, limit, offset]);
+
+    // Enrich with SOL balances in parallel
+    const balanceResults = await Promise.allSettled(
+      usersResult.rows.map(u =>
+        portfolioService.getPortfolio(u.wallet_address, network)
+      )
+    );
+
+    const users = usersResult.rows.map((u, i) => {
+      const balResult = balanceResults[i];
+      const solBalance = balResult.status === 'fulfilled'
+        ? balResult.value.nativeBalance.balance
+        : null;
+
+      return {
+        walletAddress: u.wallet_address,
+        username: u.username,
+        avatar: u.avatar,
+        createdAt: u.created_at,
+        firstSeenAt: u.first_seen_at,
+        lastSeenAt: u.last_seen_at,
+        solBalance,
+        deviceInfo: u.device_info || null,
+      };
+    });
+
+    res.json({
+      success: true,
+      data: {
+        users,
+        stats: {
+          total,
+          active7d: parseInt(statsResult.rows[0].active_7d),
+          new7d: parseInt(statsResult.rows[0].new_7d),
+        },
+        pagination: { total, limit, offset },
+      },
+    });
+  } catch (error) {
+    console.error('[Developer] Error listing app users:', error.message);
+    res.status(500).json({ success: false, error: 'Failed to list app users' });
+  }
+});
+
+/**
+ * GET /api/developer/apps/:appId/users/:walletAddress
+ * Get detailed user info including full portfolio (SOL, tokens, NFTs).
+ */
+portalRouter.get('/apps/:appId/users/:walletAddress', authenticate, async (req, res) => {
+  try {
+    const { appId, walletAddress } = req.params;
+
+    // Verify ownership and get app environment
+    const appResult = await pool.query(
+      `SELECT da.id, da.environment FROM developer_apps da
+       JOIN developer_accounts dac ON da.developer_id = dac.id
+       WHERE da.id = $1 AND dac.wallet_address = $2`,
+      [appId, req.user.walletAddress]
+    );
+    if (appResult.rows.length === 0) {
+      return res.status(404).json({ success: false, error: 'App not found' });
+    }
+
+    const network = appResult.rows[0].environment === 'production' ? 'mainnet-beta' : 'devnet';
+
+    // Fetch user + app relationship
+    const userResult = await pool.query(`
+      SELECT
+        u.id,
+        u.wallet_address,
+        u.username,
+        u.avatar,
+        u.created_at,
+        dau.first_seen_at,
+        dau.last_seen_at,
+        dau.device_info
+      FROM developer_app_users dau
+      JOIN users u ON dau.user_id = u.id
+      WHERE dau.developer_app_id = $1 AND u.wallet_address = $2
+    `, [appId, walletAddress]);
+
+    if (userResult.rows.length === 0) {
+      return res.status(404).json({ success: false, error: 'User not found in this app' });
+    }
+
+    const u = userResult.rows[0];
+
+    // Fetch full portfolio
+    let portfolio = null;
+    try {
+      portfolio = await portfolioService.getPortfolio(walletAddress, network);
+    } catch (err) {
+      console.error(`[Developer] Portfolio fetch failed for ${walletAddress}:`, err.message);
+    }
+
+    // Fetch push tokens for this user+app
+    let pushTokens = [];
+    try {
+      const pushResult = await pool.query(
+        `SELECT token, platform, device_name, active, created_at
+         FROM expo_push_tokens
+         WHERE user_id = $1 AND developer_app_id = $2
+         ORDER BY updated_at DESC`,
+        [u.id, appId]
+      );
+      pushTokens = pushResult.rows.map(t => ({
+        token: t.token,
+        platform: t.platform,
+        deviceName: t.device_name,
+        active: t.active,
+        createdAt: t.created_at,
+      }));
+    } catch (err) {
+      console.error(`[Developer] Push tokens fetch failed for user ${u.id}:`, err.message);
+    }
+
+    res.json({
+      success: true,
+      data: {
+        user: {
+          walletAddress: u.wallet_address,
+          username: u.username,
+          avatar: u.avatar,
+          createdAt: u.created_at,
+          firstSeenAt: u.first_seen_at,
+          lastSeenAt: u.last_seen_at,
+        },
+        deviceInfo: u.device_info || null,
+        pushTokens,
+        portfolio: portfolio ? {
+          solBalance: portfolio.nativeBalance.balance,
+          solBalanceFormatted: portfolio.nativeBalance.balanceFormatted,
+          tokens: portfolio.tokenBalances.map(t => ({
+            mint: t.mint,
+            symbol: t.symbol,
+            name: t.name,
+            balance: t.balance,
+            balanceFormatted: t.balanceFormatted,
+            decimals: t.decimals,
+            logo: t.metadata?.logoURI || null,
+            isToken2022: t.isTokenExtension,
+          })),
+          nfts: portfolio.nftBalances.map(n => ({
+            mint: n.mint,
+            name: n.name,
+            symbol: n.symbol,
+            logo: n.metadata?.logoURI || null,
+            isToken2022: n.isTokenExtension,
+          })),
+          tokenCount: portfolio.fungibleTokenCount,
+          nftCount: portfolio.nftCount,
+          network,
+          fetchTimeMs: portfolio.fetchTimeMs,
+          fromCache: portfolio.fromCache,
+        } : null,
+      },
+    });
+  } catch (error) {
+    console.error('[Developer] Error fetching user detail:', error.message);
+    res.status(500).json({ success: false, error: 'Failed to fetch user details' });
+  }
+});
+
+/**
+ * POST /api/developer/apps/:appId/users/:walletAddress/push-test
+ * Send a test push notification to a user from the developer portal.
+ */
+portalRouter.post('/apps/:appId/users/:walletAddress/push-test', authenticate, async (req, res) => {
+  try {
+    const { appId, walletAddress } = req.params;
+    const { title, body } = req.body;
+
+    // Verify ownership
+    const appResult = await pool.query(
+      `SELECT da.id FROM developer_apps da
+       JOIN developer_accounts dac ON da.developer_id = dac.id
+       WHERE da.id = $1 AND dac.wallet_address = $2`,
+      [appId, req.user.walletAddress]
+    );
+    if (appResult.rows.length === 0) {
+      return res.status(404).json({ success: false, error: 'App not found' });
+    }
+
+    // Get user ID
+    const userResult = await pool.query(
+      'SELECT id FROM users WHERE wallet_address = $1',
+      [walletAddress]
+    );
+    if (userResult.rows.length === 0) {
+      return res.status(404).json({ success: false, error: 'User not found' });
+    }
+
+    const result = await expoPushService.sendToUser(userResult.rows[0].id, {
+      title: title || 'Test Notification',
+      body: body || 'This is a test push from the Dubs developer dashboard',
+      data: { type: 'test' },
+    });
+
+    res.json({ success: true, data: result });
+  } catch (error) {
+    console.error('[Developer] Error sending test push:', error.message);
+    res.status(500).json({ success: false, error: 'Failed to send test push' });
+  }
+});
+
+/**
+ * GET /api/developer/apps/:appId/games
+ * List games attributed to this app via developer_game_attributions.
+ * Supports pagination, status filter, and search by title or game_id.
+ */
+portalRouter.get('/apps/:appId/games', authenticate, async (req, res) => {
+  try {
+    const { appId } = req.params;
+    const limit = Math.min(50, Math.max(1, parseInt(req.query.limit) || 20));
+    const offset = Math.max(0, parseInt(req.query.offset) || 0);
+    const status = req.query.status || '';   // open, locked, resolved
+    const search = (req.query.search || '').trim();
+
+    // Verify ownership
+    const appResult = await pool.query(
+      `SELECT da.id FROM developer_apps da
+       JOIN developer_accounts dac ON da.developer_id = dac.id
+       WHERE da.id = $1 AND dac.wallet_address = $2`,
+      [appId, req.user.walletAddress]
+    );
+    if (appResult.rows.length === 0) {
+      return res.status(404).json({ success: false, error: 'App not found' });
+    }
+
+    // Build WHERE clauses
+    const whereClauses = ['dga.app_id = $1'];
+    const params = [appId];
+
+    if (status) {
+      // Map public status back to DB status
+      const dbStatus = status === 'open' ? 'pending' : status;
+      params.push(dbStatus);
+      whereClauses.push(`g.automatic_status = $${params.length}`);
+    }
+
+    if (search) {
+      params.push(`%${search}%`);
+      whereClauses.push(`(g.title ILIKE $${params.length} OR g.game_id ILIKE $${params.length})`);
+    }
+
+    const whereSQL = whereClauses.join(' AND ');
+
+    // Count total
+    const countResult = await pool.query(
+      `SELECT COUNT(DISTINCT g.game_id) FROM developer_game_attributions dga
+       JOIN games g ON dga.game_id = g.game_id
+       WHERE ${whereSQL}`,
+      params
+    );
+    const total = parseInt(countResult.rows[0].count);
+
+    // Stats: open, locked, resolved counts for this app
+    const statsResult = await pool.query(
+      `SELECT
+         COUNT(DISTINCT g.game_id) AS total,
+         COUNT(DISTINCT g.game_id) FILTER (WHERE g.automatic_status = 'pending') AS open,
+         COUNT(DISTINCT g.game_id) FILTER (WHERE g.automatic_status = 'locked' OR g.automatic_status = 'in_progress') AS locked,
+         COUNT(DISTINCT g.game_id) FILTER (WHERE g.automatic_status = 'resolved') AS resolved
+       FROM developer_game_attributions dga
+       JOIN games g ON dga.game_id = g.game_id
+       WHERE dga.app_id = $1`,
+      [appId]
+    );
+
+    // Fetch page of games
+    const gamesResult = await pool.query(`
+      SELECT * FROM (
+        SELECT DISTINCT ON (g.game_id)
+          g.game_id, g.title, g.buy_in, g.game_mode,
+          g.is_locked, g.is_resolved, g.automatic_status,
+          g.total_pool, g.lock_timestamp, g.created_at,
+          g.created_by, g.game_address,
+          g.home_team_players, g.away_team_players, g.draw_team_players,
+          g.sports_event, g.matchup_image_url, g.max_players,
+          g.sports_event->'finalScore'->>'winner' as winner_side,
+          (SELECT COUNT(*) FROM user_game_refs ugr WHERE ugr.game_id = g.game_id AND ugr.claimed_at IS NOT NULL) as claimed_count
+        FROM developer_game_attributions dga
+        JOIN games g ON dga.game_id = g.game_id
+        WHERE ${whereSQL}
+        ORDER BY g.game_id, g.created_at DESC
+      ) deduped
+      ORDER BY deduped.created_at DESC
+      LIMIT $${params.length + 1} OFFSET $${params.length + 2}
+    `, [...params, limit, offset]);
+
+    const games = gamesResult.rows.map(g => {
+      const base = normalizeGameRow(g);
+      const homePlayers = (g.home_team_players || []);
+      const awayPlayers = (g.away_team_players || []);
+      const drawPlayers = (g.draw_team_players || []);
+      const playerCount = homePlayers.length + awayPlayers.length + drawPlayers.length;
+
+      // Compute claim status for resolved games
+      let claimStatus = null;
+      if (g.is_resolved) {
+        const winnerSide = g.winner_side || null;
+        const claimedCount = parseInt(g.claimed_count) || 0;
+        let eligibleCount;
+        if (!winnerSide) {
+          // Refund — all players are eligible
+          eligibleCount = playerCount;
+        } else if (winnerSide === 'home') {
+          eligibleCount = homePlayers.length;
+        } else if (winnerSide === 'away') {
+          eligibleCount = awayPlayers.length;
+        } else if (winnerSide === 'draw') {
+          eligibleCount = drawPlayers.length;
+        } else {
+          eligibleCount = playerCount;
+        }
+        claimStatus = { winnerSide, claimedCount, eligibleCount };
+      }
+
+      return {
+        ...base,
+        gameAddress: g.game_address,
+        createdBy: g.created_by,
+        maxPlayers: g.max_players || 0,
+        playerCount,
+        claimStatus,
+      };
+    });
+
+    const s = statsResult.rows[0];
+    res.json({
+      success: true,
+      data: {
+        games,
+        stats: {
+          total: parseInt(s.total),
+          open: parseInt(s.open),
+          locked: parseInt(s.locked),
+          resolved: parseInt(s.resolved),
+        },
+        pagination: { total, limit, offset },
+      },
+    });
+  } catch (error) {
+    console.error('[Developer] Error listing app games:', error.message);
+    res.status(500).json({ success: false, error: 'Failed to list app games' });
+  }
+});
+
+/**
+ * GET /api/developer/apps/:appId/games/:gameId
+ * Get detailed game info including enriched player profiles, signatures, and pools.
+ */
+portalRouter.get('/apps/:appId/games/:gameId', authenticate, async (req, res) => {
+  try {
+    const { appId, gameId } = req.params;
+
+    // Verify ownership
+    const appResult = await pool.query(
+      `SELECT da.id, da.environment FROM developer_apps da
+       JOIN developer_accounts dac ON da.developer_id = dac.id
+       WHERE da.id = $1 AND dac.wallet_address = $2`,
+      [appId, req.user.walletAddress]
+    );
+    if (appResult.rows.length === 0) {
+      return res.status(404).json({ success: false, error: 'App not found' });
+    }
+
+    // Verify game belongs to this app
+    const attrResult = await pool.query(
+      `SELECT id FROM developer_game_attributions WHERE game_id = $1 AND app_id = $2`,
+      [gameId, appId]
+    );
+    if (attrResult.rows.length === 0) {
+      return res.status(404).json({ success: false, error: 'Game not found in this app' });
+    }
+
+    // Fetch game
+    const gameResult = await pool.query(`
+      SELECT
+        g.game_id, g.game_address, g.title, g.buy_in, g.game_mode,
+        g.is_locked, g.is_resolved, g.automatic_status, g.lock_timestamp,
+        g.home_team_players, g.away_team_players, g.draw_team_players,
+        g.player_amounts, g.home_pool, g.away_pool, g.draw_pool, g.total_pool,
+        g.sports_event, g.matchup_image_url, g.max_players,
+        g.created_by, g.claim_signature, g.created_at, g.updated_at, g.completed_at,
+        g.sports_event->'finalScore'->>'winner' as winner_side
+      FROM games g WHERE g.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];
+    const se = game.sports_event || {};
+    const playerAmounts = game.player_amounts || {};
+
+    // Build players array with profiles + signatures from user_game_refs
+    const allWallets = [
+      ...(game.home_team_players || []).map(w => ({ wallet: w, team: 'home' })),
+      ...(game.away_team_players || []).map(w => ({ wallet: w, team: 'away' })),
+      ...(game.draw_team_players || []).map(w => ({ wallet: w, team: 'draw' })),
+    ];
+
+    let players = [];
+    if (allWallets.length > 0) {
+      const uniqueWallets = [...new Set(allWallets.map(b => b.wallet))];
+
+      // Fetch user profiles
+      const usersResult = await pool.query(
+        `SELECT wallet_address, username, avatar FROM users WHERE wallet_address = ANY($1)`,
+        [uniqueWallets]
+      );
+      const userMap = {};
+      for (const u of usersResult.rows) {
+        userMap[u.wallet_address] = u;
+      }
+
+      // Fetch user_game_refs for signatures
+      const refsResult = await pool.query(
+        `SELECT wallet_address, role, team_choice, joined_at, my_signature, my_explorer_url,
+                claim_signature, claim_explorer_url, amount_claimed
+         FROM user_game_refs WHERE game_id = $1 AND wallet_address = ANY($2)`,
+        [gameId, uniqueWallets]
+      );
+      const refMap = {};
+      for (const r of refsResult.rows) {
+        refMap[r.wallet_address] = r;
+      }
+
+      players = allWallets.map(b => {
+        const user = userMap[b.wallet] || {};
+        const ref = refMap[b.wallet] || {};
+        return {
+          wallet: b.wallet,
+          username: user.username || null,
+          avatar: user.avatar || null,
+          team: b.team,
+          amount: parseFloat(playerAmounts[b.wallet]) || parseFloat(game.buy_in),
+          role: ref.role || null,
+          joinedAt: ref.joined_at || null,
+          joinSignature: ref.my_signature || null,
+          joinExplorerUrl: ref.my_explorer_url || null,
+          claimSignature: ref.claim_signature || null,
+          claimExplorerUrl: ref.claim_explorer_url || null,
+          amountClaimed: ref.amount_claimed ? parseFloat(ref.amount_claimed) : null,
+        };
+      });
+    }
+
+    res.json({
+      success: true,
+      data: {
+        game: {
+          gameId: game.game_id,
+          gameAddress: game.game_address,
+          title: game.title,
+          buyIn: parseFloat(game.buy_in),
+          gameMode: game.game_mode,
+          isLocked: game.is_locked,
+          isResolved: game.is_resolved,
+          status: publicGameStatus(game.automatic_status),
+          league: se.strLeague || null,
+          lockTimestamp: game.lock_timestamp,
+          maxPlayers: game.max_players || 0,
+          createdBy: game.created_by,
+          resolveSignature: game.claim_signature || null,
+          completedAt: game.completed_at || null,
+          opponents: [
+            { name: se.strHomeTeam || null, imageUrl: se.strHomeTeamBadge || null },
+            { name: se.strAwayTeam || null, imageUrl: se.strAwayTeamBadge || null },
+          ],
+          pools: {
+            home: parseFloat(game.home_pool) || 0,
+            away: parseFloat(game.away_pool) || 0,
+            draw: parseFloat(game.draw_pool) || 0,
+            total: parseFloat(game.total_pool) || 0,
+          },
+          media: {
+            poster: game.matchup_image_url || se.strPoster || null,
+            thumbnail: game.matchup_image_url || se.strThumb || null,
+          },
+          winnerSide: game.winner_side || null,
+          players,
+          createdAt: game.created_at,
+          updatedAt: game.updated_at,
+        },
+      },
+    });
+  } catch (error) {
+    console.error('[Developer] Error fetching game detail:', error.message);
+    res.status(500).json({ success: false, error: 'Failed to fetch game details' });
+  }
+});
+
+/**
+ * POST /api/developer/apps/:appId/games/:gameId/resolve
+ * Manually resolve a custom game (game_mode=6) from the developer portal.
+ * Used when SDK resolution fails (e.g., network error) and game is stuck.
+ */
+portalRouter.post('/apps/:appId/games/:gameId/resolve', authenticate, async (req, res) => {
+  try {
+    const { appId, gameId } = req.params;
+    const { winner } = req.body; // 'home' | 'away' | 'draw' | null
+
+    // Validate winner value
+    if (winner !== null && winner !== undefined && !['home', 'away', 'draw'].includes(winner)) {
+      return res.status(400).json({ success: false, error: 'Invalid winner value. Must be "home", "away", "draw", or null (refund).' });
+    }
+
+    // Verify developer owns the app
+    const appResult = await pool.query(
+      `SELECT da.id, da.environment FROM developer_apps da
+       JOIN developer_accounts dac ON da.developer_id = dac.id
+       WHERE da.id = $1 AND dac.wallet_address = $2`,
+      [appId, req.user.walletAddress]
+    );
+    if (appResult.rows.length === 0) {
+      return res.status(404).json({ success: false, error: 'App not found' });
+    }
+
+    // Verify game belongs to this app
+    const attrResult = await pool.query(
+      `SELECT id FROM developer_game_attributions WHERE game_id = $1 AND app_id = $2`,
+      [gameId, appId]
+    );
+    if (attrResult.rows.length === 0) {
+      return res.status(404).json({ success: false, error: 'Game not found in this app' });
+    }
+
+    // Fetch game and validate
+    const gameResult = await pool.query(
+      `SELECT game_id, game_mode, is_locked, is_resolved,
+              home_team_players, away_team_players, draw_team_players
+       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];
+
+    if (game.game_mode !== 6) {
+      return res.status(400).json({ success: false, error: 'Only custom games (game_mode=6) can be resolved via this endpoint' });
+    }
+    if (game.is_resolved) {
+      return res.status(409).json({ success: false, error: 'Game has already been resolved' });
+    }
+
+    // Auto-lock if not locked yet
+    if (!game.is_locked) {
+      await pool.query(
+        `UPDATE games SET is_locked = true, automatic_status = 'locked', updated_at = NOW() WHERE game_id = $1`,
+        [gameId]
+      );
+      console.log(`[Portal] Auto-locked game ${gameId} before resolution`);
+    }
+
+    // Check for competition — if only one side has bets, force refund
+    const homePlayers = game.home_team_players || [];
+    const awayPlayers = game.away_team_players || [];
+    const drawPlayers = game.draw_team_players || [];
+    const sidesWithBets = [homePlayers.length > 0, awayPlayers.length > 0, drawPlayers.length > 0].filter(Boolean).length;
+
+    let effectiveWinner = winner ?? null;
+    if (sidesWithBets < 2) {
+      effectiveWinner = null;
+      console.log(`[Portal] Game ${gameId} has only ${sidesWithBets} side(s) with bets — forcing refund`);
+    }
+
+    // Resolve on-chain + update DB
+    const resolver = getCustomGameResolver();
+    const { signature: txSignature } = await resolver.resolveGame(gameId, effectiveWinner);
+
+    // Fire webhook notification
+    fireWebhooks(appId, 'game.resolved', {
+      gameId,
+      winner: effectiveWinner,
+      signature: txSignature,
+    });
+
+    console.log(`[Portal] Game ${gameId} resolved by developer ${req.user.walletAddress} — winner: ${effectiveWinner}, tx: ${txSignature}`);
+
+    res.json({
+      success: true,
+      gameId,
+      winner: effectiveWinner,
+      signature: txSignature,
+      explorerUrl: `https://solscan.io/tx/${txSignature}`,
+    });
+  } catch (error) {
+    console.error('[Portal] Error resolving game:', error.message);
+
+    // Try to extract a human-readable message from Solana program errors
+    let userMessage = error.message;
+
+    // Check for custom program error hex code in the message (e.g. 0x179b)
+    const hexMatch = error.message.match(/custom program error: 0x([0-9a-fA-F]+)/);
+    if (hexMatch) {
+      const errorCode = parseInt(hexMatch[1], 16);
+      const known = SOLANA_PROGRAM_ERRORS[errorCode];
+      if (known) {
+        userMessage = known.message;
+      }
+    }
+
+    // Also try the structured error if available (SendTransactionError)
+    if (error.transactionError) {
+      const parsed = parseSolanaError(error.transactionError);
+      if (parsed && parsed.code !== 'unknown_error') {
+        userMessage = parsed.message;
+      }
+    }
+
+    res.status(500).json({ success: false, error: userMessage });
+  }
+});
+
+/**
+ * PATCH /api/developer/webhooks/:webhookId
+ * Update a webhook
+ */
+portalRouter.patch('/webhooks/:webhookId', authenticate, async (req, res) => {
+  try {
+    const { webhookId } = req.params;
+    const { url, events, isActive, description } = req.body;
+
+    // Verify ownership
+    const hookResult = await pool.query(
+      `SELECT dw.id FROM developer_webhooks dw
+       JOIN developer_apps da ON dw.app_id = da.id
+       JOIN developer_accounts dac ON da.developer_id = dac.id
+       WHERE dw.id = $1 AND dac.wallet_address = $2`,
+      [webhookId, req.user.walletAddress]
+    );
+    if (hookResult.rows.length === 0) {
+      return res.status(404).json({ success: false, error: 'Webhook not found' });
+    }
+
+    if (events) {
+      const invalid = events.filter(e => !ALLOWED_WEBHOOK_EVENTS.includes(e));
+      if (invalid.length > 0) {
+        return res.status(400).json({ success: false, error: `Invalid events: ${invalid.join(', ')}` });
+      }
+    }
+
+    if (url) {
+      try {
+        const parsed = new URL(url);
+        if (parsed.protocol !== 'https:' && parsed.hostname !== 'localhost' && parsed.hostname !== '127.0.0.1') {
+          return res.status(400).json({ success: false, error: 'Webhook URL must use HTTPS' });
+        }
+      } catch {
+        return res.status(400).json({ success: false, error: 'Invalid URL' });
+      }
+    }
+
+    const updates = [];
+    const params = [];
+    if (url !== undefined) { params.push(url); updates.push(`url = $${params.length}`); }
+    if (events !== undefined) { params.push(events); updates.push(`events = $${params.length}`); }
+    if (isActive !== undefined) { params.push(isActive); updates.push(`is_active = $${params.length}`); }
+    if (description !== undefined) { params.push(description); updates.push(`description = $${params.length}`); }
+
+    if (updates.length === 0) {
+      return res.status(400).json({ success: false, error: 'No fields to update' });
+    }
+
+    updates.push('updated_at = NOW()');
+    params.push(webhookId);
+
+    const result = await pool.query(
+      `UPDATE developer_webhooks SET ${updates.join(', ')} WHERE id = $${params.length}
+       RETURNING id, url, events, is_active, description, updated_at`,
+      params
+    );
+
+    const w = result.rows[0];
+    res.json({
+      success: true,
+      webhook: {
+        id: w.id,
+        url: w.url,
+        events: w.events,
+        isActive: w.is_active,
+        description: w.description,
+        updatedAt: w.updated_at,
+      },
+    });
+  } catch (error) {
+    console.error('[Developer] Error updating webhook:', error.message);
+    res.status(500).json({ success: false, error: 'Failed to update webhook' });
+  }
+});
+
+/**
+ * DELETE /api/developer/webhooks/:webhookId
+ * Delete a webhook (cascade removes logs)
+ */
+portalRouter.delete('/webhooks/:webhookId', authenticate, async (req, res) => {
+  try {
+    const { webhookId } = req.params;
+
+    // Verify ownership
+    const hookResult = await pool.query(
+      `SELECT dw.id FROM developer_webhooks dw
+       JOIN developer_apps da ON dw.app_id = da.id
+       JOIN developer_accounts dac ON da.developer_id = dac.id
+       WHERE dw.id = $1 AND dac.wallet_address = $2`,
+      [webhookId, req.user.walletAddress]
+    );
+    if (hookResult.rows.length === 0) {
+      return res.status(404).json({ success: false, error: 'Webhook not found' });
+    }
+
+    await pool.query('DELETE FROM developer_webhooks WHERE id = $1', [webhookId]);
+
+    res.json({ success: true, message: 'Webhook deleted' });
+  } catch (error) {
+    console.error('[Developer] Error deleting webhook:', error.message);
+    res.status(500).json({ success: false, error: 'Failed to delete webhook' });
+  }
+});
+
+/**
+ * GET /api/developer/webhooks/:webhookId/logs
+ * Recent delivery logs for a webhook
+ */
+portalRouter.get('/webhooks/:webhookId/logs', authenticate, async (req, res) => {
+  try {
+    const { webhookId } = req.params;
+
+    // Verify ownership
+    const hookResult = await pool.query(
+      `SELECT dw.id FROM developer_webhooks dw
+       JOIN developer_apps da ON dw.app_id = da.id
+       JOIN developer_accounts dac ON da.developer_id = dac.id
+       WHERE dw.id = $1 AND dac.wallet_address = $2`,
+      [webhookId, req.user.walletAddress]
+    );
+    if (hookResult.rows.length === 0) {
+      return res.status(404).json({ success: false, error: 'Webhook not found' });
+    }
+
+    const result = await pool.query(
+      `SELECT id, event, status_code, attempts, success, error, created_at
+       FROM developer_webhook_logs
+       WHERE webhook_id = $1
+       ORDER BY created_at DESC
+       LIMIT 50`,
+      [webhookId]
+    );
+
+    res.json({
+      success: true,
+      logs: result.rows.map(l => ({
+        id: l.id,
+        event: l.event,
+        statusCode: l.status_code,
+        attempts: l.attempts,
+        success: l.success,
+        error: l.error,
+        createdAt: l.created_at,
+      })),
+    });
+  } catch (error) {
+    console.error('[Developer] Error fetching webhook logs:', error.message);
+    res.status(500).json({ success: false, error: 'Failed to fetch webhook logs' });
+  }
+});
+
+// ============================================================
+// PUBLIC API ROUTES — API key auth (third-party developer usage)
+// ============================================================
+
+// All routes here require apiKeyAuth middleware
+apiRouter.use(apiKeyAuth);
+
+// Logging middleware — track all API calls
+apiRouter.use((req, res, next) => {
+  const start = Date.now();
+  res.on('finish', () => {
+    logApiCall(req, res.statusCode, Date.now() - start);
+  });
+  next();
+});
+
+// ============================================================
+// USER AUTH ROUTES — API key + optional user JWT
+// ============================================================
+
+/**
+ * UPSERT into developer_app_users junction table.
+ * Tracks which users authenticated through which developer app.
+ */
+async function trackAppUser(appId, userId, deviceInfo = null) {
+  await pool.query(`
+    INSERT INTO developer_app_users (developer_app_id, user_id, first_seen_at, last_seen_at, device_info)
+    VALUES ($1, $2, NOW(), NOW(), $3)
+    ON CONFLICT (developer_app_id, user_id)
+    DO UPDATE SET last_seen_at = NOW(), device_info = COALESCE($3, developer_app_users.device_info)
+  `, [appId, userId, deviceInfo ? JSON.stringify(deviceInfo) : null]);
+}
+
+/**
+ * Generate an 8-char referral code (same algorithm as authRoutes.js).
+ * Excludes confusing chars: 0, O, I, 1.
+ */
+async function generateUniqueReferralCode() {
+  const chars = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
+  const maxAttempts = 10;
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    let code = '';
+    for (let i = 0; i < 8; i++) {
+      code += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+    const existing = await pool.query('SELECT id FROM users WHERE my_referral_code = $1', [code]);
+    if (existing.rows.length === 0) return code;
+  }
+
+  return null;
+}
+
+/**
+ * POST /api/developer/v1/auth/nonce
+ * Generate a nonce for wallet signature verification.
+ * Requires: API key only
+ */
+apiRouter.post('/auth/nonce', async (req, res) => {
+  try {
+    const { walletAddress } = req.body;
+
+    if (!walletAddress) {
+      return apiError(res, 400, 'invalid_request', 'walletAddress is required');
+    }
+
+    // Validate wallet format
+    try {
+      new PublicKey(walletAddress);
+    } catch {
+      return apiError(res, 400, 'invalid_wallet', 'Invalid Solana wallet address');
+    }
+
+    const nonce = crypto.randomBytes(32).toString('hex');
+
+    await pool.query(
+      `INSERT INTO auth_nonces (wallet_address, nonce, expires_at, used)
+       VALUES ($1, $2, NOW() + INTERVAL '5 minutes', false)
+       ON CONFLICT (wallet_address)
+       DO UPDATE SET nonce = $2, expires_at = NOW() + INTERVAL '5 minutes', used = false`,
+      [walletAddress, nonce]
+    );
+
+    const message = `Sign in to ${req.developerApp.appName} via Dubs\nNonce: ${nonce}`;
+
+    res.json({
+      success: true,
+      data: { nonce, message },
+    });
+  } catch (error) {
+    console.error('[DevAPI] Error generating nonce:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to generate nonce');
+  }
+});
+
+/**
+ * POST /api/developer/v1/auth/authenticate
+ * Verify wallet signature. Returns JWT+profile for existing users, or needsRegistration for new wallets.
+ * Requires: API key only
+ */
+apiRouter.post('/auth/authenticate', async (req, res) => {
+  try {
+    const { walletAddress, signature, nonce, deviceInfo } = req.body;
+
+    if (!walletAddress || !signature || !nonce) {
+      return apiError(res, 400, 'invalid_request', 'walletAddress, signature, and nonce are required');
+    }
+
+    // Validate nonce
+    const nonceResult = await pool.query(
+      'SELECT * FROM auth_nonces WHERE wallet_address = $1 AND nonce = $2 AND used = false AND expires_at > NOW()',
+      [walletAddress, nonce]
+    );
+
+    if (nonceResult.rows.length === 0) {
+      return apiError(res, 400, 'invalid_nonce', 'Invalid or expired nonce');
+    }
+
+    // Reconstruct message from nonce + appName (never trust client message)
+    const message = `Sign in to ${req.developerApp.appName} via Dubs\nNonce: ${nonce}`;
+    const messageBytes = new TextEncoder().encode(message);
+    const signatureBytes = bs58.decode(signature);
+    const publicKeyBytes = new PublicKey(walletAddress).toBytes();
+
+    const valid = nacl.sign.detached.verify(messageBytes, signatureBytes, publicKeyBytes);
+
+    if (!valid) {
+      return apiError(res, 401, 'invalid_signature', 'Signature verification failed');
+    }
+
+    // Check if user exists
+    const userResult = await pool.query(
+      'SELECT * FROM users WHERE wallet_address = $1',
+      [walletAddress]
+    );
+
+    if (userResult.rows.length === 0) {
+      // New wallet — do NOT mark nonce as used (register will consume it)
+      return res.json({
+        success: true,
+        data: { needsRegistration: true },
+      });
+    }
+
+    // Existing user — mark nonce as used
+    await pool.query(
+      'UPDATE auth_nonces SET used = true WHERE wallet_address = $1 AND nonce = $2',
+      [walletAddress, nonce]
+    );
+
+    const user = userResult.rows[0];
+    const token = generateToken(walletAddress, user.id);
+    const expiresAt = new Date(Date.now() + parseDuration(JWT_EXPIRES_IN));
+    await createSession(walletAddress, user.id, token, expiresAt);
+
+    // Track app-user relationship
+    await trackAppUser(req.developerApp.appId, user.id, deviceInfo);
+
+    res.json({
+      success: true,
+      data: {
+        needsRegistration: false,
+        user: {
+          walletAddress: user.wallet_address,
+          username: user.username,
+          avatar: user.avatar,
+          myReferralCode: user.my_referral_code,
+          onboardingComplete: user.onboarding_complete,
+          createdAt: user.created_at,
+        },
+        token,
+      },
+    });
+  } catch (error) {
+    console.error('[DevAPI] Error authenticating:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to authenticate');
+  }
+});
+
+/**
+ * POST /api/developer/v1/auth/register
+ * Register a new user with wallet + username. Requires valid nonce+signature.
+ * Requires: API key only
+ */
+apiRouter.post('/auth/register', async (req, res) => {
+  try {
+    const { walletAddress, signature, nonce, username, referralCode, avatarUrl, deviceInfo } = req.body;
+
+    if (!walletAddress || !signature || !nonce || !username) {
+      return apiError(res, 400, 'invalid_request', 'walletAddress, signature, nonce, and username are required');
+    }
+
+    // Validate nonce
+    const nonceResult = await pool.query(
+      'SELECT * FROM auth_nonces WHERE wallet_address = $1 AND nonce = $2 AND used = false AND expires_at > NOW()',
+      [walletAddress, nonce]
+    );
+
+    if (nonceResult.rows.length === 0) {
+      return apiError(res, 400, 'invalid_nonce', 'Invalid or expired nonce');
+    }
+
+    // Verify signature
+    const message = `Sign in to ${req.developerApp.appName} via Dubs\nNonce: ${nonce}`;
+    const messageBytes = new TextEncoder().encode(message);
+    const signatureBytes = bs58.decode(signature);
+    const publicKeyBytes = new PublicKey(walletAddress).toBytes();
+
+    const valid = nacl.sign.detached.verify(messageBytes, signatureBytes, publicKeyBytes);
+
+    if (!valid) {
+      return apiError(res, 401, 'invalid_signature', 'Signature verification failed');
+    }
+
+    // Check wallet not already registered
+    const existingWallet = await pool.query('SELECT id FROM users WHERE wallet_address = $1', [walletAddress]);
+    if (existingWallet.rows.length > 0) {
+      return apiError(res, 409, 'already_registered', 'This wallet is already registered');
+    }
+
+    // Username validation: 3-20 chars, alphanumeric + underscores
+    if (username.length < 3) {
+      return apiError(res, 400, 'invalid_username', 'Username must be at least 3 characters');
+    }
+    if (username.length > 20) {
+      return apiError(res, 400, 'invalid_username', 'Username must be 20 characters or less');
+    }
+    if (!/^[a-zA-Z0-9_]+$/.test(username)) {
+      return apiError(res, 400, 'invalid_username', 'Username can only contain letters, numbers, and underscores');
+    }
+
+    // Case-insensitive uniqueness check
+    const existingUsername = await pool.query(
+      'SELECT id FROM users WHERE LOWER(username) = LOWER($1)',
+      [username]
+    );
+    if (existingUsername.rows.length > 0) {
+      return apiError(res, 409, 'username_taken', 'Username is already taken');
+    }
+
+    // Mark nonce as used
+    await pool.query(
+      'UPDATE auth_nonces SET used = true WHERE wallet_address = $1 AND nonce = $2',
+      [walletAddress, nonce]
+    );
+
+    // Insert user
+    const insertResult = await pool.query(
+      `INSERT INTO users (wallet_address, username, avatar, referral_code, created_at, onboarding_complete)
+       VALUES ($1, $2, $3, $4, NOW(), false)
+       RETURNING *`,
+      [walletAddress, username, avatarUrl || null, referralCode || null]
+    );
+
+    let user = insertResult.rows[0];
+
+    // Generate referral code (same algo as authRoutes.js)
+    const myReferralCode = await generateUniqueReferralCode();
+    if (myReferralCode) {
+      const updateResult = await pool.query(
+        'UPDATE users SET my_referral_code = $1 WHERE id = $2 RETURNING *',
+        [myReferralCode, user.id]
+      );
+      user = updateResult.rows[0];
+    }
+
+    // Generate JWT + create session
+    const token = generateToken(walletAddress, user.id);
+    const expiresAt = new Date(Date.now() + parseDuration(JWT_EXPIRES_IN));
+    await createSession(walletAddress, user.id, token, expiresAt);
+
+    // Track app-user relationship
+    await trackAppUser(req.developerApp.appId, user.id, deviceInfo);
+
+    console.log(`[DevAPI] New user registered: ${username} (${walletAddress}) via app ${req.developerApp.appName}`);
+
+    res.json({
+      success: true,
+      data: {
+        user: {
+          walletAddress: user.wallet_address,
+          username: user.username,
+          avatar: user.avatar,
+          myReferralCode: user.my_referral_code,
+          onboardingComplete: user.onboarding_complete,
+          createdAt: user.created_at,
+        },
+        token,
+      },
+    });
+  } catch (error) {
+    console.error('[DevAPI] Error registering user:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to register user');
+  }
+});
+
+/**
+ * GET /api/developer/v1/auth/me
+ * Get the authenticated user's profile.
+ * Requires: API key + user JWT (dual auth)
+ */
+apiRouter.get('/auth/me', developerUserAuth, async (req, res) => {
+  try {
+    const userResult = await pool.query(
+      'SELECT * FROM users WHERE wallet_address = $1',
+      [req.developerUser.walletAddress]
+    );
+
+    if (userResult.rows.length === 0) {
+      return apiError(res, 404, 'user_not_found', 'User not found');
+    }
+
+    const user = userResult.rows[0];
+
+    res.json({
+      success: true,
+      data: {
+        user: {
+          walletAddress: user.wallet_address,
+          username: user.username,
+          avatar: user.avatar,
+          myReferralCode: user.my_referral_code,
+          onboardingComplete: user.onboarding_complete,
+          createdAt: user.created_at,
+        },
+      },
+    });
+  } catch (error) {
+    console.error('[DevAPI] Error fetching user profile:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to fetch user profile');
+  }
+});
+
+/**
+ * PATCH /api/developer/v1/auth/profile
+ * Update the authenticated user's profile (e.g. avatar).
+ * Requires: API key + user JWT (dual auth)
+ */
+apiRouter.patch('/auth/profile', developerUserAuth, async (req, res) => {
+  try {
+    const { avatar } = req.body;
+
+    if (avatar !== undefined && typeof avatar !== 'string') {
+      return apiError(res, 400, 'invalid_request', 'avatar must be a string URL');
+    }
+
+    const result = await pool.query(
+      `UPDATE users
+       SET avatar = COALESCE($2, avatar),
+           updated_at = NOW()
+       WHERE id = $1
+       RETURNING wallet_address, username, avatar, created_at`,
+      [req.developerUser.userId, avatar]
+    );
+
+    if (result.rows.length === 0) {
+      return apiError(res, 404, 'user_not_found', 'User not found');
+    }
+
+    const user = result.rows[0];
+    res.json({
+      success: true,
+      data: {
+        user: {
+          walletAddress: user.wallet_address,
+          username: user.username,
+          avatar: user.avatar,
+          createdAt: user.created_at,
+        },
+      },
+    });
+  } catch (error) {
+    console.error('[DevAPI] Error updating user profile:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to update user profile');
+  }
+});
+
+/**
+ * POST /api/developer/v1/auth/logout
+ * Log out the authenticated user (delete session).
+ * Requires: API key + user JWT (dual auth)
+ */
+apiRouter.post('/auth/logout', developerUserAuth, async (req, res) => {
+  try {
+    const authHeader = req.headers.authorization;
+    const token = authHeader.substring(7);
+
+    await deleteSession(req.developerUser.walletAddress, token);
+
+    res.json({
+      success: true,
+      data: { message: 'Logged out successfully' },
+    });
+  } catch (error) {
+    console.error('[DevAPI] Error logging out:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to log out');
+  }
+});
+
+// ── Push Notification Endpoints ──
+
+/**
+ * POST /api/developer/v1/push/expo-token
+ * Register an Expo push token for the authenticated user.
+ * Requires: API key + user JWT (dual auth)
+ */
+apiRouter.post('/push/expo-token', developerUserAuth, async (req, res) => {
+  try {
+    const { token, platform, deviceName } = req.body;
+    if (!token || !platform) {
+      return apiError(res, 400, 'missing_params', 'token and platform are required');
+    }
+
+    const appId = req.developerApp.appId;
+    const userId = req.developerUser.userId;
+
+    const result = await expoPushService.registerToken(userId, token, platform, deviceName, appId);
+
+    res.json({
+      success: true,
+      data: { tokenId: result.id, token: result.token },
+    });
+  } catch (error) {
+    console.error('[DevAPI] Error registering push token:', error.message);
+    apiError(res, 500, 'internal_error', error.message || 'Failed to register push token');
+  }
+});
+
+/**
+ * DELETE /api/developer/v1/push/expo-token
+ * Unregister an Expo push token for the authenticated user.
+ * Requires: API key + user JWT (dual auth)
+ */
+apiRouter.delete('/push/expo-token', developerUserAuth, async (req, res) => {
+  try {
+    const { token } = req.body;
+    if (!token) {
+      return apiError(res, 400, 'missing_params', 'token is required');
+    }
+
+    await expoPushService.unregisterToken(req.developerUser.userId, token);
+
+    res.json({
+      success: true,
+      data: { message: 'Token unregistered' },
+    });
+  } catch (error) {
+    console.error('[DevAPI] Error unregistering push token:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to unregister push token');
+  }
+});
+
+/**
+ * POST /api/developer/v1/push/simulate
+ * Send a test push notification to a specific user.
+ * Requires: API key + user JWT (dual auth)
+ */
+apiRouter.post('/push/simulate', developerUserAuth, async (req, res) => {
+  try {
+    const { userId, title, body, data } = req.body;
+    if (!userId) {
+      return apiError(res, 400, 'missing_params', 'userId is required');
+    }
+
+    const result = await expoPushService.sendToUser(userId, {
+      title: title || 'Test Notification',
+      body: body || 'This is a test push from the Dubs developer dashboard',
+      data: data || { type: 'test' },
+    });
+
+    res.json({
+      success: true,
+      data: result,
+    });
+  } catch (error) {
+    console.error('[DevAPI] Error simulating push:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to send push notification');
+  }
+});
+
+/**
+ * GET /api/developer/v1/auth/check-username/:username
+ * Check if a username is available.
+ * Requires: API key only
+ */
+apiRouter.get('/auth/check-username/:username', async (req, res) => {
+  try {
+    const { username } = req.params;
+
+    // Validate format
+    if (!username || username.length < 3) {
+      return res.json({ success: true, data: { available: false, reason: 'Username must be at least 3 characters' } });
+    }
+    if (username.length > 20) {
+      return res.json({ success: true, data: { available: false, reason: 'Username must be 20 characters or less' } });
+    }
+    if (!/^[a-zA-Z0-9_]+$/.test(username)) {
+      return res.json({ success: true, data: { available: false, reason: 'Username can only contain letters, numbers, and underscores' } });
+    }
+
+    const result = await pool.query(
+      'SELECT id FROM users WHERE LOWER(username) = LOWER($1)',
+      [username]
+    );
+
+    res.json({
+      success: true,
+      data: { available: result.rows.length === 0 },
+    });
+  } catch (error) {
+    console.error('[DevAPI] Error checking username:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to check username');
+  }
+});
+
+/**
+ * GET /api/developer/v1/users/:walletAddress
+ * Public profile lookup (no JWT needed).
+ * Returns null if wallet not found (no 404).
+ * Requires: API key only
+ */
+apiRouter.get('/users/:walletAddress', async (req, res) => {
+  try {
+    const { walletAddress } = req.params;
+
+    const result = await pool.query(
+      'SELECT wallet_address, username, avatar, created_at FROM users WHERE wallet_address = $1',
+      [walletAddress]
+    );
+
+    if (result.rows.length === 0) {
+      return res.json({ success: true, data: { user: null } });
+    }
+
+    const user = result.rows[0];
+    res.json({
+      success: true,
+      data: {
+        user: {
+          walletAddress: user.wallet_address,
+          username: user.username,
+          avatar: user.avatar,
+          createdAt: user.created_at,
+        },
+      },
+    });
+  } catch (error) {
+    console.error('[DevAPI] Error fetching user:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to fetch user');
+  }
+});
+
+/**
+ * GET /api/developer/v1/users
+ * List users who have authenticated through this developer's app.
+ * Paginated with limit/offset.
+ * Requires: API key only
+ */
+apiRouter.get('/users', async (req, res) => {
+  try {
+    const { appId } = req.developerApp;
+    const limit = Math.min(100, Math.max(1, parseInt(req.query.limit) || 20));
+    const offset = Math.max(0, parseInt(req.query.offset) || 0);
+
+    const countResult = await pool.query(
+      'SELECT COUNT(*) FROM developer_app_users WHERE developer_app_id = $1',
+      [appId]
+    );
+    const total = parseInt(countResult.rows[0].count);
+
+    const result = await pool.query(`
+      SELECT
+        u.wallet_address,
+        u.username,
+        u.avatar,
+        u.created_at,
+        dau.first_seen_at,
+        dau.last_seen_at
+      FROM developer_app_users dau
+      JOIN users u ON dau.user_id = u.id
+      WHERE dau.developer_app_id = $1
+      ORDER BY dau.last_seen_at DESC
+      LIMIT $2 OFFSET $3
+    `, [appId, limit, offset]);
+
+    res.json({
+      success: true,
+      data: {
+        users: result.rows.map(u => ({
+          walletAddress: u.wallet_address,
+          username: u.username,
+          avatar: u.avatar,
+          createdAt: u.created_at,
+          firstSeenAt: u.first_seen_at,
+          lastSeenAt: u.last_seen_at,
+        })),
+        pagination: { total, limit, offset },
+      },
+    });
+  } catch (error) {
+    console.error('[DevAPI] Error listing app users:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to list users');
+  }
+});
+
+/**
+ * Parse a duration string like '7d', '24h', '30m' into milliseconds.
+ */
+function parseDuration(str) {
+  const match = str.match(/^(\d+)([dhms])$/);
+  if (!match) return 7 * 24 * 60 * 60 * 1000; // default 7 days
+  const val = parseInt(match[1]);
+  switch (match[2]) {
+    case 'd': return val * 24 * 60 * 60 * 1000;
+    case 'h': return val * 60 * 60 * 1000;
+    case 'm': return val * 60 * 1000;
+    case 's': return val * 1000;
+    default: return 7 * 24 * 60 * 60 * 1000;
+  }
+}
+
+// ── Unified Events ──
+
+/**
+ * GET /api/developer/v1/events/upcoming
+ * Unified paginated endpoint for ALL upcoming bettable events (sports + esports).
+ *
+ * Query params:
+ *   type     - "sports" or "esports" (optional, returns both if omitted)
+ *   game     - NBA, UFC, cs-go, valorant, etc. (optional)
+ *   page     - Page number (default: 1)
+ *   per_page - Items per page (default: 20, max: 100)
+ */
+apiRouter.get('/events/upcoming', async (req, res) => {
+  try {
+    const typeFilter = req.query.type?.toLowerCase();
+    const gameFilter = req.query.game?.toLowerCase();
+    const page = Math.max(1, parseInt(req.query.page) || 1);
+    const perPage = Math.min(100, Math.max(1, parseInt(req.query.per_page) || 20));
+
+    if (typeFilter && !['sports', 'esports'].includes(typeFilter)) {
+      return apiError(res, 400, 'invalid_request', 'type must be "sports" or "esports"');
+    }
+
+    if (gameFilter && !GAME_PARAM_MAP[gameFilter]) {
+      return apiError(res, 400, 'invalid_request', `Unknown game "${req.query.game}". Valid: ${Object.keys(GAME_PARAM_MAP).join(', ')}`);
+    }
+
+    // Determine which sources to fetch
+    let sportsLeagues = [];
+    let esportsVideogames = [];
+
+    if (gameFilter) {
+      const mapping = GAME_PARAM_MAP[gameFilter];
+      if (mapping.type === 'sports') sportsLeagues = [mapping.league];
+      else esportsVideogames = [mapping.videogame];
+    } else {
+      if (!typeFilter || typeFilter === 'sports') sportsLeagues = ALL_SPORTS_LEAGUES;
+      if (!typeFilter || typeFilter === 'esports') esportsVideogames = ALL_ESPORTS_VIDEOGAMES;
+    }
+
+    // Respect type filter even when game is set
+    if (typeFilter === 'sports') esportsVideogames = [];
+    if (typeFilter === 'esports') sportsLeagues = [];
+
+    // Fetch all sources in parallel
+    const fetches = [];
+    for (const league of sportsLeagues) {
+      fetches.push(fetchSportsEvents(league).then(events => events.map(e => normalizeToUnifiedSportsEvent(e, league))));
+    }
+    for (const vg of esportsVideogames) {
+      fetches.push(fetchEsportsMatches(vg).then(matches => matches.map(m => normalizeToUnifiedEsportsEvent(m))));
+    }
+
+    const results = await Promise.all(fetches);
+    let allEvents = results.flat();
+
+    // Only bettable events — exclude finished, canceled, and past-start-time
+    const now = new Date();
+    allEvents = allEvents.filter(e => {
+      if (e.status !== 'upcoming' && e.status !== 'live') return false;
+      // Exclude events whose start time has already passed (upstream API can be slow to update status)
+      if (e.startTime && new Date(e.startTime) < now) return false;
+      return true;
+    });
+
+    // Sort by startTime ascending
+    allEvents.sort((a, b) => {
+      const da = a.startTime ? new Date(a.startTime).getTime() : Infinity;
+      const db = b.startTime ? new Date(b.startTime).getTime() : Infinity;
+      return da - db;
+    });
+
+    // Paginate
+    const total = allEvents.length;
+    const totalPages = Math.ceil(total / perPage);
+    const events = allEvents.slice((page - 1) * perPage, page * perPage);
+
+    res.json({ success: true, events, pagination: { page, perPage, total, totalPages } });
+  } catch (error) {
+    console.error('[DevAPI] Error in unified events endpoint:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to fetch events');
+  }
+});
+
+// ── Type-Specific Data (also normalized) ──
+
+/**
+ * GET /api/developer/v1/sports/events/:league
+ * Upcoming sports events for a single league (normalized shape)
+ */
+apiRouter.get('/sports/events/:league', async (req, res) => {
+  try {
+    const { league } = req.params;
+    const rawEvents = await fetchSportsEvents(league);
+    const events = rawEvents.map(e => normalizeToUnifiedSportsEvent(e, league.toUpperCase()));
+    res.json({ success: true, league, events });
+  } catch (error) {
+    console.error('[DevAPI] Error fetching sports events:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to fetch sports events');
+  }
+});
+
+/**
+ * GET /api/developer/v1/esports/matches/upcoming
+ * Upcoming esports matches (normalized shape)
+ */
+apiRouter.get('/esports/matches/upcoming', async (req, res) => {
+  try {
+    const rawMatches = await fetchEsportsMatches(req.query.videogame || null);
+    const matches = rawMatches.map(m => normalizeToUnifiedEsportsEvent(m));
+    res.json({ success: true, matches });
+  } catch (error) {
+    console.error('[DevAPI] Error fetching esports matches:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to fetch esports matches');
+  }
+});
+
+/**
+ * GET /api/developer/v1/esports/matches/:matchId
+ * Single esports match detail (detailed shape, not unified)
+ */
+apiRouter.get('/esports/matches/:matchId', async (req, res) => {
+  try {
+    const response = await axios.get(`${BASE_URL_INTERNAL}/api/esports/matches/${req.params.matchId}`, { timeout: 15000 });
+    const rawMatch = response.data?.data || response.data;
+    const match = transformEsportsMatchDetail(rawMatch);
+    res.json({ success: true, match });
+  } catch (error) {
+    console.error('[DevAPI] Error fetching esports match:', error.message);
+    const status = error.response?.status || 500;
+    apiError(res, status, status === 404 ? 'match_not_found' : 'internal_error', 'Failed to fetch esports match');
+  }
+});
+
+// ── Shared: Event ID Resolution ──
+
+/**
+ * Server-side stash for event data between create → confirm.
+ * Keyed by gameId, auto-expires after 10 minutes.
+ * This keeps raw provider data (sportsEvent, gameMode) off the public API.
+ */
+const pendingGameEvents = new Map();
+const STASH_TTL_MS = 10 * 60 * 1000;
+
+function stashEventData(gameId, data) {
+  pendingGameEvents.set(gameId, { ...data, _createdAt: Date.now() });
+  // Lazy cleanup: purge expired entries
+  for (const [key, val] of pendingGameEvents) {
+    if (Date.now() - val._createdAt > STASH_TTL_MS) pendingGameEvents.delete(key);
+  }
+}
+
+function popEventData(gameId) {
+  const data = pendingGameEvents.get(gameId);
+  pendingGameEvents.delete(gameId);
+  return data || null;
+}
+
+/**
+ * Error helper — consistent error shape across all endpoints.
+ * @param {object} res - Express response
+ * @param {number} httpStatus - HTTP status code
+ * @param {string} code - Machine-readable error code
+ * @param {string} message - Human-readable message
+ */
+function apiError(res, httpStatus, code, message) {
+  return res.status(httpStatus).json({ success: false, error: { code, message } });
+}
+
+// ============================================================
+// SOLANA PROGRAM ERROR MAP
+// ============================================================
+// Custom error codes from dubs_solana_program (starts at 6000)
+const SOLANA_PROGRAM_ERRORS = {
+  6000: { code: 'invalid_amount', message: 'Amount must be greater than 0' },
+  6001: { code: 'invalid_max_players', message: 'Max players must be between 1 and 20' },
+  6002: { code: 'game_not_active', message: 'Game is not active' },
+  6003: { code: 'game_full', message: 'Game is full' },
+  6004: { code: 'player_already_joined', message: 'Player has already joined this game' },
+  6005: { code: 'insufficient_funds', message: 'Insufficient funds in pot' },
+  6006: { code: 'unauthorized', message: 'Only the game creator can perform this action' },
+  6007: { code: 'invalid_winner_index', message: 'Invalid winner index' },
+  6008: { code: 'game_still_active', message: 'Game is still active — must close before resetting' },
+  6009: { code: 'pot_not_empty', message: 'Pot must be empty before resetting — distribute winnings first' },
+  6010: { code: 'no_winners_specified', message: 'At least one winner must be specified' },
+  6011: { code: 'mismatched_winners_percentages', message: 'Number of winners must match number of percentages' },
+  6012: { code: 'percentages_invalid', message: 'Percentages must sum to exactly 100' },
+  6013: { code: 'winner_account_mismatch', message: 'Winner account does not match expected player' },
+  6014: { code: 'invalid_operator_fee', message: 'Operator fee must be between 0 and 100' },
+  6015: { code: 'operator_wallet_mismatch', message: 'Operator wallet does not match game settings' },
+  6016: { code: 'winner_not_in_game', message: 'Winner address is not a player in this game' },
+  6017: { code: 'voting_not_enabled', message: 'Voting is not enabled for this game' },
+  6018: { code: 'voter_not_in_game', message: 'Voter is not a player in this game' },
+  6019: { code: 'voted_for_not_in_game', message: 'Cannot vote for someone who is not in the game' },
+  6020: { code: 'voting_incomplete', message: 'Voting incomplete — need majority of players to vote' },
+  6021: { code: 'invalid_referee_commission', message: 'Referee commission must be between 0 and 100' },
+  6022: { code: 'total_fees_exceed_100', message: 'Total fees (operator + referee) cannot exceed 100%' },
+  6023: { code: 'referee_mode_requires_referee', message: 'Referee mode requires a referee address' },
+  6024: { code: 'referee_must_earn_commission', message: 'Referee must earn commission' },
+  6025: { code: 'referee_cannot_be_player', message: 'Referee cannot join as a player (conflict of interest)' },
+  6026: { code: 'only_referee_can_vote', message: 'Only the referee can vote in Referee mode' },
+  6027: { code: 'referee_account_mismatch', message: 'Referee account does not match game settings' },
+  6028: { code: 'invalid_lock_time', message: 'Lock time must be in the future' },
+  6029: { code: 'game_locked', message: 'Game is locked — no more players can join' },
+  6030: { code: 'lock_time_passed', message: 'Lock time has passed — game is now locked' },
+  6031: { code: 'unauthorized_oracle', message: 'Only authorized oracle can resolve this game' },
+  6032: { code: 'game_not_locked', message: 'Game must be locked before it can be resolved' },
+  6033: { code: 'already_resolved', message: 'Game has already been resolved' },
+  6034: { code: 'game_not_resolved', message: 'Game has not been resolved yet' },
+  6035: { code: 'player_not_in_game', message: 'Player is not in this game' },
+  6036: { code: 'not_a_winner', message: 'Player did not win this game' },
+  6037: { code: 'invalid_game_mode', message: 'Invalid game mode for this operation' },
+  6038: { code: 'already_claimed', message: 'Player has already claimed their winnings' },
+  6039: { code: 'lock_time_too_soon', message: 'Lock time must be at least 2 minutes in the future' },
+  6040: { code: 'operator_account_missing', message: 'Operator account must be provided' },
+  6041: { code: 'no_winners_to_distribute', message: 'No winners to distribute funds to' },
+  6042: { code: 'insufficient_funds_for_rent', message: 'Insufficient funds to maintain rent exemption' },
+  6043: { code: 'cannot_resolve_before_lock', message: 'Cannot resolve game before lock time has passed' },
+  6044: { code: 'emergency_refund_not_available', message: 'Emergency refund not available yet — must wait 7 days after lock time' },
+  6045: { code: 'sponsor_account_missing', message: 'Sponsor account must be provided for tie refund' },
+  6046: { code: 'sponsor_wallet_mismatch', message: 'Sponsor wallet does not match stored sponsor' },
+  6047: { code: 'invalid_bet_amount', message: 'Bet amount must be greater than zero' },
+  6048: { code: 'no_survivors_to_distribute', message: 'No survivors to distribute winnings to' },
+  6049: { code: 'too_many_survivors', message: 'Too many survivors (max 50 per batch)' },
+};
+
+// Known Solana built-in instruction errors
+const SOLANA_BUILTIN_ERRORS = {
+  0: { code: 'generic_error', message: 'Generic instruction error' },
+  1: { code: 'invalid_argument', message: 'Invalid argument passed to program' },
+  2: { code: 'invalid_instruction_data', message: 'Invalid instruction data' },
+  3: { code: 'invalid_account_data', message: 'Invalid account data' },
+  4: { code: 'account_data_too_small', message: 'Account data too small' },
+  5: { code: 'insufficient_funds', message: 'Insufficient funds for transaction' },
+  6: { code: 'incorrect_program_id', message: 'Incorrect program ID' },
+  7: { code: 'missing_required_signature', message: 'Missing required signature' },
+  8: { code: 'account_already_initialized', message: 'Account already initialized' },
+  9: { code: 'uninitialized_account', message: 'Attempt to operate on uninitialized account' },
+};
+
+/**
+ * Parse a raw Solana transaction error into a normalized { code, message } object.
+ * Handles: { InstructionError: [idx, { Custom: N }] }
+ *          { InstructionError: [idx, "SomeBuiltinError"] }
+ *          String errors, etc.
+ */
+function parseSolanaError(err) {
+  if (!err) return { code: 'unknown_error', message: 'Unknown transaction error' };
+
+  // Handle string input (from pollTransactionConfirmation)
+  if (typeof err === 'string') {
+    try {
+      // Try to extract JSON from "Transaction failed: {...}"
+      const jsonMatch = err.match(/\{.*\}/s);
+      if (jsonMatch) err = JSON.parse(jsonMatch[0]);
+      else return { code: 'transaction_failed', message: err };
+    } catch {
+      return { code: 'transaction_failed', message: err };
+    }
+  }
+
+  // { InstructionError: [index, details] }
+  if (err.InstructionError) {
+    const [ixIndex, details] = err.InstructionError;
+
+    // { Custom: 6004 }
+    if (details && typeof details === 'object' && details.Custom != null) {
+      const customCode = details.Custom;
+      const known = SOLANA_PROGRAM_ERRORS[customCode];
+      if (known) return known;
+      return { code: `program_error_${customCode}`, message: `Program error code ${customCode} (instruction ${ixIndex})` };
+    }
+
+    // Built-in enum like "InsufficientFundsForRent" or numeric
+    if (typeof details === 'string') {
+      const snake = details.replace(/([a-z])([A-Z])/g, '$1_$2').toLowerCase();
+      return { code: snake, message: details.replace(/([a-z])([A-Z])/g, '$1 $2') };
+    }
+    if (typeof details === 'number') {
+      const known = SOLANA_BUILTIN_ERRORS[details];
+      if (known) return known;
+      return { code: `instruction_error_${details}`, message: `Instruction error ${details}` };
+    }
+
+    return { code: 'instruction_error', message: `Instruction ${ixIndex} failed: ${JSON.stringify(details)}` };
+  }
+
+  return { code: 'transaction_failed', message: typeof err === 'object' ? JSON.stringify(err) : String(err) };
+}
+
+/**
+ * Simulate a base64-encoded transaction against the RPC.
+ * If simulation reveals an on-chain error, sends apiError and returns false.
+ * If simulation passes (or RPC is unreachable), returns true to continue.
+ */
+async function simulateTransactionOrFail(base64Tx, res, label) {
+  try {
+    const tx = Transaction.from(Buffer.from(base64Tx, 'base64'));
+    const simResult = await connection.simulateTransaction(tx);
+    if (simResult.value.err) {
+      console.error(`[DevAPI] ${label} simulation failed:`, JSON.stringify(simResult.value.err));
+      const parsed = parseSolanaError(simResult.value.err);
+      apiError(res, 400, parsed.code, parsed.message);
+      return false;
+    }
+    return true;
+  } catch (simError) {
+    console.warn(`[DevAPI] ${label} simulation RPC error (non-blocking):`, simError.message);
+    return true;
+  }
+}
+
+// ============================================================
+// WEBHOOK DELIVERY
+// ============================================================
+
+const ALLOWED_WEBHOOK_EVENTS = ['game.created', 'game.joined', 'game.resolved'];
+
+/**
+ * Fire webhooks for a developer app event.
+ * Non-blocking — errors are logged, never thrown to the caller.
+ * Signs payload with HMAC-SHA256 using the webhook's secret.
+ */
+async function fireWebhooks(appId, event, payload) {
+  try {
+    const { rows: hooks } = await pool.query(
+      `SELECT id, url, secret FROM developer_webhooks
+       WHERE app_id = $1 AND is_active = TRUE AND $2 = ANY(events)`,
+      [appId, event]
+    );
+    if (hooks.length === 0) return;
+
+    const body = JSON.stringify({ event, timestamp: new Date().toISOString(), data: payload });
+
+    for (const hook of hooks) {
+      const sig = crypto.createHmac('sha256', hook.secret).update(body).digest('hex');
+      deliverWebhook(hook, event, body, sig, 1);
+    }
+
+    console.log(`[Webhooks] Fired ${event} to ${hooks.length} hook(s) for app ${appId}`);
+  } catch (err) {
+    console.error(`[Webhooks] Failed to query webhooks for app ${appId}:`, err.message);
+  }
+}
+
+async function deliverWebhook(hook, event, body, signature, attempt) {
+  const MAX_ATTEMPTS = 3;
+  try {
+    const res = await axios.post(hook.url, body, {
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Dubs-Signature': signature,
+        'X-Dubs-Event': event,
+      },
+      timeout: 10000,
+    });
+
+    await pool.query(
+      `INSERT INTO developer_webhook_logs (webhook_id, event, payload, status_code, response_body, attempts, success)
+       VALUES ($1, $2, $3, $4, $5, $6, TRUE)`,
+      [hook.id, event, body, res.status, String(res.data).slice(0, 500), attempt]
+    ).catch(() => {});
+  } catch (err) {
+    const statusCode = err.response?.status || null;
+    const errorMsg = err.message;
+
+    if (attempt < MAX_ATTEMPTS) {
+      setTimeout(() => deliverWebhook(hook, event, body, signature, attempt + 1), attempt * 2000);
+      return;
+    }
+
+    await pool.query(
+      `INSERT INTO developer_webhook_logs (webhook_id, event, payload, status_code, attempts, success, error)
+       VALUES ($1, $2, $3, $4, $5, FALSE, $6)`,
+      [hook.id, event, body, statusCode, attempt, errorMsg]
+    ).catch(() => {});
+    console.warn(`[Webhooks] Delivery failed for hook ${hook.id} after ${attempt} attempts: ${errorMsg}`);
+  }
+}
+
+// ============================================================
+// EVENT RESOLUTION
+// ============================================================
+
+/**
+ * Parse a namespaced event ID and resolve it to internal data.
+ * Sports ID format:  "sports:LEAGUE:EVENT_ID"  e.g. "sports:UFC:espn-ufc-600057329"
+ * Esports ID format: "esports:MATCH_ID"        e.g. "esports:1353988"
+ *
+ * Returns: { type, gameMode, sportsEvent, lockTimestamp, sportsEventId } or { error }
+ */
+async function resolveEventId(id) {
+  if (!id || typeof id !== 'string') {
+    return { error: { status: 400, code: 'invalid_request', message: 'id is required' } };
+  }
+
+  const colonIdx = id.indexOf(':');
+  if (colonIdx === -1) {
+    return { error: { status: 400, code: 'invalid_id_format', message: `Invalid id "${id}". Use "esports:MATCH_ID" or "sports:LEAGUE:EVENT_ID"` } };
+  }
+
+  const prefix = id.slice(0, colonIdx);
+  const rest = id.slice(colonIdx + 1);
+
+  // ── Esports ──
+  if (prefix === 'esports') {
+    try {
+      const response = await axios.post(`${BASE_URL_INTERNAL}/api/esports/games/validate`, {
+        pandascoreMatchId: rest,
+      }, { timeout: 15000 });
+
+      const data = response.data;
+      if (!data.success) {
+        return { error: { status: 400, code: 'event_not_bettable', message: data.error || 'Event is not bettable' } };
+      }
+
+      return {
+        type: 'esports',
+        gameMode: 5,
+        sportsEvent: data.sportsEvent,
+        lockTimestamp: data.match?.lockTimestamp,
+        sportsEventId: rest,
+        startTime: normalizeTimestamp(data.match?.scheduledAt),
+        status: normalizeEsportsStatus(data.match?.status),
+      };
+    } catch (err) {
+      const msg = err.response?.data?.error || 'Failed to validate esports event';
+      const status = err.response?.status || 500;
+      return { error: { status, code: status === 404 ? 'event_not_found' : 'event_not_bettable', message: msg } };
+    }
+  }
+
+  // ── Sports ──
+  if (prefix === 'sports') {
+    const secondColon = rest.indexOf(':');
+    if (secondColon === -1) {
+      return { error: { status: 400, code: 'invalid_id_format', message: 'Sports id must be "sports:LEAGUE:EVENT_ID"' } };
+    }
+
+    const league = rest.slice(0, secondColon);
+    const eventId = rest.slice(secondColon + 1);
+
+    if (!ALL_SPORTS_LEAGUES.includes(league)) {
+      return { error: { status: 400, code: 'unknown_league', message: `Unknown league "${league}". Valid: ${ALL_SPORTS_LEAGUES.join(', ')}` } };
+    }
+
+    const events = await fetchSportsEvents(league);
+    const event = events.find(e => e.idEvent === eventId);
+
+    if (!event) {
+      return { error: { status: 404, code: 'event_not_found', message: `Event "${eventId}" not found in ${league}` } };
+    }
+
+    const status = normalizeSportsStatus(event.strStatus);
+    if (status === 'finished') {
+      return { error: { status: 400, code: 'event_not_bettable', message: 'Event has already finished' } };
+    }
+    if (status === 'canceled') {
+      return { error: { status: 400, code: 'event_not_bettable', message: 'Event is canceled or postponed' } };
+    }
+
+    const startTime = new Date(event.strTimestamp + (event.strTimestamp.endsWith('Z') ? '' : 'Z'));
+    const isLive = status === 'live';
+    if (!isLive) {
+      const minTime = new Date(Date.now() + 2 * 60 * 1000);
+      if (startTime <= minTime) {
+        return { error: { status: 400, code: 'event_not_bettable', message: 'Event starts too soon — must be at least 2 minutes from now' } };
+      }
+    }
+
+    const lockTimestamp = isLive
+      ? Math.floor((Date.now() + 5 * 60 * 1000) / 1000)
+      : Math.floor(startTime.getTime() / 1000);
+
+    return {
+      type: 'sports',
+      gameMode: 4,
+      sportsEvent: event,
+      lockTimestamp,
+      sportsEventId: eventId,
+      league,
+      startTime: normalizeTimestamp(event.strTimestamp),
+      status,
+    };
+  }
+
+  return { error: { status: 400, code: 'unknown_event_type', message: `Unknown type "${prefix}". Supported: esports, sports` } };
+}
+
+// ── Game Lifecycle ──
+
+/**
+ * POST /api/developer/v1/games/validate
+ * Check if an event is bettable. Lightweight yes/no check.
+ * Body: { id: "sports:UFC:espn-ufc-600057329" } or { id: "esports:1353988" }
+ */
+apiRouter.post('/games/validate', async (req, res) => {
+  try {
+    const resolved = await resolveEventId(req.body.id);
+
+    if (resolved.error) {
+      return apiError(res, resolved.error.status, resolved.error.code, resolved.error.message);
+    }
+
+    res.json({
+      success: true,
+      bettable: true,
+      gameMode: resolved.gameMode,
+      lockTimestamp: resolved.lockTimestamp,
+      startTime: resolved.startTime,
+      status: resolved.status,
+    });
+  } catch (error) {
+    console.error('[DevAPI] Error validating game:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to validate event');
+  }
+});
+
+/**
+ * POST /api/developer/v1/games/create
+ * Resolve event, validate, and build an unsigned create+join transaction.
+ * Body: { id, playerWallet, teamChoice, wagerAmount }
+ * Developer never handles raw event data — we fetch it from the event ID.
+ */
+apiRouter.post('/games/create', async (req, res) => {
+  try {
+    const { id, playerWallet, teamChoice, wagerAmount } = req.body;
+
+    if (!id) return apiError(res, 400, 'invalid_request', 'id is required');
+    if (!playerWallet) return apiError(res, 400, 'invalid_request', 'playerWallet is required');
+    if (!teamChoice) return apiError(res, 400, 'invalid_request', 'teamChoice is required');
+    if (!wagerAmount) return apiError(res, 400, 'invalid_request', 'wagerAmount is required');
+    if (!['home', 'away', 'draw'].includes(teamChoice)) {
+      return apiError(res, 400, 'invalid_team_choice', 'teamChoice must be home, away, or draw');
+    }
+
+    // Resolve event ID → sportsEvent + lockTimestamp + gameMode
+    const resolved = await resolveEventId(id);
+    if (resolved.error) {
+      return apiError(res, resolved.error.status, resolved.error.code, resolved.error.message);
+    }
+
+    // Generate game ID in the same format as the existing frontend
+    const gameId = `sport-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+
+    // Build unsigned transaction
+    const txResponse = await axios.post(
+      `${BASE_URL_INTERNAL}/api/v1/prod/transaction/build/create-and-join-automatic`,
+      {
+        creatorAddress: playerWallet,
+        buyIn: wagerAmount,
+        lockTimestamp: resolved.lockTimestamp,
+        sportsEventId: resolved.sportsEventId,
+        teamChoice,
+        gameId,
+      },
+      { timeout: 15000 }
+    );
+
+    if (!txResponse.data.success) {
+      return apiError(res, 400, 'transaction_failed', 'Failed to build transaction');
+    }
+
+    // Build normalized event for the developer to display
+    let event;
+    if (resolved.type === 'sports') {
+      event = normalizeToUnifiedSportsEvent(resolved.sportsEvent, resolved.league);
+    } else {
+      const se = resolved.sportsEvent || {};
+      event = {
+        id: `esports:${resolved.sportsEventId}`,
+        type: 'esports',
+        title: se.strEvent || null,
+        league: se.strLeague || null,
+        game: se.strSport || null,
+        startTime: resolved.startTime,
+        status: resolved.status,
+        opponents: [
+          { name: se.strHomeTeam || null, imageUrl: null, score: null },
+          { name: se.strAwayTeam || null, imageUrl: null, score: null },
+        ],
+      };
+    }
+
+    const ok = await simulateTransactionOrFail(txResponse.data.transaction, res, 'CreateGame');
+    if (!ok) return;
+
+    // Stash raw event data server-side for confirm (never sent to client)
+    stashEventData(txResponse.data.gameId, {
+      sportsEvent: resolved.sportsEvent,
+      gameMode: resolved.gameMode,
+      lockTimestamp: resolved.lockTimestamp,
+    });
+
+    res.json({
+      success: true,
+      gameId: txResponse.data.gameId,
+      gameAddress: txResponse.data.gameAddress,
+      transaction: txResponse.data.transaction,
+      lockTimestamp: resolved.lockTimestamp,
+      event,
+    });
+  } catch (error) {
+    console.error('[DevAPI] Error creating game:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to create game');
+  }
+});
+
+/**
+ * POST /api/developer/v1/games/join
+ * Build an unsigned join transaction for an existing game.
+ * Body: { playerWallet, gameId, teamChoice, amount }
+ */
+apiRouter.post('/games/join', async (req, res) => {
+  try {
+    const { playerWallet, gameId, teamChoice, amount } = req.body;
+
+    if (!playerWallet) return apiError(res, 400, 'invalid_request', 'playerWallet is required');
+    if (!gameId) return apiError(res, 400, 'invalid_request', 'gameId is required');
+    if (!teamChoice) return apiError(res, 400, 'invalid_request', 'teamChoice is required');
+    if (!amount) return apiError(res, 400, 'invalid_request', 'amount is required');
+
+    // ── Network mode visibility check ──
+    const { appId, networkMode } = req.developerApp;
+    const attrResult = await pool.query(
+      `SELECT dga.app_id, da.network_mode
+       FROM developer_game_attributions dga
+       JOIN developer_apps da ON dga.app_id = da.id
+       WHERE dga.game_id = $1`,
+      [gameId]
+    );
+
+    if (attrResult.rows.length > 0) {
+      const gameApp = attrResult.rows[0];
+      if (gameApp.network_mode === 'private' && gameApp.app_id !== appId) {
+        return apiError(res, 403, 'game_not_accessible', 'This game is not available on your app');
+      }
+      if (networkMode === 'private' && gameApp.app_id !== appId) {
+        return apiError(res, 403, 'game_not_accessible', 'Your app is in private mode — you can only join games created through your app');
+      }
+    } else if (networkMode === 'private') {
+      // No attribution (main Dubs game) — private apps can't join these
+      return apiError(res, 403, 'game_not_accessible', 'Your app is in private mode — you can only join games created through your app');
+    }
+
+    const txResponse = await axios.post(
+      `${BASE_URL_INTERNAL}/api/v1/prod/transaction/build/join-automatic`,
+      { playerAddress: playerWallet, gameId, teamChoice, amount },
+      { timeout: 15000 }
+    );
+
+    const ok = await simulateTransactionOrFail(txResponse.data.transaction, res, 'JoinGame');
+    if (!ok) return;
+
+    res.json({
+      success: true,
+      gameId,
+      transaction: txResponse.data.transaction,
+      gameAddress: txResponse.data.gameAddress,
+    });
+  } catch (error) {
+    console.error('[DevAPI] Error building join tx:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to build join transaction');
+  }
+});
+
+/**
+ * POST /api/developer/v1/games/confirm
+ * Confirm a signed transaction and save the game to DB.
+ * Body: { gameId, playerWallet, signature, teamChoice, wagerAmount, gameAddress }
+ * Event data is retrieved server-side from the stash (set during create).
+ */
+apiRouter.post('/games/confirm', async (req, res) => {
+  try {
+    const {
+      gameId,
+      playerWallet,
+      signature,
+      teamChoice,
+      wagerAmount,
+      role = 'creator',
+      gameAddress,
+    } = req.body;
+
+    if (!gameId) return apiError(res, 400, 'invalid_request', 'gameId is required');
+    if (!playerWallet) return apiError(res, 400, 'invalid_request', 'playerWallet is required');
+    if (!signature) return apiError(res, 400, 'invalid_request', 'signature is required');
+
+    // Retrieve stashed event data from create step (only required for creators)
+    const stashed = popEventData(gameId);
+    if (role === 'creator' && !stashed) {
+      return apiError(res, 400, 'stash_expired', 'Game session expired or was already confirmed. Call /games/create again.');
+    }
+
+    const sportsEvent = stashed?.sportsEvent || {};
+    const gameMode = stashed?.gameMode || 4;
+    const lockTimestamp = stashed?.lockTimestamp || null;
+    const explorerUrl = `https://solscan.io/tx/${signature}`;
+
+    if (role === 'creator') {
+      // Creator: save shared game data + user ref via /save
+      const saveBody = {
+        walletAddress: playerWallet,
+        gameId,
+        sharedGameData: {
+          title: sportsEvent?.strEvent || sportsEvent?.matchName || `Game ${gameId.slice(0, 8)}`,
+          gameType: 'automatic',
+          gameAddress,
+          buyIn: wagerAmount,
+          maxPlayers: 0,
+          gameMode,
+          createdBy: playerWallet,
+          sportsEvent,
+          homeTeamPlayers: teamChoice === 'home' ? [playerWallet] : [],
+          awayTeamPlayers: teamChoice === 'away' ? [playerWallet] : [],
+          drawTeamPlayers: teamChoice === 'draw' ? [playerWallet] : [],
+          lockTimestamp,
+        },
+        userGameRef: {
+          role,
+          joinedAt: new Date().toISOString(),
+          teamChoice,
+          mySignature: signature,
+          myExplorerUrl: explorerUrl,
+          status: 'active',
+        },
+      };
+      await axios.post(`${BASE_URL_INTERNAL}/api/auth/games/save`, saveBody, { timeout: 15000 });
+    } else {
+      // Joiner: use the /:gameId/join endpoint which updates team arrays + pools
+      const joinBody = {
+        walletAddress: playerWallet,
+        teamChoice,
+        amount: wagerAmount,
+        userGameRef: {
+          role: 'player',
+          joinedAt: new Date().toISOString(),
+          teamChoice,
+          mySignature: signature,
+          myExplorerUrl: explorerUrl,
+          status: 'active',
+        },
+      };
+      await axios.post(`${BASE_URL_INTERNAL}/api/auth/games/${gameId}/join`, joinBody, { timeout: 15000 });
+
+      // Auto-lock custom games (game_mode=6) when maxPlayers reached
+      if (gameMode === 6) {
+        const gameCheck = await pool.query('SELECT max_players FROM games WHERE game_id = $1', [gameId]);
+        const mp = gameCheck.rows[0]?.max_players || 0;
+        if (mp > 0) {
+          await autoLockIfFull(gameId, mp);
+        }
+      }
+    }
+
+    // Create developer attribution record for commission tracking
+    const { appId, developerId, commissionWallet } = req.developerApp;
+    await pool.query(`
+      INSERT INTO developer_game_attributions (game_id, app_id, developer_id, commission_wallet)
+      VALUES ($1, $2, $3, $4)
+      ON CONFLICT DO NOTHING
+    `, [gameId, appId, developerId, commissionWallet]);
+
+    console.log(`[DevAPI] Game ${gameId} attributed to app ${appId} (dev ${developerId}, commission → ${commissionWallet})`);
+
+    // Fire webhooks (non-blocking)
+    const webhookPayload = {
+      gameId,
+      gameAddress,
+      playerWallet,
+      teamChoice,
+      wagerAmount,
+      role,
+      signature,
+      explorerUrl,
+    };
+
+    if (role === 'creator') {
+      fireWebhooks(appId, 'game.created', webhookPayload);
+    } else {
+      // Notify the joining player's app
+      fireWebhooks(appId, 'game.joined', webhookPayload);
+
+      // Also notify the game creator's app (may be a different app)
+      pool.query(
+        `SELECT app_id FROM developer_game_attributions WHERE game_id = $1 AND app_id != $2 LIMIT 1`,
+        [gameId, appId]
+      ).then(({ rows }) => {
+        if (rows.length > 0) {
+          fireWebhooks(rows[0].app_id, 'game.joined', webhookPayload);
+        }
+      }).catch(() => {});
+    }
+
+    res.json({
+      success: true,
+      gameId,
+      signature,
+      explorerUrl,
+      message: role === 'creator' ? 'Game created and confirmed' : 'Game joined and confirmed',
+    });
+  } catch (error) {
+    console.error('[DevAPI] Error confirming game:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to confirm game');
+  }
+});
+
+/**
+ * GET /api/developer/v1/games/:gameId
+ * Get game status and details
+ */
+apiRouter.get('/games/:gameId', async (req, res) => {
+  try {
+    const { gameId } = req.params;
+
+    const result = await pool.query(`
+      SELECT
+        g.game_id,
+        g.game_address,
+        g.title,
+        g.buy_in,
+        g.game_mode,
+        g.is_locked,
+        g.is_resolved,
+        g.automatic_status,
+        g.lock_timestamp,
+        g.home_team_players,
+        g.away_team_players,
+        g.draw_team_players,
+        g.player_amounts,
+        g.home_pool,
+        g.away_pool,
+        g.draw_pool,
+        g.total_pool,
+        g.sports_event,
+        g.matchup_image_url,
+        g.created_at,
+        g.updated_at,
+        g.sports_event->'finalScore'->>'winner' as winner_side
+      FROM games g
+      WHERE g.game_id = $1
+    `, [gameId]);
+
+    if (result.rows.length === 0) {
+      return apiError(res, 404, 'game_not_found', 'Game not found');
+    }
+
+    const game = result.rows[0];
+    const se = game.sports_event || {};
+    const playerAmounts = game.player_amounts || {};
+
+    // Build enriched bettors array — resolve wallets to user profiles
+    const allWallets = [
+      ...(game.home_team_players || []).map(w => ({ wallet: w, team: 'home' })),
+      ...(game.away_team_players || []).map(w => ({ wallet: w, team: 'away' })),
+      ...(game.draw_team_players || []).map(w => ({ wallet: w, team: 'draw' })),
+    ];
+
+    let bettors = [];
+    if (allWallets.length > 0) {
+      const uniqueWallets = [...new Set(allWallets.map(b => b.wallet))];
+      const usersResult = await pool.query(
+        `SELECT wallet_address, username, avatar FROM users WHERE wallet_address = ANY($1)`,
+        [uniqueWallets]
+      );
+      const userMap = {};
+      for (const u of usersResult.rows) {
+        userMap[u.wallet_address] = u;
+      }
+
+      // Fetch claim data from user_game_refs
+      const refsResult = await pool.query(
+        `SELECT wallet_address, amount_claimed, claim_signature FROM user_game_refs WHERE game_id = $1 AND wallet_address = ANY($2)`,
+        [gameId, uniqueWallets]
+      );
+      const refsMap = {};
+      for (const r of refsResult.rows) {
+        refsMap[r.wallet_address] = r;
+      }
+
+      bettors = allWallets.map(b => {
+        const user = userMap[b.wallet] || {};
+        const ref = refsMap[b.wallet] || {};
+        return {
+          wallet: b.wallet,
+          username: user.username || null,
+          avatar: user.avatar || null,
+          team: b.team,
+          amount: parseFloat(playerAmounts[b.wallet]) || parseFloat(game.buy_in),
+          amountClaimed: ref.amount_claimed ? parseFloat(ref.amount_claimed) : null,
+          claimSignature: ref.claim_signature || null,
+        };
+      });
+    }
+
+    res.json({
+      success: true,
+      game: {
+        gameId: game.game_id,
+        gameAddress: game.game_address,
+        title: game.title,
+        buyIn: parseFloat(game.buy_in),
+        gameMode: game.game_mode,
+        isLocked: game.is_locked,
+        isResolved: game.is_resolved,
+        status: publicGameStatus(game.automatic_status),
+        league: se.strLeague || null,
+        lockTimestamp: game.lock_timestamp,
+        opponents: [
+          { name: se.strHomeTeam || null, imageUrl: se.strHomeTeamBadge || null },
+          { name: se.strAwayTeam || null, imageUrl: se.strAwayTeamBadge || null },
+        ],
+        winnerSide: game.winner_side || null,
+        bettors,
+        homePool: parseFloat(game.home_pool) || 0,
+        awayPool: parseFloat(game.away_pool) || 0,
+        drawPool: parseFloat(game.draw_pool) || 0,
+        totalPool: parseFloat(game.total_pool) || 0,
+        media: {
+          poster: game.matchup_image_url || se.strPoster || null,
+          thumbnail: game.matchup_image_url || se.strThumb || null,
+        },
+        createdAt: game.created_at,
+        updatedAt: game.updated_at,
+      },
+    });
+  } catch (error) {
+    console.error('[DevAPI] Error fetching game:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to fetch game');
+  }
+});
+
+/**
+ * GET /api/developer/v1/games/:gameId/live-score
+ * Returns the live ESPN score data for a specific game.
+ */
+apiRouter.get('/games/:gameId/live-score', async (req, res) => {
+  try {
+    const { gameId } = req.params;
+
+    // 1. Look up the game
+    const result = await pool.query(
+      `SELECT sports_event, game_mode FROM games WHERE game_id = $1`,
+      [gameId]
+    );
+
+    if (result.rows.length === 0) {
+      return apiError(res, 404, 'game_not_found', 'Game not found');
+    }
+
+    const game = result.rows[0];
+    const se = game.sports_event || {};
+    const homeTeam = se.strHomeTeam;
+    const awayTeam = se.strAwayTeam;
+    const league = se.strLeague;
+
+    if (!league || !homeTeam || !awayTeam) {
+      return res.json({ success: true, liveScore: null });
+    }
+
+    // 2. Normalize the league name to ESPN abbreviation
+    const espnLeague = normalizeLeague(league);
+    const url = ESPN_URLS[espnLeague];
+
+    if (!url) {
+      return res.json({ success: true, liveScore: null });
+    }
+
+    // 3. Fetch scores from ESPN
+    let scores;
+    if (espnLeague === 'UFC') {
+      scores = await fetchUFCScores(url);
+    } else {
+      scores = await fetchScoresForLeague(url, espnLeague);
+    }
+
+    // 4. Match by team names (case-insensitive)
+    const homeLower = homeTeam.toLowerCase();
+    const awayLower = awayTeam.toLowerCase();
+
+    const match = scores.find(s => {
+      const names = s.competitors.map(c => c.name.toLowerCase());
+      return names.includes(homeLower) || names.includes(awayLower);
+    });
+
+    if (!match) {
+      return res.json({ success: true, liveScore: null });
+    }
+
+    // 5. Build response
+    const liveScore = {
+      status: match.status,
+      period: match.period || null,
+      displayClock: match.displayClock || null,
+      detail: match.detail || null,
+      shortDetail: match.shortDetail || null,
+      competitors: match.competitors.map(c => ({
+        name: c.name,
+        homeAway: c.homeAway,
+        score: c.score,
+        logo: c.logo || null,
+        abbreviation: c.abbreviation || '',
+      })),
+    };
+
+    // Include UFC-specific data if present
+    if (match.ufcData) {
+      liveScore.ufcData = match.ufcData;
+    }
+
+    res.json({ success: true, liveScore });
+  } catch (error) {
+    console.error('[DevAPI] Error fetching live score:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to fetch live score');
+  }
+});
+
+/**
+ * GET /api/developer/v1/games
+ * List games, optionally filtered by wallet
+ */
+apiRouter.get('/games', async (req, res) => {
+  try {
+    const { wallet, status, limit = 20, offset = 0 } = req.query;
+    const { appId, networkMode } = req.developerApp;
+
+    const params = [];
+    const conditions = [];
+    let query;
+
+    if (networkMode === 'private') {
+      // Private app: only see games created through THIS app
+      params.push(appId);
+      query = `
+        SELECT
+          g.game_id, g.title, g.buy_in, g.game_mode,
+          g.is_locked, g.is_resolved, g.automatic_status,
+          g.total_pool, g.lock_timestamp,
+          g.sports_event, g.matchup_image_url, g.created_at
+        FROM games g
+        JOIN developer_game_attributions dga ON g.game_id = dga.game_id
+        WHERE dga.app_id = $${params.length}
+      `;
+    } else {
+      // Open app: see games from other open apps + unattributed (main Dubs) + own games
+      params.push(appId);
+      query = `
+        SELECT
+          g.game_id, g.title, g.buy_in, g.game_mode,
+          g.is_locked, g.is_resolved, g.automatic_status,
+          g.total_pool, g.lock_timestamp,
+          g.sports_event, g.matchup_image_url, g.created_at
+        FROM games g
+        LEFT JOIN developer_game_attributions dga ON g.game_id = dga.game_id
+        LEFT JOIN developer_apps da ON dga.app_id = da.id
+        WHERE (
+          da.network_mode = 'open'
+          OR dga.app_id IS NULL
+          OR dga.app_id = $${params.length}
+        )
+      `;
+    }
+
+    if (wallet) {
+      params.push(wallet);
+      conditions.push(`(g.home_team_players @> ARRAY[$${params.length}]::text[] OR g.away_team_players @> ARRAY[$${params.length}]::text[] OR g.draw_team_players @> ARRAY[$${params.length}]::text[])`);
+    }
+
+    if (status) {
+      // Map public API status names to internal DB values
+      const statusMap = { open: 'pending', running: 'pending', locked: 'locked', resolved: 'resolved', pending: 'pending' };
+      const dbStatus = statusMap[status] || status;
+      params.push(dbStatus);
+      conditions.push(`g.automatic_status = $${params.length}`);
+
+      // For "open" status, also exclude games whose lock time has passed
+      if (status === 'open') {
+        conditions.push(`(g.lock_timestamp IS NULL OR g.lock_timestamp > ${Math.floor(Date.now() / 1000)})`);
+      }
+    }
+
+    if (conditions.length > 0) {
+      query += ' AND ' + conditions.join(' AND ');
+    }
+
+    query += ' ORDER BY g.created_at DESC';
+
+    params.push(parseInt(limit));
+    query += ` LIMIT $${params.length}`;
+
+    params.push(parseInt(offset));
+    query += ` OFFSET $${params.length}`;
+
+    const result = await pool.query(query, params);
+
+    res.json({
+      success: true,
+      games: result.rows.map(normalizeGameRow),
+    });
+  } catch (error) {
+    console.error('[DevAPI] Error listing games:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to list games');
+  }
+});
+
+/**
+ * GET /api/developer/v1/network/games
+ * Fetch joinable games from the Dubs open network.
+ * Only available to apps with network_mode = 'open'.
+ * Returns sports games that have at least one empty team slot.
+ */
+apiRouter.get('/network/games', async (req, res) => {
+  try {
+    const { appId, networkMode } = req.developerApp;
+
+    // Only open-network apps can browse the network
+    if (networkMode === 'private') {
+      return apiError(res, 403, 'network_mode_private', 'Network games are only available to apps with open network mode');
+    }
+
+    const { league, exclude_wallet, limit = 20, offset = 0 } = req.query;
+    const params = [appId];
+    const nowUnix = Math.floor(Date.now() / 1000);
+
+    let query = `
+      SELECT
+        g.game_id, g.title, g.buy_in, g.game_mode,
+        g.is_locked, g.is_resolved, g.automatic_status,
+        g.total_pool, g.lock_timestamp,
+        g.sports_event, g.matchup_image_url, g.created_at
+      FROM games g
+      LEFT JOIN developer_game_attributions dga ON g.game_id = dga.game_id
+      LEFT JOIN developer_apps da ON dga.app_id = da.id
+      WHERE
+        (da.network_mode = 'open' OR dga.app_id IS NULL OR dga.app_id = $1)
+        AND g.game_mode = 4
+        AND g.automatic_status = 'pending'
+        AND g.is_locked = false
+        AND g.is_resolved = false
+        AND (g.lock_timestamp IS NULL OR g.lock_timestamp > ${nowUnix})
+    `;
+
+    // Exclude games the wallet is already in
+    if (exclude_wallet) {
+      params.push(exclude_wallet);
+      query += ` AND NOT (g.home_team_players @> ARRAY[$${params.length}]::text[] OR g.away_team_players @> ARRAY[$${params.length}]::text[] OR g.draw_team_players @> ARRAY[$${params.length}]::text[])`;
+    }
+
+    // Server-side league filter
+    if (league) {
+      const dbLeague = LEAGUE_ABBREV_TO_DB[league.toUpperCase()];
+      if (dbLeague) {
+        params.push(`%${dbLeague}%`);
+        query += ` AND g.sports_event->>'strLeague' ILIKE $${params.length}`;
+      }
+    }
+
+    // Count for pagination (before LIMIT/OFFSET)
+    const countQuery = `SELECT COUNT(*) FROM (${query}) sub`;
+    const countResult = await pool.query(countQuery, params);
+    const total = parseInt(countResult.rows[0].count);
+
+    query += ' ORDER BY g.created_at DESC';
+
+    params.push(parseInt(limit));
+    query += ` LIMIT $${params.length}`;
+
+    params.push(parseInt(offset));
+    query += ` OFFSET $${params.length}`;
+
+    const result = await pool.query(query, params);
+
+    res.json({
+      success: true,
+      games: result.rows.map(normalizeGameRow),
+      pagination: {
+        total,
+        limit: parseInt(limit),
+        offset: parseInt(offset),
+      },
+    });
+  } catch (error) {
+    console.error('[DevAPI] Error listing network games:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to list network games');
+  }
+});
+
+/**
+ * POST /api/developer/v1/transactions/build/claim
+ * Build an unsigned claim transaction for a resolved game
+ */
+apiRouter.post('/transactions/build/claim', async (req, res) => {
+  try {
+    const { playerWallet, gameId } = req.body;
+
+    if (!playerWallet) return apiError(res, 400, 'invalid_request', 'playerWallet is required');
+    if (!gameId) return apiError(res, 400, 'invalid_request', 'gameId is required');
+
+    const txResponse = await axios.post(
+      `${BASE_URL_INTERNAL}/api/v1/prod/transaction/build/claim-automatic`,
+      { playerAddress: playerWallet, gameId },
+      { timeout: 15000 }
+    );
+
+    const base64Tx = txResponse.data.transaction;
+
+    const ok = await simulateTransactionOrFail(base64Tx, res, 'Claim');
+    if (!ok) return;
+
+    res.json({
+      success: true,
+      transaction: base64Tx,
+      gameAddress: txResponse.data.gameAddress,
+      message: 'Have your user sign this transaction to claim winnings',
+    });
+  } catch (error) {
+    console.error('[DevAPI] Error building claim tx:', error.message);
+    // Pass through error from internal API
+    if (error.response?.data) {
+      const d = error.response.data;
+      const code = d.error?.code || d.code || 'transaction_failed';
+      const message = d.error?.message || d.message || 'Failed to build claim transaction';
+      return apiError(res, error.response.status || 400, code, message);
+    }
+    apiError(res, 500, 'internal_error', 'Failed to build claim transaction');
+  }
+});
+
+/**
+ * GET /api/developer/v1/apps/config
+ * Returns the app's UI customization config (accent color, icon, tagline)
+ * Used by the SDK on DubsProvider mount to apply developer branding
+ */
+apiRouter.get('/apps/config', apiKeyAuth, async (req, res) => {
+  try {
+    const { rows } = await pool.query(
+      'SELECT ui_config, website_url, app_name FROM developer_apps WHERE id = $1',
+      [req.developerApp.appId]
+    );
+    const app = rows[0] || {};
+    res.json({
+      success: true,
+      data: {
+        uiConfig: {
+          ...app.ui_config,
+          appUrl: app.website_url || undefined,
+          appName: app.ui_config?.appName || app.app_name || undefined,
+        }
+      }
+    });
+  } catch (error) {
+    console.error('[DevAPI] Error fetching app config:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to fetch app config');
+  }
+});
+
+/**
+ * POST /api/developer/v1/errors/parse
+ * Decode a raw Solana transaction error into a human-readable { code, message }
+ */
+apiRouter.post('/errors/parse', (req, res) => {
+  const { error } = req.body;
+  if (!error) return apiError(res, 400, 'invalid_request', 'error field is required');
+  const parsed = parseSolanaError(error);
+  res.json({ success: true, error: parsed });
+});
+
+/**
+ * GET /api/developer/v1/errors/codes
+ * Return the full map of Solana program error codes for client-side use
+ */
+apiRouter.get('/errors/codes', (_req, res) => {
+  res.json({ success: true, errors: SOLANA_PROGRAM_ERRORS });
+});
+
+// ============================================================
+// CUSTOM GAME ENDPOINTS (game_mode=6)
+// Developer-resolved games — no sports/esports event needed
+// ============================================================
+
+/**
+ * POST /api/developer/v1/games/custom/create
+ * Create a custom wager game. Returns unsigned Solana transaction.
+ *
+ * Body: {
+ *   playerWallet, teamChoice, wagerAmount, title,
+ *   lockTimestamp? (ISO string or unix — defaults to now+30days),
+ *   maxPlayers? (0=unlimited, default),
+ *   metadata? (arbitrary developer data)
+ * }
+ */
+apiRouter.post('/games/custom/create', async (req, res) => {
+  try {
+    const {
+      playerWallet,
+      teamChoice,
+      wagerAmount,
+      title,
+      lockTimestamp: rawLockTimestamp,
+      maxPlayers = 0,
+      metadata,
+    } = req.body;
+
+    if (!playerWallet) return apiError(res, 400, 'invalid_request', 'playerWallet is required');
+    if (!teamChoice) return apiError(res, 400, 'invalid_request', 'teamChoice is required');
+    if (!wagerAmount) return apiError(res, 400, 'invalid_request', 'wagerAmount is required');
+    if (!['home', 'away', 'draw'].includes(teamChoice)) {
+      return apiError(res, 400, 'invalid_team_choice', 'teamChoice must be home, away, or draw');
+    }
+    if (typeof maxPlayers !== 'number' || maxPlayers < 0 || maxPlayers > 50) {
+      return apiError(res, 400, 'invalid_max_players', 'maxPlayers must be 0-50 (0 = unlimited)');
+    }
+
+    // Resolve lockTimestamp
+    // Default to now + 30 days (same pattern as Connect4).
+    // Custom games don't have a real "game start" time — the developer controls
+    // when to resolve via the resolve endpoint. The force-lock + resolve pattern
+    // allows immediate resolution regardless of lock time.
+    // Developers can override via the lockTimestamp param if needed.
+    let lockTimestamp;
+    if (rawLockTimestamp) {
+      // Accept ISO string or Unix seconds
+      lockTimestamp = typeof rawLockTimestamp === 'string'
+        ? Math.floor(new Date(rawLockTimestamp).getTime() / 1000)
+        : Math.floor(rawLockTimestamp);
+    } else {
+      lockTimestamp = Math.floor(Date.now() / 1000) + (30 * 24 * 60 * 60); // 30 days
+    }
+
+    // Validate lockTimestamp is at least 2 minutes in the future (contract enforces this at init)
+    const minLock = Math.floor(Date.now() / 1000) + 110; // small buffer
+    if (lockTimestamp < minLock) {
+      return apiError(res, 400, 'invalid_lock_timestamp', 'lockTimestamp must be at least 2 minutes in the future');
+    }
+
+    const gameTitle = title || `Custom Game`;
+
+    // Generate game ID — custom prefix for easy identification
+    const gameId = crypto.randomUUID();
+
+    // Use the game title as the on-chain sportsEventId (it's just a string label)
+    const sportsEventId = `custom:${req.developerApp.appId}:${gameId}`;
+
+    // Build unsigned transaction via the same internal builder
+    const txResponse = await axios.post(
+      `${BASE_URL_INTERNAL}/api/v1/prod/transaction/build/create-and-join-automatic`,
+      {
+        creatorAddress: playerWallet,
+        buyIn: wagerAmount,
+        lockTimestamp,
+        sportsEventId,
+        teamChoice,
+        gameId,
+      },
+      { timeout: 15000 }
+    );
+
+    if (!txResponse.data.success) {
+      return apiError(res, 400, 'transaction_failed', 'Failed to build transaction');
+    }
+
+    // Stash custom game data for the confirm step
+    stashEventData(txResponse.data.gameId, {
+      sportsEvent: {
+        strEvent: gameTitle,
+        strHomeTeam: 'Home',
+        strAwayTeam: 'Away',
+        strLeague: 'Custom',
+        ...(metadata || {}),
+      },
+      gameMode: 6,
+      lockTimestamp,
+      maxPlayers,
+      metadata: metadata || null,
+      title: gameTitle,
+    });
+
+    const ok = await simulateTransactionOrFail(txResponse.data.transaction, res, 'CustomCreate');
+    if (!ok) return;
+
+    res.json({
+      success: true,
+      gameId: txResponse.data.gameId,
+      gameAddress: txResponse.data.gameAddress,
+      transaction: txResponse.data.transaction,
+      lockTimestamp,
+    });
+  } catch (error) {
+    console.error('[DevAPI] Error creating custom game:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to create custom game');
+  }
+});
+
+/**
+ * POST /api/developer/v1/games/custom/confirm
+ * Confirm a signed custom game transaction and save to DB.
+ *
+ * Body: {
+ *   gameId, playerWallet, signature, teamChoice, wagerAmount,
+ *   role? ('creator'|'player'), gameAddress
+ * }
+ */
+apiRouter.post('/games/custom/confirm', async (req, res) => {
+  try {
+    const {
+      gameId,
+      playerWallet,
+      signature,
+      teamChoice,
+      wagerAmount,
+      role = 'creator',
+      gameAddress,
+    } = req.body;
+
+    if (!gameId) return apiError(res, 400, 'invalid_request', 'gameId is required');
+    if (!playerWallet) return apiError(res, 400, 'invalid_request', 'playerWallet is required');
+    if (!signature) return apiError(res, 400, 'invalid_request', 'signature is required');
+
+    // Retrieve stashed custom game data
+    const stashed = popEventData(gameId);
+    if (role === 'creator' && !stashed) {
+      return apiError(res, 400, 'stash_expired', 'Game session expired or was already confirmed. Call /games/custom/create again.');
+    }
+
+    const sportsEvent = stashed?.sportsEvent || {};
+    const gameMode = 6;
+    const lockTimestamp = stashed?.lockTimestamp || null;
+    const maxPlayers = stashed?.maxPlayers || 0;
+    const gameTitle = stashed?.title || sportsEvent?.strEvent || `Custom Game ${gameId.slice(0, 8)}`;
+
+    const explorerUrl = `https://solscan.io/tx/${signature}`;
+
+    if (role === 'creator') {
+      const saveBody = {
+        walletAddress: playerWallet,
+        gameId,
+        sharedGameData: {
+          title: gameTitle,
+          gameType: 'automatic',
+          gameAddress,
+          buyIn: wagerAmount,
+          maxPlayers,
+          gameMode,
+          createdBy: playerWallet,
+          sportsEvent,
+          homeTeamPlayers: teamChoice === 'home' ? [playerWallet] : [],
+          awayTeamPlayers: teamChoice === 'away' ? [playerWallet] : [],
+          drawTeamPlayers: teamChoice === 'draw' ? [playerWallet] : [],
+          lockTimestamp,
+        },
+        userGameRef: {
+          role,
+          joinedAt: new Date().toISOString(),
+          teamChoice,
+          mySignature: signature,
+          myExplorerUrl: explorerUrl,
+          status: 'active',
+        },
+      };
+      await axios.post(`${BASE_URL_INTERNAL}/api/auth/games/save`, saveBody, { timeout: 15000 });
+    } else {
+      const joinBody = {
+        walletAddress: playerWallet,
+        teamChoice,
+        amount: wagerAmount,
+        userGameRef: {
+          role: 'player',
+          joinedAt: new Date().toISOString(),
+          teamChoice,
+          mySignature: signature,
+          myExplorerUrl: explorerUrl,
+          status: 'active',
+        },
+      };
+      await axios.post(`${BASE_URL_INTERNAL}/api/auth/games/${gameId}/join`, joinBody, { timeout: 15000 });
+
+      // Auto-lock if maxPlayers reached (game_mode=6 feature)
+      if (maxPlayers > 0) {
+        await autoLockIfFull(gameId, maxPlayers);
+      }
+    }
+
+    // Attribution
+    const { appId, developerId, commissionWallet } = req.developerApp;
+    await pool.query(`
+      INSERT INTO developer_game_attributions (game_id, app_id, developer_id, commission_wallet)
+      VALUES ($1, $2, $3, $4)
+      ON CONFLICT DO NOTHING
+    `, [gameId, appId, developerId, commissionWallet]);
+
+    console.log(`[DevAPI] Custom game ${gameId} attributed to app ${appId}`);
+
+    // Fire webhooks (non-blocking)
+    const webhookPayload = { gameId, gameAddress, playerWallet, teamChoice, wagerAmount, role, signature, explorerUrl };
+    if (role === 'creator') {
+      fireWebhooks(appId, 'game.created', webhookPayload);
+    } else {
+      fireWebhooks(appId, 'game.joined', webhookPayload);
+      pool.query(
+        `SELECT app_id FROM developer_game_attributions WHERE game_id = $1 AND app_id != $2 LIMIT 1`,
+        [gameId, appId]
+      ).then(({ rows }) => {
+        if (rows.length > 0) fireWebhooks(rows[0].app_id, 'game.joined', webhookPayload);
+      }).catch(() => {});
+    }
+
+    res.json({
+      success: true,
+      gameId,
+      signature,
+      explorerUrl,
+      message: role === 'creator' ? 'Custom game created and confirmed' : 'Custom game joined and confirmed',
+    });
+  } catch (error) {
+    console.error('[DevAPI] Error confirming custom game:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to confirm custom game');
+  }
+});
+
+/**
+ * POST /api/developer/v1/games/:gameId/claim/confirm
+ * Confirm a signed claim transaction and record it in the DB.
+ *
+ * Called by the SDK after the user signs and sends the on-chain claim tx.
+ *
+ * Body: { playerWallet, signature, amountClaimed }
+ */
+apiRouter.post('/games/:gameId/claim/confirm', async (req, res) => {
+  try {
+    const { gameId } = req.params;
+    const { playerWallet, signature, amountClaimed } = req.body;
+
+    if (!gameId) return apiError(res, 400, 'invalid_request', 'gameId is required');
+    if (!playerWallet) return apiError(res, 400, 'invalid_request', 'playerWallet is required');
+    if (!signature) return apiError(res, 400, 'invalid_request', 'signature is required');
+
+    const explorerUrl = `https://solscan.io/tx/${signature}`;
+
+    // Update user_game_refs with claim information
+    const result = await pool.query(`
+      UPDATE user_game_refs
+      SET claimed_at = NOW(),
+          claim_signature = $1,
+          claim_explorer_url = $2,
+          amount_claimed = $3,
+          updated_at = NOW()
+      WHERE wallet_address = $4 AND game_id = $5
+      RETURNING *
+    `, [signature, explorerUrl, amountClaimed || null, playerWallet, gameId]);
+
+    if (result.rows.length === 0) {
+      return apiError(res, 404, 'not_found', 'No game reference found for this player and game');
+    }
+
+    console.log(`[DevAPI] Claim confirmed: game=${gameId} player=${playerWallet} sig=${signature.slice(0, 12)}... amount=${amountClaimed}`);
+
+    // Fire game.claimed webhook (non-blocking)
+    const { appId } = req.developerApp;
+    fireWebhooks(appId, 'game.claimed', {
+      gameId,
+      playerWallet,
+      signature,
+      explorerUrl,
+      amountClaimed: amountClaimed || null,
+    });
+
+    res.json({
+      success: true,
+      gameId,
+      signature,
+      explorerUrl,
+      message: 'Claim confirmed',
+    });
+  } catch (error) {
+    console.error('[DevAPI] Error confirming claim:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to confirm claim');
+  }
+});
+
+/**
+ * POST /api/developer/v1/games/:gameId/resolve
+ * Developer webhook to resolve a custom game (game_mode=6).
+ *
+ * Security: API key + HMAC signature + app ownership + state validation
+ *
+ * Headers:
+ *   x-api-key: dubs_test_...
+ *   x-dubs-signature: sha256=<HMAC-SHA256(body, resolution_secret)>
+ *
+ * Body: {
+ *   winner: 'home' | 'away' | 'draw' | null,  // null = refund
+ *   metadata?: { ... }                          // optional proof data
+ * }
+ */
+apiRouter.post('/games/:gameId/resolve', async (req, res) => {
+  try {
+    const { gameId } = req.params;
+    const { winner, metadata } = req.body;
+
+    // 1. Validate winner value
+    if (winner === undefined) {
+      return apiError(res, 400, 'invalid_request', 'winner is required (use null for refund)');
+    }
+    if (winner !== null && !['home', 'away', 'draw'].includes(winner)) {
+      return apiError(res, 400, 'invalid_winner', 'winner must be home, away, draw, or null');
+    }
+
+    // 2. Verify HMAC signature
+    const signatureHeader = req.headers['x-dubs-signature'];
+    if (!signatureHeader) {
+      return apiError(res, 403, 'missing_signature', 'x-dubs-signature header is required');
+    }
+
+    // Look up the app's resolution_secret
+    const appResult = await pool.query(
+      'SELECT resolution_secret FROM developer_apps WHERE id = $1',
+      [req.developerApp.appId]
+    );
+    const resolutionSecret = appResult.rows[0]?.resolution_secret;
+    if (!resolutionSecret) {
+      return apiError(res, 403, 'no_resolution_secret', 'App has no resolution secret configured. Contact support.');
+    }
+
+    // Verify HMAC: sha256=<hex>
+    const rawBody = req.rawBody;
+    if (!rawBody) {
+      return apiError(res, 400, 'missing_raw_body', 'Request body could not be verified. Ensure Content-Type is application/json.');
+    }
+
+    const expectedSig = 'sha256=' + crypto.createHmac('sha256', resolutionSecret).update(rawBody).digest('hex');
+    if (!crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expectedSig))) {
+      return apiError(res, 403, 'invalid_signature', 'HMAC signature verification failed');
+    }
+
+    // 3. Load game and validate state
+    const gameResult = await pool.query(`
+      SELECT game_id, game_mode, is_resolved, is_locked, automatic_status,
+             home_team_players, away_team_players, draw_team_players
+      FROM games WHERE game_id = $1
+    `, [gameId]);
+
+    if (gameResult.rows.length === 0) {
+      return apiError(res, 404, 'game_not_found', 'Game not found');
+    }
+
+    const game = gameResult.rows[0];
+
+    if (game.game_mode !== 6) {
+      return apiError(res, 400, 'wrong_game_mode', 'Only custom games (game_mode=6) can be resolved via this endpoint');
+    }
+
+    if (game.is_resolved) {
+      return apiError(res, 409, 'already_resolved', 'Game has already been resolved');
+    }
+
+    // 4. Verify app ownership via developer_game_attributions
+    const attrResult = await pool.query(
+      'SELECT id FROM developer_game_attributions WHERE game_id = $1 AND app_id = $2',
+      [gameId, req.developerApp.appId]
+    );
+    if (attrResult.rows.length === 0) {
+      return apiError(res, 403, 'not_your_game', 'This game does not belong to your app');
+    }
+
+    // 5. Auto-lock if not locked yet
+    if (!game.is_locked) {
+      await pool.query(
+        `UPDATE games SET is_locked = true, automatic_status = 'locked', updated_at = NOW() WHERE game_id = $1`,
+        [gameId]
+      );
+      console.log(`[DevAPI] Auto-locked game ${gameId} before resolution`);
+    }
+
+    // 6. Check for competition — if only one side has bets, force refund
+    const homePlayers = game.home_team_players || [];
+    const awayPlayers = game.away_team_players || [];
+    const drawPlayers = game.draw_team_players || [];
+    const sidesWithBets = [homePlayers.length > 0, awayPlayers.length > 0, drawPlayers.length > 0].filter(Boolean).length;
+
+    let effectiveWinner = winner;
+    if (sidesWithBets < 2) {
+      effectiveWinner = null; // Force refund — no competition
+      console.log(`[DevAPI] Game ${gameId} has only ${sidesWithBets} side(s) with bets — forcing refund`);
+    }
+
+    // 7. Resolve on-chain + update DB
+    const resolver = getCustomGameResolver();
+    const { signature: txSignature } = await resolver.resolveGame(gameId, effectiveWinner, metadata);
+
+    // 8. Fire webhook notification
+    fireWebhooks(req.developerApp.appId, 'game.resolved', {
+      gameId,
+      winner: effectiveWinner,
+      signature: txSignature,
+      metadata: metadata || null,
+    });
+
+    res.json({
+      success: true,
+      gameId,
+      winner: effectiveWinner,
+      signature: txSignature,
+      explorerUrl: `https://solscan.io/tx/${txSignature}`,
+    });
+  } catch (error) {
+    console.error('[DevAPI] Error resolving custom game:', error.message);
+
+    let userMessage = error.message;
+    const hexMatch = error.message.match(/custom program error: 0x([0-9a-fA-F]+)/);
+    if (hexMatch) {
+      const errorCode = parseInt(hexMatch[1], 16);
+      const known = SOLANA_PROGRAM_ERRORS[errorCode];
+      if (known) userMessage = known.message;
+    }
+    if (error.transactionError) {
+      const parsed = parseSolanaError(error.transactionError);
+      if (parsed && parsed.code !== 'unknown_error') userMessage = parsed.message;
+    }
+
+    apiError(res, 500, 'resolution_failed', userMessage);
+  }
+});
+
+/**
+ * Auto-lock a game if it has reached maxPlayers.
+ * Used for game_mode=6 custom games (e.g., 1v1 Battleship).
+ */
+async function autoLockIfFull(gameId, maxPlayers) {
+  try {
+    const result = await pool.query(`
+      SELECT home_team_players, away_team_players, draw_team_players, is_locked
+      FROM games WHERE game_id = $1
+    `, [gameId]);
+
+    if (result.rows.length === 0) return;
+    const game = result.rows[0];
+    if (game.is_locked) return;
+
+    const totalPlayers = (game.home_team_players || []).length
+      + (game.away_team_players || []).length
+      + (game.draw_team_players || []).length;
+
+    if (totalPlayers >= maxPlayers) {
+      await pool.query(
+        `UPDATE games SET is_locked = true, automatic_status = 'locked', updated_at = NOW() WHERE game_id = $1`,
+        [gameId]
+      );
+      console.log(`[DevAPI] Auto-locked game ${gameId}: ${totalPlayers}/${maxPlayers} players`);
+    }
+  } catch (err) {
+    console.error(`[DevAPI] Error in autoLockIfFull for ${gameId}:`, err.message);
+  }
+}
+
+// ============================================================
+// UFC FIGHT CARD
+// ============================================================
+
+/**
+ * GET /api/developer/v1/ufc/fightcard
+ * Returns the full upcoming/live UFC fight card with all fights.
+ *
+ * Each fight includes fighters, weight class, round info, and live status.
+ * Fights are grouped by eventName so consumers can display the full card.
+ *
+ * Response shape:
+ * {
+ *   success: true,
+ *   events: [{
+ *     eventName: "UFC 324: ...",
+ *     fights: [{ home, away, weightClass, status, ufcData, ... }]
+ *   }]
+ * }
+ */
+apiRouter.get('/ufc/fightcard', async (req, res) => {
+  try {
+    // Fetch upcoming UFC events for the next 90 days (default scoreboard only returns current/next event)
+    const now = new Date();
+    const yesterday = new Date(now.getTime() - 24 * 60 * 60 * 1000);
+    const startDate = yesterday.toISOString().split('T')[0].replace(/-/g, '');
+    const endDate = new Date(now.getTime() + 90 * 24 * 60 * 60 * 1000)
+      .toISOString().split('T')[0].replace(/-/g, '');
+    const url = `${ESPN_URLS['UFC']}?dates=${startDate}-${endDate}`;
+    const rawFights = await fetchUFCScores(url);
+
+    // Group fights by eventName
+    const eventMap = new Map();
+    for (const fight of rawFights) {
+      const key = fight.eventName || 'UFC Event';
+      if (!eventMap.has(key)) {
+        eventMap.set(key, { eventName: key, date: fight.date, fights: [] });
+      }
+      const home = fight.competitors.find(c => c.homeAway === 'home') || fight.competitors[0];
+      const away = fight.competitors.find(c => c.homeAway === 'away') || fight.competitors[1];
+      eventMap.get(key).fights.push({
+        id: fight.competitionId || null,
+        home: {
+          name: home?.name || 'TBD',
+          athleteId: home?.athleteId || null,
+          headshotUrl: home?.headshot || null,
+          flagUrl: home?.logo || null,
+          country: home?.country || null,
+          abbreviation: home?.abbreviation || '',
+          record: home?.record || null,
+          winner: home?.winner || false,
+        },
+        away: {
+          name: away?.name || 'TBD',
+          athleteId: away?.athleteId || null,
+          headshotUrl: away?.headshot || null,
+          flagUrl: away?.logo || null,
+          country: away?.country || null,
+          abbreviation: away?.abbreviation || '',
+          record: away?.record || null,
+          winner: away?.winner || false,
+        },
+        weightClass: fight.weightClass || null,
+        status: fight.status,
+        ufcData: fight.ufcData || null,
+      });
+    }
+
+    const events = Array.from(eventMap.values());
+
+    res.json({ success: true, events });
+  } catch (error) {
+    console.error('[DevAPI] Error fetching UFC fight card:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to fetch UFC fight card');
+  }
+});
+
+// ============================================================
+// UFC FIGHTER DETAIL
+// ============================================================
+
+/**
+ * GET /api/developer/v1/ufc/fighters/:athleteId
+ * Returns detailed fighter profile from ESPN core API.
+ *
+ * Includes: nickname, height, weight, reach, stance, gym, stance photo,
+ * citizenship, weight class, date of birth, and age.
+ *
+ * The athleteId comes from the fightcard endpoint (home.athleteId / away.athleteId).
+ */
+apiRouter.get('/ufc/fighters/:athleteId', async (req, res) => {
+  try {
+    const { athleteId } = req.params;
+    if (!athleteId) {
+      return apiError(res, 400, 'missing_param', 'athleteId is required');
+    }
+
+    const espnUrl = `https://sports.core.api.espn.com/v2/sports/mma/leagues/ufc/athletes/${athleteId}`;
+    const { data } = await axios.get(espnUrl, { timeout: 10000 });
+
+    const fighter = {
+      athleteId: data.id,
+      firstName: data.firstName || null,
+      lastName: data.lastName || null,
+      fullName: data.fullName || data.displayName || null,
+      nickname: data.nickname || null,
+      shortName: data.shortName || null,
+      height: data.displayHeight || null,
+      heightInches: data.height || null,
+      weight: data.displayWeight || null,
+      weightLbs: data.weight || null,
+      reach: data.displayReach || null,
+      reachInches: data.reach || null,
+      age: data.age || null,
+      dateOfBirth: data.dateOfBirth || null,
+      stance: data.stance?.text || null,
+      weightClass: data.weightClass?.text || null,
+      citizenship: data.citizenship || null,
+      citizenshipAbbreviation: data.citizenshipCountry?.abbreviation || null,
+      gym: data.association?.name?.trim() || null,
+      gymCountry: data.association?.location?.country || null,
+      active: data.active || false,
+      headshotUrl: data.headshot?.href || null,
+      flagUrl: data.flag?.href || null,
+      stanceImageUrl: data.images?.find(img => img.rel?.includes('rightStance'))?.href || null,
+      espnUrl: data.links?.find(l => l.rel?.includes('playercard'))?.href || null,
+      slug: data.slug || null,
+    };
+
+    res.json({ success: true, fighter });
+  } catch (error) {
+    if (error.response?.status === 404) {
+      return apiError(res, 404, 'not_found', `Fighter with athleteId ${req.params.athleteId} not found`);
+    }
+    console.error('[DevAPI] Error fetching UFC fighter:', error.message);
+    apiError(res, 500, 'internal_error', 'Failed to fetch fighter details');
+  }
+});
+
+module.exports = { portalRouter, apiRouter };