llmsdottxt

This guide helps AI models understand how to build games using the games.fun platform SDKs.

Packages

@games-fun/sdk

Core SDK for game integration
Token transfers and validation
Authentication and state management
Development mode for testing

@games-fun/react

React hooks and components
Context provider for SDK
State management utilities
Built-in UI components

@games-fun/server-sdk

Game server utilities
Wallet management
JWT verification
WebSocket helpers

Installation

# Core SDK (required)
npm install @games-fun/sdk

# React bindings (optional)
npm install @games-fun/react

# Server SDK (for game servers)
npm install @games-fun/server-sdk

Core Integration Steps

1. Game Wallet Setup

Get API key after deploying game
Create or get game wallet:

// Create new wallet
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;

// Or get existing wallet
const response = await fetch('https://games.fun/api/games/wallet', {
    headers: {
        'x-api-key': 'your-games-fun-api-key'
    }
});
const { wallet } = await response.json();

Store wallet address for token transfers

2. Authentication Setup

Server setup - get public key:

// On server startup
const response = await fetch('https://games.fun/api/games/auth/keys');
const { 
    public_key, 
    algorithm,  // 'RS256'
    issuer     // 'games.fun'
} = await response.json();

// Store for token verification
const verifyPlayerToken = async (token) => {
    const result = await JWTUtils.verifyToken(token, public_key, {
        issuer,
        algorithms: [algorithm]
    });
    return result;
};

Client authentication:

// Request JWT token
const result = await sdk.triggerAction("issueJWT", {});
const jwt = result.params.jwt;

// Use with game server
gameServer.setJWT(jwt);

// JWT payload structure
{
    sub: "player-id",    // Player ID
    iss: "games.fun",    // Token issuer
    exp: 1234567890,     // Expiration timestamp
    iat: 1234567890      // Issued at timestamp
}

WebSocket authentication:

// Client connection
gameServer.connect(sdk.getConnection().privyId);
gameServer.setJWT(jwt);

// Server validation
ws.on('message', async (data) => {
    const { jwt } = data;
    const authResult = await verifyPlayerToken(jwt);
    if (!authResult.valid) {
        throw new Error('Authentication required');
    }
    // Process authenticated message...
});

3. Token Transfer Flow

Client initializes SDK with validation endpoint:

const sdk = new GamesFunSDK({
    gameServerUrl: "https://your-game.com/api/validate", // Hit on validation
    onConnect: (connection) => {
        console.log('Connected:', connection);
    }
});

Client triggers transfer:

const result = await sdk.triggerAction("transferTokens", {
    recipient: gameWalletAddress,
    amount: tokenAmount,
    itemId: "shield" // Optional context
});

Platform validates and hits your endpoint:

// POST https://your-game.com/api/validate
{
    actionName: "transferTokens",
    requestId: "unique-id",
    params: {
        signature: "tx-signature",
        sender: "player-wallet",
        recipient: "game-wallet",
        token: "token-mint",
        amount: tokenAmount,
        itemId: "shield" // Original context preserved
    }
}

Your server processes validation:

app.post('/api/validate', async (req, res) => {
    // Validate origin
    const origin = req.headers.origin;
    if (process.env.NODE_ENV === 'production' && origin !== 'https://games.fun') {
        return res.status(403).json({ error: 'Unauthorized origin' });
    }

    const { actionName, params } = req.body;
    
    if (actionName === 'transferTokens') {
        // Verify transfer details
        const { sender, recipient, amount, token } = params;
        
        // Validate recipient
        if (recipient !== gameWalletAddress) {
            return res.status(400).json({ error: 'Invalid recipient' });
        }

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

        // Validate amount
        const transferAmount = parseInt(amount);
        if (isNaN(transferAmount) || transferAmount <= 0) {
            return res.status(400).json({ error: 'Invalid amount' });
        }
        
        // Update game state
        const points = transferAmount * POINTS_PER_TOKEN;
        await updatePlayerBalance(sender, points);
        
        // Send success
        res.json({ success: true });
        
        // Broadcast state update via WebSocket
        wss.clients.forEach(client => {
            if (client.playerId === sender) {
                client.send(JSON.stringify({
                    type: 'state_update',
                    balance: points
                }));
            }
        });
    }
});

Initial Setup

Deploy your game to get an API key
Create a game wallet to receive token transfers:

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;

Core Concepts

Token System

Players transfer tokens to game wallet
Games can:
- Convert tokens to points with custom ratio
- Sell items directly for tokens
- Use any token-based economy
All conversions handled by game server

Action Validation

Platform verifies token transfers on chain
Forwards validation to game server
Includes transfer details and context
One-time-only credit of points/items

Authentication

JWT-based auth for game actions
Required for purchases/withdrawals
Tokens verified with RS256

