API Reference

Complete reference documentation for all Arcadia Game SDK methods, types, and interfaces.

ArcadiaSDK Class

The main SDK class that provides all functionality.

Constructor

new ArcadiaSDK(config: SDKConfig)

Creates a new SDK instance.

Parameters:

• config.gameId (string, required) - Your unique game identifier
• config.parentOrigin (string, optional) - Parent window origin for security (default: '*')
• config.timeout (number, optional) - Request timeout in milliseconds (default: 30000)

Throws:

• InvalidConfigError - If gameId is missing or invalid

Example:

const arcadia = new ArcadiaSDK({
  gameId: 'my-awesome-game',
  parentOrigin: 'https://arcadia.com', // Optional
  timeout: 30000, // Optional
});

Methods

init(): Promise<void>

Initializes the SDK and requests initialization data from the parent window. Must be called after creating the SDK instance.

Returns: Promise that resolves when initialization is complete

Example:

await arcadia.init();

getWalletAddress(): Promise<string | null>

Gets the connected wallet address. Use this as your primary user identifier.

Returns:

• string - Wallet address if connected
• null - If wallet is not connected

Example:

const walletAddress = await arcadia.getWalletAddress();
if (!walletAddress) {
  console.log('Wallet not connected');
}

isWalletConnected(): Promise<boolean>

Checks if a wallet is currently connected.

Returns:

• true - If wallet is connected
• false - If wallet is not connected

Example:

const connected = await arcadia.isWalletConnected();

onWalletChange(callback: (connected: boolean, address: string | null) => void): void

Registers a callback to listen for wallet connection changes.

Parameters:

• callback - Function called when wallet connection status changes
  • connected (boolean) - Whether wallet is connected
  • address (string | null) - Wallet address or null

Example:

arcadia.onWalletChange((connected, address) => {
  if (connected) {
    console.log('Wallet connected:', address);
  } else {
    console.log('Wallet disconnected');
  }
});

offWalletChange(callback: Function): void

Removes a wallet change listener.

Parameters:

• callback - The callback function to remove

Example:

const handler = (connected, address) => { /* ... */ };
arcadia.onWalletChange(handler);
// Later...
arcadia.offWalletChange(handler);

isInIframe(): boolean

Checks if the SDK is running in an iframe environment.

Returns:

• true - If running in iframe
• false - If not in iframe

Example:

if (arcadia.isInIframe()) {
  console.log('Running in Arcadia iframe');
}

isInitialized(): boolean

Checks if the SDK has been initialized.

Returns:

• true - If initialized
• false - If not initialized

Example:

if (arcadia.isInitialized()) {
  // SDK is ready
}

getConfig(): SDKConfig

Gets the current SDK configuration.

Returns: SDK configuration object

Example:

const config = arcadia.getConfig();
console.log('Game ID:', config.gameId);

destroy(): void

Cleans up SDK resources. Call this when the game is unloaded.

Example:

arcadia.destroy();

Payment Methods

payment.payToPlay(amount: number, token: 'SOL' | 'USDC'): Promise<PaymentResult>

Processes a pay-to-play payment (one-time payment to access game).

Parameters:

• amount (number) - Payment amount (must be > 0)
• token ('SOL' | 'USDC') - Token type

Returns: Promise that resolves to PaymentResult

Throws:

• WalletNotConnectedError - If wallet is not connected
• InvalidAmountError - If amount is invalid
• InvalidTokenError - If token is invalid
• PaymentFailedError - If payment fails
• NotInIframeError - If not running in iframe

Example:

const result = await arcadia.payment.payToPlay(0.5, 'SOL');
console.log('Payment successful:', result.txSignature);

payment.purchaseItem(itemId: string, amount: number, token: 'SOL' | 'USDC'): Promise<PaymentResult>

Purchases an in-game item.

Parameters:

• itemId (string) - Unique item identifier
• amount (number) - Payment amount (must be > 0)
• token ('SOL' | 'USDC') - Token type

Returns: Promise that resolves to PaymentResult

Throws:

