═══════════════════════════════════════════════════════════════════════════════
ARCADIA GAME SDK - DEVELOPER DOCUMENTATION
═══════════════════════════════════════════════════════════════════════════════
Document: Examples
Generated: 2/13/2026, 7:31:45 PM
Version: 1.0.0
═══════════════════════════════════════════════════════════════════════════════
Examples
══════════════════════════════════════════════════════════════════════
Complete, working examples for common use cases with the Arcadia Game SDK.
Table of Contents
════════════════════════════════════════════════════════════
• Basic Integration
• Wallet Integration
• Pay-to-Play
• In-Game Purchases
• Complete Game Example
• TypeScript Example
• Error Handling
Basic Integration
════════════════════════════════════════════════════════════
Minimal example showing SDK initialization and wallet address retrieval.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CODE BLOCK [HTML]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Basic SDK Integration
Initializing...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Wallet Integration
════════════════════════════════════════════════════════════
Complete wallet integration with change listeners.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CODE BLOCK [TYPESCRIPT]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
import { ArcadiaSDK, WalletNotConnectedError } from '@arcadiasol/sdk';
class WalletManager {
private arcadia: ArcadiaSDK;
private walletAddress: string | null = null;
private onConnectCallbacks: Array<(address: string) => void> = [];
private onDisconnectCallbacks: Array<() => void> = [];
constructor(gameId: string) {
this.arcadia = new ArcadiaSDK({ gameId });
}
async initialize() {
await this.arcadia.init();
// Get initial wallet address
this.walletAddress = await this.arcadia.getWalletAddress();
// Listen for wallet changes
this.arcadia.onWalletChange((connected, address) => {
if (connected && address) {
this.handleConnect(address);
} else {
this.handleDisconnect();
}
});
return this.walletAddress;
}
private handleConnect(address: string) {
const wasConnected = this.walletAddress !== null;
this.walletAddress = address;
if (!wasConnected) {
// First connection
this.onConnectCallbacks.forEach(cb => cb(address));
} else if (this.walletAddress !== address) {
// Wallet changed
this.onDisconnectCallbacks.forEach(cb => cb());
this.onConnectCallbacks.forEach(cb => cb(address));
}
}
private handleDisconnect() {
if (this.walletAddress) {
this.walletAddress = null;
this.onDisconnectCallbacks.forEach(cb => cb());
}
}
onConnect(callback: (address: string) => void) {
this.onConnectCallbacks.push(callback);
}
onDisconnect(callback: () => void) {
this.onDisconnectCallbacks.push(callback);
}
getAddress(): string | null {
return this.walletAddress;
}
}
// Usage
const walletManager = new WalletManager('your-game-id');
await walletManager.initialize();
walletManager.onConnect((address) => {
console.log('Wallet connected:', address);
loadPlayerData(address);
});
walletManager.onDisconnect(() => {
console.log('Wallet disconnected');
saveGameState();
pauseGame();
});
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Pay-to-Play
════════════════════════════════════════════════════════════
Complete pay-to-play implementation with verification.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CODE BLOCK [TYPESCRIPT]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
import { ArcadiaSDK, PaymentFailedError, WalletNotConnectedError } from '@arcadiasol/sdk';
class PayToPlayManager {
private arcadia: ArcadiaSDK;
private walletAddress: string | null = null;
private hasPaid: boolean = false;
constructor(gameId: string) {
this.arcadia = new ArcadiaSDK({ gameId });
}
async initialize() {
await this.arcadia.init();
this.walletAddress = await this.arcadia.getWalletAddress();
if (!this.walletAddress) {
throw new WalletNotConnectedError();
}
// Check if already paid
this.hasPaid = await this.checkPaymentStatus(this.walletAddress);
}
async checkPaymentRequired(): Promise {
return !this.hasPaid;
}
async processPayment(amount: number, token: 'SOL' | 'USDC'): Promise {
if (!this.walletAddress) {
throw new WalletNotConnectedError();
}
try {
showLoading('Processing payment...');
const result = await this.arcadia.payment.payToPlay(amount, token);
// Verify payment
if (!result.success || result.amount !== amount) {
throw new PaymentFailedError('Payment verification failed');
}
// Mark as paid
await this.markAsPaid(this.walletAddress, result);
this.hasPaid = true;
// Log payment
await this.logPayment(result);
return true;
} catch (error) {
if (error instanceof PaymentFailedError) {
showError('Payment failed: ' + error.message);
} else if (error instanceof WalletNotConnectedError) {
showError('Please connect your wallet');
} else {
showError('An error occurred');
}
return false;
} finally {
hideLoading();
}
}
private async checkPaymentStatus(walletAddress: string): Promise {
const response = await fetch([/api/payment-status?wallet=${walletAddress}]);
const data = await response.json();
return data.hasPaid || false;
}
private async markAsPaid(walletAddress: string, result: PaymentResult) {
await fetch('/api/mark-paid', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
walletAddress,
txSignature: result.txSignature,
amount: result.amount,
token: result.token,
timestamp: result.timestamp,
}),
});
}
private async logPayment(result: PaymentResult) {
await fetch('/api/analytics/payment', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(result),
});
}
}
// Usage
const paymentManager = new PayToPlayManager('your-game-id');
await paymentManager.initialize();
if (await paymentManager.checkPaymentRequired()) {
const paid = await paymentManager.processPayment(0.5, 'SOL');
if (paid) {
startGame();
}
} else {
startGame();
}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
In-Game Purchases
════════════════════════════════════════════════════════════
Complete item shop implementation.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CODE BLOCK [TYPESCRIPT]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
import { ArcadiaSDK, PaymentFailedError } from '@arcadiasol/sdk';
interface ShopItem {
id: string;
name: string;
price: number;
token: 'SOL' | 'USDC';
description: string;
}
class ItemShop {
private arcadia: ArcadiaSDK;
private walletAddress: string | null = null;
private inventory: string[] = [];
constructor(gameId: string) {
this.arcadia = new ArcadiaSDK({ gameId });
}
async initialize() {
await this.arcadia.init();
this.walletAddress = await this.arcadia.getWalletAddress();
this.inventory = await this.loadInventory(this.walletAddress!);
}
async purchaseItem(item: ShopItem): Promise {
if (!this.walletAddress) {
showError('Please connect your wallet');
return false;
}
try {
showLoading([Purchasing ${item.name}...]);
const result = await this.arcadia.payment.purchaseItem(
item.id,
item.price,
item.token
);
// Verify purchase
if (!result.success ||
result.amount !== item.price ||
result.token !== item.token) {
throw new PaymentFailedError('Purchase verification failed');
}
// Add to inventory
this.inventory.push(item.id);
await this.saveInventory(this.walletAddress, this.inventory);
// Log purchase
await this.logPurchase(item, result);
showSuccess([${item.name} purchased!]);
return true;
} catch (error) {
if (error instanceof PaymentFailedError) {
showError('Purchase failed: ' + error.message);
} else {
showError('An error occurred');
}
return false;
} finally {
hideLoading();
}
}
hasItem(itemId: string): boolean {
return this.inventory.includes(itemId);
}
private async loadInventory(walletAddress: string): Promise {
const response = await fetch([/api/inventory?wallet=${walletAddress}]);
const data = await response.json();
return data.inventory || [];
}
private async saveInventory(walletAddress: string, inventory: string[]) {
await fetch('/api/inventory', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ walletAddress, inventory }),
});
}
private async logPurchase(item: ShopItem, result: PaymentResult) {
await fetch('/api/analytics/purchase', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
itemId: item.id,
itemName: item.name,
...result,
}),
});
}
}
// Usage
const shop = new ItemShop('your-game-id');
await shop.initialize();
const item: ShopItem = {
id: 'sword-001',
name: 'Legendary Sword',
price: 1.0,
token: 'SOL',
description: 'A powerful sword',
};
const purchased = await shop.purchaseItem(item);
if (purchased) {
console.log('Item added to inventory!');
}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Complete Game Example
════════════════════════════════════════════════════════════
Full game integration with wallet, payments, and save data.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CODE BLOCK [TYPESCRIPT]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
import { ArcadiaSDK, WalletNotConnectedError, PaymentFailedError } from '@arcadiasol/sdk';
class Game {
private arcadia: ArcadiaSDK;
private walletAddress: string | null = null;
private playerData: any = null;
private shop: ItemShop;
constructor(gameId: string) {
this.arcadia = new ArcadiaSDK({ gameId });
this.shop = new ItemShop(gameId);
}
async initialize() {
// Initialize SDK
await this.arcadia.init();
// Get wallet address
this.walletAddress = await this.arcadia.getWalletAddress();
if (!this.walletAddress) {
throw new WalletNotConnectedError();
}
// Load or create player data
this.playerData = await this.loadOrCreatePlayerData(this.walletAddress);
// Initialize shop
await this.shop.initialize();
// Set up wallet change listener
this.arcadia.onWalletChange((connected, address) => {
this.handleWalletChange(connected, address);
});
// Check payment requirement
if (this.gameRequiresPayment() && !this.playerData.hasPaid) {
await this.handlePayToPlay();
}
// Start game
this.start();
}
private async handlePayToPlay() {
const amount = 0.5;
const token = 'SOL';
try {
const result = await this.arcadia.payment.payToPlay(amount, token);
if (result.success && result.amount === amount) {
this.playerData.hasPaid = true;
await this.savePlayerData(this.walletAddress!, this.playerData);
showSuccess('Payment successful!');
}
} catch (error) {
if (error instanceof PaymentFailedError) {
showError('Payment failed: ' + error.message);
}
throw error;
}
}
private handleWalletChange(connected: boolean, address: string | null) {
if (!connected) {
this.saveGameState();
this.pause();
showMessage('Wallet disconnected. Please reconnect.');
} else if (address && address !== this.walletAddress) {
// Different wallet
this.saveGameState();
this.walletAddress = address;
this.loadPlayerData(address);
}
}
private async loadOrCreatePlayerData(walletAddress: string) {
const existing = await this.loadPlayerData(walletAddress);
if (existing) {
return existing;
}
const newData = {
walletAddress,
level: 1,
score: 0,
inventory: [],
hasPaid: false,
};
await this.savePlayerData(walletAddress, newData);
return newData;
}
private async loadPlayerData(walletAddress: string) {
const response = await fetch([/api/player-data?wallet=${walletAddress}]);
if (response.ok) {
return response.json();
}
return null;
}
private async savePlayerData(walletAddress: string, data: any) {
await fetch('/api/player-data', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ walletAddress, data }),
});
}
private saveGameState() {
if (this.walletAddress && this.playerData) {
this.savePlayerData(this.walletAddress, this.playerData);
}
}
private gameRequiresPayment(): boolean {
return true; // Your logic
}
private start() {
console.log('Game started!');
}
private pause() {
console.log('Game paused');
}
}
// Initialize game
const game = new Game('your-game-id');
game.initialize().catch(error => {
console.error('Game initialization failed:', error);
});
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TypeScript Example
════════════════════════════════════════════════════════════
Type-safe implementation with full TypeScript support.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CODE BLOCK [TYPESCRIPT]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
import {
ArcadiaSDK,
SDKConfig,
PaymentResult,
WalletNotConnectedError,
PaymentFailedError,
} from '@arcadiasol/sdk';
interface PlayerData {
walletAddress: string;
level: number;
score: number;
inventory: string[];
hasPaid: boolean;
}
class TypedGameManager {
private arcadia: ArcadiaSDK;
private walletAddress: string | null = null;
private playerData: PlayerData | null = null;
constructor(config: SDKConfig) {
this.arcadia = new ArcadiaSDK(config);
}
async initialize(): Promise {
await this.arcadia.init();
this.walletAddress = await this.arcadia.getWalletAddress();
if (!this.walletAddress) {
throw new WalletNotConnectedError();
}
this.playerData = await this.loadPlayerData(this.walletAddress);
}
async processPayment(amount: number, token: 'SOL' | 'USDC'): Promise {
if (!this.walletAddress) {
throw new WalletNotConnectedError();
}
try {
const result: PaymentResult = await this.arcadia.payment.payToPlay(amount, token);
if (!result.success || result.amount !== amount) {
throw new PaymentFailedError('Payment verification failed');
}
return result;
} catch (error) {
if (error instanceof PaymentFailedError) {
throw error;
}
throw new PaymentFailedError('Payment failed');
}
}
private async loadPlayerData(walletAddress: string): Promise {
// Implementation
return {
walletAddress,
level: 1,
score: 0,
inventory: [],
hasPaid: false,
};
}
}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Error Handling
════════════════════════════════════════════════════════════
Complete error handling example.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CODE BLOCK [TYPESCRIPT]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
import {
ArcadiaSDK,
WalletNotConnectedError,
PaymentFailedError,
TimeoutError,
InvalidAmountError,
InvalidTokenError,
} from '@arcadiasol/sdk';
class ErrorHandlingExample {
private arcadia: ArcadiaSDK;
constructor(gameId: string) {
this.arcadia = new ArcadiaSDK({ gameId });
}
async safeGetWalletAddress(): Promise {
try {
return await this.arcadia.getWalletAddress();
} catch (error) {
if (error instanceof TimeoutError) {
console.warn('Request timed out, retrying...');
// Retry logic
return await this.arcadia.getWalletAddress();
}
console.error('Failed to get wallet address:', error);
return null;
}
}
async safePayment(amount: number, token: 'SOL' | 'USDC'): Promise {
try {
return await this.arcadia.payment.payToPlay(amount, token);
} catch (error) {
if (error instanceof WalletNotConnectedError) {
showError('Please connect your wallet');
} else if (error instanceof PaymentFailedError) {
showError('Payment failed: ' + error.message);
} else if (error instanceof InvalidAmountError) {
showError('Invalid payment amount');
} else if (error instanceof InvalidTokenError) {
showError('Invalid token type');
} else if (error instanceof TimeoutError) {
showError('Request timed out. Please try again.');
} else {
showError('An unexpected error occurred');
console.error('Unknown error:', error);
}
return null;
}
}
}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Next Steps
════════════════════════════════════════════════════════════
• See Getting Started for basic setup
• Review API Reference for complete documentation
• Check Error Handling for error handling patterns
═══════════════════════════════════════════════════════════════════════════════
For the latest documentation, visit: https://arcadia.obeliskprotocol.io/developer
For support, email: support@arcadia.com
═══════════════════════════════════════════════════════════════════════════════