{ "title": "Dhaniverse Game API Documentation", "version": "1.0.0", "description": "Comprehensive API documentation for the Dhaniverse financial education game backend services.", "baseUrl": "https://dhaniverse-backend.deno.dev", "sections": [ { "name": "Health & Status", "description": "System health checks and status endpoints", "endpoints": [ { "method": "GET", "path": "/health", "description": "Check server health and database connection status", "parameters": [], "responses": { "200": { "description": "Server is healthy", "example": { "status": "ok", "timestamp": "2025-09-23T10:30:00.000Z", "database": "connected" } } } }, { "method": "GET", "path": "/api/health", "description": "API-specific health check", "parameters": [], "responses": { "200": { "description": "API is healthy", "example": { "status": "ok", "message": "API is running", "version": "1.0.0" } } } }, { "method": "GET", "path": "/api/game/status", "description": "Game service status", "parameters": [], "responses": { "200": { "description": "Game service status", "example": { "status": "ok", "service": "game-api", "timestamp": "2025-09-23T10:30:00.000Z" } } } } ] }, { "name": "Authentication", "description": "User authentication and session management", "endpoints": [ { "method": "POST", "path": "/auth/send-magic-link", "description": "Send magic link authentication email", "parameters": [ { "name": "email", "type": "string", "required": true, "description": "User's email address" } ], "requestBody": { "example": { "email": "user@example.com" } }, "responses": { "200": { "description": "Magic link sent successfully", "example": { "success": true, "message": "Magic link sent to your email" } }, "429": { "description": "Rate limit exceeded", "example": { "error": "Rate limit exceeded", "message": "Please wait before requesting another magic link" } } } }, { "method": "GET", "path": "/auth/verify-magic-link", "description": "Verify magic link and authenticate user", "parameters": [ { "name": "token", "type": "string", "required": true, "description": "Magic link verification token" } ], "responses": { "200": { "description": "Authentication successful", "example": { "success": true, "user": { "email": "user@example.com", "id": "user_123" }, "token": "jwt_token_here" } }, "400": { "description": "Invalid or expired token", "example": { "error": "Invalid token", "message": "The magic link is invalid or has expired" } } } }, { "method": "GET", "path": "/auth/me", "description": "Get current user information", "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer JWT token" } ], "responses": { "200": { "description": "User information", "example": { "id": "user_123", "email": "user@example.com", "username": "player1", "createdAt": "2025-09-23T10:30:00.000Z" } }, "401": { "description": "Unauthorized", "example": { "error": "Unauthorized", "message": "Invalid or missing authentication token" } } } }, { "method": "POST", "path": "/auth/google", "description": "Authenticate with Google OAuth", "parameters": [ { "name": "credential", "type": "string", "required": true, "description": "Google OAuth credential token" } ], "requestBody": { "example": { "credential": "google_oauth_credential_token" } }, "responses": { "200": { "description": "Google authentication successful", "example": { "success": true, "user": { "email": "user@gmail.com", "name": "John Doe", "picture": "https://example.com/avatar.jpg" }, "token": "jwt_token_here" } } } }, { "method": "POST", "path": "/auth/internet-identity", "description": "Authenticate with Internet Identity", "parameters": [ { "name": "principal", "type": "string", "required": true, "description": "Internet Identity principal" }, { "name": "identity", "type": "object", "required": true, "description": "Identity verification data" } ], "responses": { "200": { "description": "Internet Identity authentication successful" } } }, { "method": "POST", "path": "/auth/signout", "description": "Sign out current user", "responses": { "200": { "description": "Successfully signed out", "example": { "success": true, "message": "Successfully signed out" } } } } ] }, { "name": "Player State", "description": "Manage player game state, progress, and currency", "endpoints": [ { "method": "GET", "path": "/game/player-state", "description": "Get current player state including currency and progress", "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer JWT token" } ], "responses": { "200": { "description": "Player state retrieved successfully", "example": { "id": "player_123", "username": "player1", "rupees": 1000, "bankBalance": 5000, "totalNetWorth": 6000, "level": 5, "experience": 2500, "lastLogin": "2025-09-23T10:30:00.000Z", "onboardingProgress": { "hasMetMaya": true, "hasFollowedMaya": true, "hasClaimedMoney": true, "hasBankAccount": true, "hasInvestedInStocks": false } } } } }, { "method": "PUT", "path": "/game/player-state", "description": "Update player state", "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer JWT token" } ], "requestBody": { "example": { "level": 6, "experience": 3000, "onboardingProgress": { "hasInvestedInStocks": true } } }, "responses": { "200": { "description": "Player state updated successfully", "example": { "success": true, "updatedState": { "level": 6, "experience": 3000 } } } } }, { "method": "PUT", "path": "/game/player-state/rupees", "description": "Update player's rupee balance", "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer JWT token" } ], "requestBody": { "example": { "rupees": 1500, "reason": "Quest completion reward" } }, "responses": { "200": { "description": "Rupee balance updated successfully", "example": { "success": true, "newBalance": 1500, "previousBalance": 1000 } } } }, { "method": "GET", "path": "/game/player-state/starter-status", "description": "Check if player has claimed starter money", "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer JWT token" } ], "responses": { "200": { "description": "Starter status retrieved", "example": { "hasClaimed": false, "canClaim": true, "amount": 1000 } } } }, { "method": "POST", "path": "/game/player-state/claim-starter", "description": "Claim starter money for new players", "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer JWT token" } ], "responses": { "200": { "description": "Starter money claimed successfully", "example": { "success": true, "amount": 1000, "newBalance": 1000 } }, "400": { "description": "Already claimed or ineligible", "example": { "error": "Already claimed", "message": "You have already claimed your starter money" } } } } ] }, { "name": "Banking System", "description": "Virtual banking operations including accounts, deposits, and withdrawals", "endpoints": [ { "method": "POST", "path": "/game/bank-account/create", "description": "Create a new bank account for the player", "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer JWT token" } ], "requestBody": { "example": { "accountType": "savings", "initialDeposit": 500 } }, "responses": { "200": { "description": "Bank account created successfully", "example": { "success": true, "account": { "id": "acc_123", "accountNumber": "DHAN123456789", "type": "savings", "balance": 500, "interestRate": 4.5, "createdAt": "2025-09-23T10:30:00.000Z" } } } } }, { "method": "GET", "path": "/game/bank-account", "description": "Get player's bank account details", "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer JWT token" } ], "responses": { "200": { "description": "Bank account details retrieved", "example": { "id": "acc_123", "accountNumber": "DHAN123456789", "balance": 2500, "type": "savings", "interestRate": 4.5, "lastTransaction": "2025-09-23T09:15:00.000Z" } } } }, { "method": "POST", "path": "/game/bank-account/deposit", "description": "Deposit money into bank account", "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer JWT token" } ], "requestBody": { "example": { "amount": 1000, "description": "Cash deposit" } }, "responses": { "200": { "description": "Deposit successful", "example": { "success": true, "transaction": { "id": "txn_123", "amount": 1000, "type": "deposit", "balanceAfter": 3500, "timestamp": "2025-09-23T10:30:00.000Z" } } } } }, { "method": "POST", "path": "/game/bank-account/withdraw", "description": "Withdraw money from bank account", "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer JWT token" } ], "requestBody": { "example": { "amount": 500, "description": "Cash withdrawal" } }, "responses": { "200": { "description": "Withdrawal successful", "example": { "success": true, "transaction": { "id": "txn_124", "amount": 500, "type": "withdrawal", "balanceAfter": 3000, "timestamp": "2025-09-23T10:35:00.000Z" } } }, "400": { "description": "Insufficient funds", "example": { "error": "Insufficient funds", "message": "Account balance is insufficient for this withdrawal" } } } } ] }, { "name": "Fixed Deposits", "description": "Fixed deposit investment management", "endpoints": [ { "method": "GET", "path": "/game/fixed-deposits", "description": "Get all player's fixed deposits", "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer JWT token" } ], "responses": { "200": { "description": "Fixed deposits retrieved", "example": { "deposits": [ { "id": "fd_123", "amount": 10000, "interestRate": 7.5, "tenure": 12, "maturityDate": "2026-09-23T10:30:00.000Z", "maturityAmount": 10750, "status": "active" } ] } } } }, { "method": "POST", "path": "/game/fixed-deposits", "description": "Create a new fixed deposit", "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer JWT token" } ], "requestBody": { "example": { "amount": 5000, "tenure": 6, "interestRate": 6.5 } }, "responses": { "200": { "description": "Fixed deposit created successfully", "example": { "success": true, "deposit": { "id": "fd_124", "amount": 5000, "interestRate": 6.5, "tenure": 6, "maturityDate": "2026-03-23T10:30:00.000Z", "maturityAmount": 5325 } } } } }, { "method": "POST", "path": "/game/fixed-deposits/:id/claim", "description": "Claim matured fixed deposit", "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer JWT token" } ], "parameters": [ { "name": "id", "type": "string", "required": true, "description": "Fixed deposit ID" } ], "responses": { "200": { "description": "Fixed deposit claimed successfully", "example": { "success": true, "amount": 10750, "interest": 750, "newBankBalance": 13750 } } } } ] }, { "name": "Stock Trading", "description": "Stock portfolio management and trading operations", "endpoints": [ { "method": "GET", "path": "/game/stock-portfolio", "description": "Get player's stock portfolio", "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer JWT token" } ], "responses": { "200": { "description": "Stock portfolio retrieved", "example": { "portfolio": [ { "symbol": "RELIANCE", "shares": 10, "avgPrice": 2500, "currentPrice": 2650, "totalValue": 26500, "gainLoss": 1500, "gainLossPercent": 6 } ], "totalValue": 26500, "totalInvestment": 25000, "totalGainLoss": 1500 } } } }, { "method": "GET", "path": "/game/stock-transactions", "description": "Get stock transaction history", "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer JWT token" } ], "responses": { "200": { "description": "Stock transactions retrieved", "example": { "transactions": [ { "id": "stock_txn_123", "symbol": "RELIANCE", "type": "buy", "shares": 10, "price": 2500, "total": 25000, "timestamp": "2025-09-20T10:30:00.000Z" } ] } } } }, { "method": "POST", "path": "/game/stock-portfolio/buy", "description": "Buy stocks", "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer JWT token" } ], "requestBody": { "example": { "symbol": "TCS", "shares": 5, "price": 3200 } }, "responses": { "200": { "description": "Stock purchase successful", "example": { "success": true, "transaction": { "symbol": "TCS", "shares": 5, "price": 3200, "total": 16000, "newBankBalance": 4000 } } } } }, { "method": "POST", "path": "/game/stock-portfolio/sell", "description": "Sell stocks", "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer JWT token" } ], "requestBody": { "example": { "symbol": "TCS", "shares": 2, "price": 3300 } }, "responses": { "200": { "description": "Stock sale successful", "example": { "success": true, "transaction": { "symbol": "TCS", "shares": 2, "price": 3300, "total": 6600, "newBankBalance": 10600, "gainLoss": 200 } } } } } ] }, { "name": "Game Sync", "description": "Data synchronization and onboarding status", "endpoints": [ { "method": "GET", "path": "/game/sync", "description": "Sync all player data", "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer JWT token" } ], "responses": { "200": { "description": "All player data synchronized", "example": { "playerState": { "rupees": 1000, "bankBalance": 5000 }, "bankAccount": { "balance": 5000, "accountNumber": "DHAN123456789" }, "portfolio": { "totalValue": 26500 }, "fixedDeposits": { "active": 2, "totalAmount": 15000 } } } } }, { "method": "GET", "path": "/game/bank-onboarding/status", "description": "Get bank onboarding progress status", "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer JWT token" } ], "responses": { "200": { "description": "Bank onboarding status", "example": { "hasAccount": true, "hasDeposited": true, "hasWithdrawn": false, "completionPercentage": 67 } } } } ] }, { "name": "Admin Panel", "description": "Administrative endpoints for game management", "endpoints": [ { "method": "GET", "path": "/admin/summary", "description": "Get admin dashboard summary", "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Admin JWT token" } ], "responses": { "200": { "description": "Admin summary data", "example": { "totalPlayers": 1250, "activePlayers": 89, "totalTransactions": 5643, "systemHealth": "good" } } } }, { "method": "GET", "path": "/admin/active-players", "description": "Get list of currently active players", "responses": { "200": { "description": "Active players list", "example": { "players": [ { "username": "player1", "level": 5, "lastActivity": "2025-09-23T10:30:00.000Z" } ] } } } }, { "method": "POST", "path": "/admin/ban", "description": "Ban a player", "requestBody": { "example": { "playerId": "player_123", "reason": "Violation of terms", "duration": "24h" } }, "responses": { "200": { "description": "Player banned successfully" } } }, { "method": "POST", "path": "/admin/announce", "description": "Send announcement to all players", "requestBody": { "example": { "message": "Server maintenance in 30 minutes", "type": "warning" } }, "responses": { "200": { "description": "Announcement sent successfully" } } } ] } ] }