Authentication Flow

1. Server Setup

First, get the platform's public key for JWT verification:

// On server startup
const setupAuth = async () => {
    // Get public key and auth config
    const response = await fetch('https://games.fun/api/games/auth/keys');
    const { 
        public_key, 
        algorithm,  // 'RS256'
        issuer     // 'games.fun'
    } = await response.json();

    // Create verification function
    const verifyPlayerToken = async (token: string) => {
        try {
            const result = await JWTUtils.verifyToken(token, public_key, {
                issuer,
                algorithms: [algorithm]
            });

            if (!result.valid || !result.payload) {
                throw new Error(result.error || 'Invalid token');
            }

            // Check expiration
            if (result.payload.exp && Date.now() >= result.payload.exp * 1000) {
                throw new Error('Token expired');
            }

            return {
                valid: true,
                playerId: result.payload.sub,
                permissions: result.payload.permissions
            };
        } catch (error) {
            return {
                valid: false,
                error: error instanceof Error ? error.message : 'Verification failed'
            };
        }
    };

    return { verifyPlayerToken };
};

2. Client Implementation

Vanilla JavaScript:

// Initialize SDK with game server URL
const sdk = new GamesFunSDK({
    gameServerUrl: "your-validation-endpoint",
    onConnect: (connection) => {
        console.log('Connected:', connection);
    }
});

// Register auth action
sdk.registerActions({
    issueJWT: "Get JWT authentication token"
});

// Authentication handler
const auth = {
    token: null,
    isAuthenticated: false,

    getAuthToken: async () => {
        try {
            const result = await sdk.triggerAction("issueJWT", {});
            if (result.params?.jwt) {
                auth.token = result.params.jwt;
                auth.isAuthenticated = true;
                gameServer.setJWT(result.params.jwt);
                return result.params.jwt;
            }
            throw new Error("Failed to get JWT");
        } catch (error) {
            auth.logout();
            throw error;
        }
    },

    logout: () => {
        auth.token = null;
        auth.isAuthenticated = false;
        gameServer.setJWT(null);
    },

    handleAuthError: async (error) => {
        if (error.message.includes('Authentication') || 
            error.message.includes('expired')) {
            auth.logout();
            // Optionally retry with new token
            await auth.getAuthToken();
        }
    }
};

React Implementation:

function useAuth() {
    const { triggerAction } = useGamesFun();
    const [isAuthenticated, setIsAuthenticated] = useState(false);
    const [authToken, setAuthToken] = useState<string | null>(null);
    const gameServerRef = useRef<GameServer | null>(null);

    const getAuthToken = async () => {
        try {
            const result = await triggerAction("issueJWT", {});
            if (result.params?.jwt) {
                setAuthToken(result.params.jwt);
                setIsAuthenticated(true);
                gameServerRef.current?.setJWT(result.params.jwt);
                return result.params.jwt;
            }
            throw new Error("Failed to get JWT");
        } catch (error) {
            logout();
            throw error;
        }
    };

    const logout = () => {
        setAuthToken(null);
        setIsAuthenticated(false);
        gameServerRef.current?.setJWT(null);
    };

    // Auto-refresh handler
    useEffect(() => {
        if (authToken) {
            // Decode token without verification
            const payload = JWTUtils.decodeToken(authToken);
            if (payload.exp) {
                const timeout = (payload.exp * 1000) - Date.now() - 60000; // Refresh 1 min early
                const refreshTimer = setTimeout(getAuthToken, timeout);
                return () => clearTimeout(refreshTimer);
            }
        }
    }, [authToken]);

    return { isAuthenticated, authToken, getAuthToken, logout };
}

3. WebSocket Authentication

// Client-side setup
const gameServer = new GameServer('wss://your-game-server');

// Set token before or after connection
gameServer.setJWT(authToken);
gameServer.connect(sdk.getConnection().privyId);

// Server-side handling
wss.on('connection', (ws) => {
    let isAuthenticated = false;
    let playerId = null;

    ws.on('message', async (data) => {
        const message = JSON.parse(data);

        // Handle authentication
        if (message.type === 'authenticate') {
            const authResult = await verifyPlayerToken(message.token);
            if (authResult.valid) {
                isAuthenticated = true;
                playerId = authResult.playerId;
                ws.send(JSON.stringify({
                    type: 'auth_status',
                    isAuthenticated: true
                }));
            } else {
                ws.send(JSON.stringify({
                    type: 'auth_status',
                    isAuthenticated: false,
                    error: authResult.error
                }));
            }
            return;
        }

        // Require auth for protected actions
        if (!isAuthenticated && message.type !== 'register') {
            ws.send(JSON.stringify({
                type: 'error',
                error: 'Authentication required'
            }));
            return;
        }

        // Handle authenticated messages...
    });
});

