Game Wallet

Each game on Games.fun has its own wallet that receives and manages player tokens. Your game wallet is the foundation for implementing token-based mechanics - players transfer tokens to it, and you convert them to points, items, or any in-game value.

The game wallet provides:

• Secure token storage

• Point conversion system

• Withdrawal capabilities

• Real-time balance tracking

Game Wallet Setup

First, create a wallet to receive player tokens:

// Using your API key
const response = await fetch('https://games.fun/api/games/wallet', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your-games-fun-api-key'
    }
});

const { wallet } = await response.json();
const gameWalletAddress = wallet.address;

Store this wallet address - players will transfer tokens to it.

Token Transfers

Client Side

Players transfer tokens using the SDK:

// Basic transfer
const result = await sdk.triggerAction("transferTokens", {
    recipient: gameWalletAddress,
    amount: tokenAmount
});

// Transfer with context (e.g., buying an item)
const result = await sdk.triggerAction("transferTokens", {
    recipient: gameWalletAddress,
    amount: price,
    itemId: "shield",
    source: "shop",
    metadata: {
        category: "powerup",
        duration: 30
    }
});

Server Side

Your server validates and processes transfers:

app.post('/api/validate', async (req, res) => {
    const { actionName, params } = req.body;
    
    if (actionName === 'transferTokens') {
        // 1. Validate transfer details
        const { sender, recipient, amount, token } = params;
        
        // Check recipient
        if (recipient !== gameWalletAddress) {
            return res.status(400).json({ error: 'Invalid recipient' });
        }

        // Check token type
        if (token !== process.env.GAME_TOKEN_MINT) {
            return res.status(400).json({ error: 'Invalid token' });
        }

        // 2. Convert to game points (e.g., 1 token = 10 points)
        const points = parseInt(amount) * POINTS_PER_TOKEN;
        
        // 3. Update player state
        const state = await updatePlayerBalance(sender, points);
        
        // 4. Send success response
        res.json({ success: true });
        
        // 5. Broadcast state update
        wss.clients.forEach(client => {
            if (client.playerId === sender) {
                client.send(JSON.stringify({
                    type: 'state_update',
                    state
                }));
            }
        });
    }
});

Point System

You can implement any point conversion system. Here's a basic example:

const POINTS_PER_TOKEN = 10; // 1 token = 10 points

class GameState {
    coins: number = 0;
    inventory: Record<string, number> = {};

    addPoints(amount: number) {
        this.coins += amount;
    }

    usePoints(amount: number): boolean {
        if (this.coins < amount) return false;
        this.coins -= amount;
        return true;
    }

    addItem(itemId: string) {
        this.inventory[itemId] = (this.inventory[itemId] || 0) + 1;
    }
}

Withdrawals

Let players withdraw their points back as tokens:

// Client side
const handleWithdraw = async (amount: number) => {
    if (amount < 10) { // Minimum 10 points = 1 token
        throw new Error('Minimum withdrawal is 10 points');
    }
    
    const tokenAmount = Math.floor(amount / POINTS_PER_TOKEN);
    await gameServer.withdrawTokens(playerWallet, amount);
};

// Server side
if (data.type === 'withdraw_request') {
    const { recipient, amount } = data;
    
    // 1. Check balance
    const state = gameManager.getState(playerId);
    if (state.coins < amount) {
        throw new Error('Insufficient points');
    }

    // 2. Convert points to tokens
    const tokenAmount = Math.floor(amount / POINTS_PER_TOKEN);
    
    // 3. Send tokens
    await walletClient.sendToken({
        recipient,
        amount: tokenAmount.toString(),
        tokenMint: process.env.GAME_TOKEN_MINT
    });
    
    // 4. Update state
    state.coins -= amount;
    
    // 5. Send update
    ws.send(JSON.stringify({
        type: 'state_update',
        state
    }));
}

Error Handling

Handle common token scenarios:

try {
    await sdk.triggerAction("transferTokens", params);
} catch (error) {
    switch (error.code) {
        case 'NO_WALLET':
            alert('Please connect your wallet');
            break;
        case 'INSUFFICIENT_BALANCE':
            alert('Not enough tokens');
            break;
        case 'INVALID_AMOUNT':
            alert('Invalid amount');
            break;
        default:
            console.error('Transfer failed:', error);
    }
}

Development Mode

Test token flows without real transfers:

const sdk = new GamesFunSDK({
    dev: {
        enabled: true,
        mock: {
            wallet: {
                tokenBalance: '1000', // Test with 1000 tokens
                solBalance: '10'
            }
        },
        validation: {
            auto: true, // Auto-validate transfers
            makeRequest: true // Still hit your server
        }
    }
});

Best Practices

1. Validation

   • Always verify token type

   • Validate amounts and recipients

   • Check for duplicate transfers

   • Use atomic transactions

2. State Management

   • Keep real-time balances

   • Handle disconnections

   • Sync client/server state

   • Log all transfers

3. User Experience

   • Show clear token/point values

   • Explain conversion rates

   • Provide transaction history

   • Handle errors gracefully

Next Steps

• Game Server - Set up your game server

• React Integration - Use with React components

• Development Guide - Testing and deployment