• WalletNotConnectedError - If wallet is not connected
• InvalidAmountError - If amount is invalid
• InvalidTokenError - If token is invalid
• PaymentFailedError - If payment fails
• NotInIframeError - If not running in iframe
• Error - If itemId is missing or invalid

Example:

const result = await arcadia.payment.purchaseItem('sword-001', 1.0, 'SOL');
console.log('Purchase successful:', result.txSignature);

Type Definitions

SDKConfig

interface SDKConfig {
  gameId: string;              // Required: Unique game identifier
  parentOrigin?: string;       // Optional: Parent window origin (default: '*')
  timeout?: number;            // Optional: Request timeout in ms (default: 30000)
}

PaymentResult

interface PaymentResult {
  success: boolean;            // Whether payment was successful
  txSignature: string;         // Blockchain transaction signature
  amount: number;              // Amount paid by user
  token: 'SOL' | 'USDC';      // Token type used
  timestamp: string;           // ISO timestamp when payment completed
  purchaseId?: string;        // Arcadia purchase ID (for tracking)
  platformFee?: number;       // Platform fee deducted
  developerAmount?: number;   // Amount received by developer (after fees)
  error?: string;             // Error message if payment failed
}

WalletInfo

interface WalletInfo {
  connected: boolean;          // Whether wallet is connected
  address: string | null;      // Wallet address or null if not connected
}

InitData

interface InitData {
  gameId: string;             // Game ID
  userId: string;             // User ID
  wallet: WalletInfo;         // Wallet information
}

WalletAddressResponse

interface WalletAddressResponse {
  walletAddress: string | null;  // Wallet address or null
  connected: boolean;             // Whether wallet is connected
}

Error Classes

ArcadiaSDKError

Base error class for all SDK errors.

class ArcadiaSDKError extends Error {
  code?: string;
  message: string;
}

WalletNotConnectedError

Thrown when wallet operations are attempted without a connected wallet.

class WalletNotConnectedError extends ArcadiaSDKError {
  code: 'WALLET_NOT_CONNECTED';
}

PaymentFailedError

Thrown when a payment fails.

class PaymentFailedError extends ArcadiaSDKError {
  code: 'PAYMENT_FAILED';
  txSignature?: string;  // Transaction signature if available
}

TimeoutError

Thrown when a request times out.

class TimeoutError extends ArcadiaSDKError {
  code: 'TIMEOUT';
}

InvalidConfigError

Thrown when SDK configuration is invalid.

class InvalidConfigError extends ArcadiaSDKError {
  code: 'INVALID_CONFIG';
}

NotInIframeError

Thrown when SDK methods are called outside of an iframe.

class NotInIframeError extends ArcadiaSDKError {
  code: 'NOT_IN_IFRAME';
}

InvalidAmountError

Thrown when an invalid payment amount is provided.

class InvalidAmountError extends ArcadiaSDKError {
  code: 'INVALID_AMOUNT';
}

InvalidTokenError

Thrown when an invalid token type is provided.

class InvalidTokenError extends ArcadiaSDKError {
  code: 'INVALID_TOKEN';
}

Importing Types and Errors

// Import SDK class
import { ArcadiaSDK } from '@arcadiasol/sdk';

// Import types
import type {
  SDKConfig,
  PaymentResult,
  WalletInfo,
} from '@arcadiasol/sdk';

// Import error classes
import {
  ArcadiaSDKError,
  WalletNotConnectedError,
  PaymentFailedError,
  TimeoutError,
  InvalidConfigError,
  NotInIframeError,
  InvalidAmountError,
  InvalidTokenError,
} from '@arcadiasol/sdk';

CDN Usage

When using CDN, the SDK is available as a global variable:

// SDK class
const ArcadiaSDK = window.ArcadiaGameSDK?.default || 
                  window.ArcadiaGameSDK?.ArcadiaSDK || 
                  window.ArcadiaGameSDK;

const arcadia = new ArcadiaSDK({
  gameId: 'your-game-id',
});

Next Steps

• See Examples for complete usage examples
• Review Error Handling for error handling patterns
• Check Wallet Integration for wallet features
• Read Payments for payment implementation