4. Error Handling

// Client-side error handling
try {
    await gameServer.purchaseItem(itemId, price);
} catch (error) {
    if (error.message.includes('Authentication')) {
        // Token expired or invalid
        auth.logout();
        // Get new token and retry
        const newToken = await auth.getAuthToken();
        if (newToken) {
            await gameServer.purchaseItem(itemId, price);
        }
    }
}

// Server-side error handling
const handleAuthenticatedRequest = async (req, res) => {
    try {
        const { jwt } = req.headers;
        const authResult = await verifyPlayerToken(jwt);
        
        if (!authResult.valid) {
            return res.status(401).json({
                error: 'Authentication failed',
                details: authResult.error,
                shouldReauth: authResult.error === 'Token expired'
            });
        }

        // Process authenticated request...
    } catch (error) {
        if (error.name === 'JsonWebTokenError') {
            return res.status(401).json({
                error: 'Invalid token format'
            });
        }
        if (error.name === 'TokenExpiredError') {
            return res.status(401).json({
                error: 'Token expired',
                shouldReauth: true
            });
        }
        // Handle other errors...
    }
};

Validation Flow

When a player transfers tokens:

Client triggers action:

const result = await sdk.triggerAction("transferTokens", {
    recipient: gameWalletAddress,
    amount: tokenAmount,
    // Optional context
    itemId: "shield",
    source: "shop"
});

Platform validates and forwards:

// POST /api/actions/validate
{
    actionName: "transferTokens",
    requestId: "unique-id",
    params: {
        // Transaction data
        signature: "tx-signature",
        sender: "player-wallet",
        recipient: "game-wallet",
        token: "token-mint", // Must match GAME_TOKEN_MINT
        amount: tokenAmount,

        // Optional context preserved
        itemId: "shield",
        source: "shop",
        metadata: {
            category: "powerup",
            duration: 30
        }
    }
}

Game server validates and processes:

// 1. Validate token and amount
const { token, amount, recipient } = params;
if (token !== process.env.GAME_TOKEN_MINT) {
    throw new Error('Invalid token');
}
if (recipient !== gameWalletAddress) {
    throw new Error('Invalid recipient');
}

// 2. Process validation result
if (params.verified) {
    const validatedTransfer = params.validatedTransfer;
    const points = parseInt(validatedTransfer.amount) * POINTS_PER_TOKEN;
    
    // Update state based on context
    if (params.itemId) {
        state.inventory[params.itemId]++;
        state.coins += points - params.metadata.price;
    } else {
        state.coins += points;
    }
}

// 3. Send state update
ws.send(JSON.stringify({
    type: 'state_update',
    state: {
        coins: state.coins,
        inventory: state.inventory,
        lastAction: {
            type: 'transfer',
            source: params.source,
            itemId: params.itemId
        }
    }
}));

Game server sends state update:

ws.send(JSON.stringify({
    type: 'state_update',
    state: {
        coins: gameState.coins,
        inventory: gameState.inventory
    }
}));

Vanilla JavaScript Integration

import { GamesFunSDK } from '@games-fun/sdk';
import { GameServer } from './gameServer';

// 1. Initialize SDK
const sdk = new GamesFunSDK({
    debug: true,
    gameServerUrl: "your-validation-endpoint",
    onConnect: (connection) => {
        console.log('Connected:', connection);
    }
});

// 2. Register actions
sdk.registerActions({
    transferTokens: "Transfer tokens to game wallet",
    validateTransfer: "Validate existing token transfer",
    issueJWT: "Get JWT authentication token"
});

// 3. Connect to game server
const gameServer = new GameServer('wss://your-game-server');
gameServer.connect(sdk.getConnection().privyId);

// 4. Handle token transfers
const handlePurchase = async (itemId, price) => {
    const result = await sdk.triggerAction("transferTokens", {
        recipient: gameWalletAddress,
        amount: price,
        itemId,
        source: "shop"
    });
    console.log('Purchase successful:', result);
};

React Integration

import { GamesFunProvider, useGamesFun, useGamesFunActions } from '@games-fun/react';

// 1. Wrap app with provider
function App() {
    return (
        <GamesFunProvider 
            options={{ 
                debug: true,
                gameServerUrl: "your-validation-endpoint"
            }}
        >
            <Game />
        </GamesFunProvider>
    );
}

// 2. Use hooks in components
function Game() {
    const { connection } = useGamesFun();
    const actions = useGamesFunActions({
        transferTokens: "Transfer tokens to game wallet",
        issueJWT: "Get JWT authentication token"
    });

    const handlePurchase = async (itemId, price) => {
        await actions.transferTokens({
            recipient: gameWalletAddress,
            amount: price,
            itemId,
            source: "shop"
        });
    };

    return (
        <div>
            <h1>Game</h1>
            <button onClick={() => handlePurchase("shield", 100)}>
                Buy Shield
            </button>
        </div>
    );
}

