Frequently Asked Questions

Common questions and answers about the Arcadia Game SDK.

General

What is the Arcadia Game SDK?

The Arcadia Game SDK is a JavaScript library that enables Web3 games to integrate wallet connectivity and payment processing. It works seamlessly in iframe environments and handles all the complexity of Web3 interactions.

What browsers are supported?

The SDK works in all modern browsers:

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Do I need to know Solana/Web3 to use the SDK?

No! The SDK abstracts away all Web3 complexity. You just call methods like payToPlay() and getWalletAddress() - the SDK handles everything else.

Is the SDK free to use?

Yes, the SDK is free to use. Arcadia charges platform fees on payments (transparently shown in payment results), but the SDK itself has no cost.

Installation

NPM vs CDN - which should I use?

• NPM: Recommended for TypeScript projects, bundlers (Webpack, Vite), and modern development
• CDN: Quick for simple HTML games, testing, or when you can't use a bundler

Both work the same - choose based on your project setup.

How do I update the SDK?

npm update @arcadiasol/sdk

Or update the version in your CDN URL:

<script src="https://cdn.jsdelivr.net/npm/@arcadiasol/sdk@latest/dist/umd/arcadia-game-sdk.js"></script>

Can I use the SDK in a Node.js environment?

No, the SDK is designed for browser environments only. It requires window and postMessage APIs.

Wallet Integration

Why use wallet address as user ID?

Wallet addresses are:

• Universal (work across all games)
• Persistent (don't change)
• Secure (cryptographically secure)
• No authentication needed

This makes them perfect for Web3 games.

What if a player doesn't have a wallet?

Players must connect a wallet in Arcadia before playing games. The SDK will return null for getWalletAddress() if no wallet is connected, and you should prompt them to connect.

Can players switch wallets during gameplay?

Yes. Use onWalletChange() to detect wallet changes and handle them appropriately (save current game, load new player data, etc.).

How do I handle wallet disconnections?

Listen for wallet changes and save game state when disconnected:

arcadia.onWalletChange((connected, address) => {
  if (!connected) {
    saveGameState();
    pauseGame();
  }
});

Payments

How fast are payments?

Payments return immediately after the transaction is sent to the blockchain. The SDK doesn't wait for full confirmation, making the experience instant for players.

What tokens are supported?

Currently supported:

• SOL (Solana native token)
• USDC (USD Coin on Solana)

More tokens may be added in the future.

How are fees calculated?

Platform fees are automatically calculated and deducted. The PaymentResult includes:

• platformFee - Fee deducted by platform
• developerAmount - Amount you receive (after fees)

Can I set custom payment amounts?

Yes, you can set any amount > 0. The SDK validates amounts but doesn't restrict them.

What happens if a payment fails?

The SDK throws a PaymentFailedError with details. Common reasons:

• User rejected transaction
• Insufficient funds
• Network error
• Developer wallet not configured

Do I need to verify payments on-chain?

No! The SDK provides complete payment details in the PaymentResult. You can verify amounts and store transaction signatures, but you don't need to query the blockchain.

Can I refund payments?

Refunds are not handled by the SDK. You'll need to implement refund logic separately if needed.

Game Integration

Does my game need to be in an iframe?

Yes, the SDK is designed for games embedded in Arcadia's iframe. Some features won't work outside of an iframe.

Can I test the SDK locally?

Yes, but some features require the Arcadia iframe environment. For full testing, you'll need to:

1. Host your game
2. Add it to Arcadia
3. Test through Arcadia's game player

How do I get a game ID?

You'll receive a game ID when you register your game on Arcadia. Contact support@arcadia.com for game registration.

Can I use the SDK with Unity/Unreal/other game engines?

Yes! As long as your game runs in a browser (WebGL builds), you can use the SDK. You'll need to:

1. Build your game for WebGL
2. Host it
3. Integrate the SDK in your game's JavaScript/TypeScript code

How do I handle game saves?

Use the wallet address as the key for save data:

const walletAddress = await arcadia.getWalletAddress();
await saveGameData(walletAddress, gameData);
const loaded = await loadGameData(walletAddress);

Error Handling

What errors can occur?

Common errors:

• WalletNotConnectedError - Wallet not connected
• PaymentFailedError - Payment failed
• TimeoutError - Request timed out
• InvalidAmountError - Invalid payment amount
• InvalidTokenError - Invalid token type

See Error Handling Guide for details.

How do I handle errors?

Use try-catch and check error types:

try {
  await arcadia.payment.payToPlay(0.5, 'SOL');
} catch (error) {
  if (error instanceof WalletNotConnectedError) {
    showMessage('Please connect your wallet');
  } else if (error instanceof PaymentFailedError) {
    showError('Payment failed: ' + error.message);
  }
}

Security

Is the SDK secure?

Yes! The SDK:

• Never accesses private keys
• Only uses public wallet addresses
• Requires user approval for all transactions
• Validates message origins
• Uses secure communication patterns

Can games steal funds?

No. Games cannot:

• Access private keys
• Send transactions without user approval
• Access wallet functionality directly
• Bypass security checks

All transactions require explicit user approval in the wallet.

Should I validate payments server-side?

Yes, for critical operations. While the SDK provides payment details, you should verify:

• Payment amounts match expected values
• Transaction signatures are valid
• Payments aren't duplicated

Troubleshooting

SDK not initializing

Check:

1. Game is running in Arcadia iframe
2. gameId is correct
3. SDK script is loaded
4. Browser console for errors

Wallet address is null

• Player hasn't connected wallet in Arcadia
• Game not running in Arcadia iframe
• SDK not initialized

Payments failing

Check:

1. Wallet has sufficient balance
2. Developer wallet is configured in Arcadia
3. Network connection is stable
4. Error message for specific issue

postMessage errors

• Game not in iframe
• Origin validation mismatch
• Parent window not responding

Support

Where can I get help?

• Documentation: This guide
• Email: support@arcadia.com
• GitHub: Issues

How do I report bugs?

Open an issue on GitHub or email support@arcadia.com with:

• Description of the issue
• Steps to reproduce
• Expected vs actual behavior
• Browser/OS information
• Error messages (if any)

Can I contribute?

Yes! Contributions are welcome. Check the GitHub repository for contribution guidelines.

Next Steps

• Review Getting Started if you're new
• Check Examples for code samples
• Read API Reference for complete documentation