Game Server Integration

import { WalletClient, JWTUtils } from '@games-fun/server-sdk';
import WebSocket from 'ws';

// 1. Initialize wallet client
const walletClient = new WalletClient({
    apiKey: process.env.GAMES_FUN_API_KEY
});

// 2. Set up WebSocket server
const wss = new WebSocket.Server({ port: 3001 });
const gameManager = new GameManager();

// 3. Handle connections
wss.on('connection', (ws) => {
    ws.on('message', async (data) => {
        // Handle player registration
        if (data.type === 'register') {
            const state = gameManager.getState(data.playerId);
            ws.send({
                type: 'init',
                state,
                config: gameConfig
            });
        }
        
        // Handle action validation
        if (data.type === 'validate_action') {
            const { actionName, params } = data;
            
            // Verify JWT for authenticated actions
            if (params.jwt) {
                const jwtResult = await JWTUtils.verifyToken(params.jwt);
                if (!jwtResult.valid) {
                    throw new Error('Invalid token');
                }
            }
            
            // Process transfer validation
            if (actionName === 'transferTokens') {
                const { amount, token, sender } = params;

                // Validate token
                if (token !== process.env.GAME_TOKEN_MINT) {
                    throw new Error('Invalid token');
                }

                // Convert to points
                const points = parseInt(amount) * POINTS_PER_TOKEN;
                const state = gameManager.getState(sender);
                
                // Update state based on context
                if (params.itemId) {
                    state.inventory[params.itemId]++;
                } else {
                    state.coins += points;
                }
                
                // Broadcast update
                ws.send({
                    type: 'state_update',
                    state
                });
            }
        }
    });
});

Token Withdrawal Flow

When a player wants to withdraw points as tokens:

Client requests withdrawal:

// Using vanilla SDK
await gameServer.withdrawTokens(playerWallet, pointAmount);

// Using React hooks
const handleWithdraw = async (amount) => {
    if (amount < 10) { // Minimum 10 points = 1 token
        throw new Error('Minimum withdrawal is 10 points');
    }
    
    // Convert points to tokens
    const tokenAmount = Math.floor(amount / POINTS_PER_TOKEN);
    await gameServer.withdrawTokens(playerWallet, amount);
};

Game server processes withdrawal:

// Server-side handling
if (data.type === 'withdraw_request') {
    // Verify JWT
    const jwtResult = await verifyPlayerToken(data.jwt);
    if (!jwtResult.valid) {
        throw new Error('Invalid token');
    }

    const { recipient, amount } = data;
    const state = gameManager.getState(playerId);
    
    if (state.coins < amount) {
        throw new Error('Insufficient points');
    }

    // Convert points to tokens
    const tokenAmount = Math.floor(amount / POINTS_PER_TOKEN);
    
    // Send tokens to player
    await walletClient.sendToken({
        recipient,
        amount: tokenAmount.toString(),
        tokenMint: process.env.GAME_TOKEN_MINT, // Must match token used in deposits
        token: process.env.GAME_TOKEN_MINT // Validate token matches
    });
    
    // Update state
    state.coins -= amount;
    
    // Send updates
    ws.send(JSON.stringify({
        type: 'state_update',
        state
    }));
}

Development Mode

Enable dev mode for testing:

const sdk = new GamesFunSDK({
    dev: {
        enabled: true,
        mock: {
            wallet: {
                address: 'ED5nyyWEzpPPiWimP8vYm7sD7TD3LAt3Q3gRTWHzPJBY',
                tokenBalance: '1000',
                solBalance: '10',
                privyId: '123'
            }
        },
        validation: {
            auto: true,
            makeRequest: true
        }
    }
});

Error Handling

// Client-side errors
try {
    await sdk.triggerAction("transferTokens", params);
} catch (error) {
    if (error.code === 'NO_WALLET') {
        // Wallet not connected
    } else if (error.code === 'INSUFFICIENT_BALANCE') {
        // Not enough tokens
    } else if (error.message.includes('Authentication')) {
        // JWT expired
        gameServer.setJWT(null);
    }
}

// Server-side errors
try {
    const response = await fetch('/api/games/wallet');
    if (!response.ok) {
        if (response.status === 401) {
            // Invalid API key
        } else if (response.status === 404) {
            // Create game wallet
            await createGameWallet();
        }
    }
} catch (error) {
    // Network errors
}

This guide covers everything needed to integrate games with the games.fun platform, with specific patterns for vanilla JS, React, and game server implementations.

PreviousSecurity Guide