Flutter (Mobile)

The Capsule SDK for Flutter allows you to easily integrate secure and scalable wallet functionalities into your mobile applications. This guide covers the installation, setup, and usage of the Capsule SDK, including handling authentication flows.

​

Prerequisites

To use Capsule, you need an API key. This key authenticates your requests to Capsule services and is essential for integration.

​

Dependency Installation

To install the Capsule SDK and required dependencies, use the following command:

flutter pub add capsule

​

Project Setup

To set up associated domains for passkey functionality in your Flutter project, you need to configure both iOS and Android platforms:

• iOS
• Android

​

Using the Capsule SDK

Much like our web SDKs, the Flutter SDK follows a similar usage pattern, handling both authentication and signing capabilities. The SDK provides comprehensive authentication flows for both creating new users and logging in existing users. Both flows utilize passkeys for secure and seamless authentication.

For authentication, we have two main paths: creating a new user or logging in an existing one. Authentication options include phone, email, OAuth, and an advanced use case with pregenerated wallets (covered later). The key concept is that once a user is created, we create an associated native passkey on their mobile device. This passkey will secure the user’s wallets when they’re created.

​

Capsule Initialization

First things first - you’ll need a beta API key from the developer portal. Once you’ve got your API key, you can create a Capsule instance in your Flutter application. Here’s an example of how to set this up:

import 'package:capsule/capsule.dart';

final capsuleClient = Capsule(
  environment: Environment.sandbox, // or Environment.prod
  apiKey: 'your_api_key_here',
);

​

Authentication Methods

The SDK provides multiple authentication methods, each following a similar pattern but with their own specific requirements:

• Email + Passkey
• Phone + Passkey
• OAuth (Google, Apple, X/Twitter, Discord)
• Pregenerated Wallets (advanced use case)

​

Email Authentication Flow

The email flow demonstrates the typical pattern all authentication methods follow. Here’s a detailed walkthrough:

// Get the user's email from your UI
final email = emailController.text.trim();

try {
  final exists = await capsuleClient.checkIfUserExists(email);
  if (exists) {
    // Show UI prompt to use passkey login instead
    // e.g., showDialog or navigate to login screen
    return;
  }
} catch (e) {
  // Handle errors appropriately in your UI
  // e.g., show error message to user
  return;
}

try {
  await capsuleClient.createUser(email);

  // After successful creation:
  // 1. Inform user to check their email
  // 2. Show OTP entry UI
} catch (e) {
  // Handle creation errors
  // Show appropriate error message to user
}

// Get OTP code from your UI
final otpCode = otpController.text.trim();

try {
  // Verify the email with the OTP
  final biometricsId = await capsuleClient.verifyEmail(otpCode);

  // Generate the passkey using the verified credentials
  await capsuleClient.generatePasskey(email, biometricsId);

  // At this point:
  // 1. Show success message
  // 2. Indicate that wallet creation is next
  // 3. You might want to show a loading indicator
} catch (e) {
  // Handle verification errors
  // Consider showing a retry option
  return;
}

try {
  final result = await capsuleClient.createWallet(skipDistribute: false);

  // Important: Store or display the recovery secret
  final recoverySecret = result.recoverySecret;
  final wallet = result.wallet;

  // At this point you should:
  // 1. Suggest secure storage of the recovery secret
  // 2. Show the wallet address to the user
  // 3. Navigate to your app's main interface
} catch (e) {
  // Handle wallet creation errors
  return;
}

​

Phone Authentication Flow

The phone flow follows the same pattern as email but with phone-specific methods:

// Get phone details from your UI
final phone = phoneController.text.trim();
final countryCode = countryCodeController.text.trim();

try {
  final exists = await capsuleClient.checkIfUserExistsByPhone(
    phone,
    '+${countryCode}' // Must include + prefix
  );
  
  if (exists) {
    // Direct to passkey login
    return;
  }
} catch (e) {
  // Handle check error
  return;
}

try {
  await capsuleClient.createUserByPhone(
    phone,
    '+${countryCode}'
  );
  
  // Show OTP entry UI
  // Consider implementing SMS auto-fill if available
} catch (e) {
  // Handle creation error
}

try {
  final biometricsId = await capsuleClient.verifyPhone(otpCode);
  
  // The full phone number must include country code
  final fullPhone = '+${countryCode}${phone}';
  await capsuleClient.generatePasskey(fullPhone, biometricsId);
  
  // Show success indication
} catch (e) {
  // Handle verification error
}

​

OAuth Authentication Flow

OAuth provides a streamlined process, handling much of the verification automatically, but unlike email and phone requires a browser view for the initial authentication:

try {
  // Get OAuth URL for selected provider
  final oauthUrl = await capsuleClient.getOAuthURL(provider);

  // Start polling for OAuth completion
  final oauthFuture = capsuleClient.waitForOAuth();

  // Launch OAuth URL in browser
  // This example uses flutter_inappwebview
  final browser = ChromeSafariBrowser();
  await browser.open(url: WebUri(oauthUrl));

  //await the OAuth result future to close the browser
  final oauthResult = await oauthFuture;

  try {
    await browser.close();
  } catch (_) {}

  if (oauthResult.isError == true) {
    throw Exception('OAuth authentication failed');
  }
} catch (e) {
  // Handle OAuth initiation errors
  return;
}

try {
  if (oauthResult.userExists) {
    // Existing user - proceed to passkey login
    final wallet = await capsuleClient.login();
    // Navigate to main app interface
  } else {
    // New user - create passkey and wallet
    if (!oauthResult.email) {
      throw Exception('Email required for registration');
    }
    
    final biometricsId = await capsuleClient.verifyOAuth();
    await capsuleClient.generatePasskey(oauthResult.email!, biometricsId);
    
    // Create wallet like in other flows
    final result = await capsuleClient.createWallet(skipDistribute: false);
    // Handle wallet and recovery secret
  }
} catch (e) {
  // Handle OAuth completion errors
}

Each flow ultimately results in:

1. A verified user account
2. A device-specific passkey
3. A wallet with its recovery secret

The key difference between flows is the initial verification method, but they all converge at the passkey and wallet creation steps.

​

Login Existing User

Once the wallet is created and automatically stored and secured by the passkey, logging in becomes straightforward. The Capsule Flutter class mirrors most of the same method names as the Capsule web JS class, maintaining consistency across platforms.

Wallet wallet;
try {
  wallet = await _capsule.login();
  print("User logged in successfully");
} catch (e) {
  print("Error during login: \$e");
  return;
}

// Handle wallet information after successful login
final address = wallet.address;
print("Wallet address: \$address");

​

Transaction Signing

Now that we have a user with wallets, we can begin signing. Signing with Capsule provides three main methods:

1. signMessage - For general-purpose signing of any data
2. signTransaction - Specifically for EVM transactions (requires RLP encoding)
3. sendTransaction - For direct transaction submission of RLPEncoded transactions

This is why it’s crucial to use libraries that handle Transaction construction correctly. You’ll want to:

1. Construct the transaction
2. Get the serialized byte data
3. Convert it to base64
4. Pass that into signMessage

Here’s an example in Solana using the solana_web3 package:

import 'package:solana_web3/solana_web3.dart' as web3;

// Construct the transaction
final transaction = web3.Transaction.v0(
  payer: publicKey,
  recentBlockhash: blockhash,
  instructions: [
    programs.SystemProgram.transfer(
      fromPubkey: publicKey,
      toPubkey: recipientPubkey,
      lamports: amount,
    ),
  ],
);

// Get bytes and convert to base64
final message = Uint8List.fromList(transaction.serializeMessage());
final messageBase64 = base64Encode(message);

// Sign with Capsule
final result = await capsuleClient.signMessage(
  walletId: wallet.id,
  messageBase64: messageBase64,
);

if (result is SuccessfulSignatureResult) {
  final signature = base64.decode(result.signature);
  transaction.addSignature(publicKey, signature);
}

​

Advanced: Pregenerated Wallets

Pregenerated wallets are an advanced use case that lets you create a wallet based on an identifier like an email before the user exists. When you create a pregenerated wallet, your app receives the user’s half of the key (userShare). This keyShare must be secured, encrypted, and NOT lost as it controls the user’s half of the key.

This advanced feature allows apps to take actions on behalf of a user without needing user interaction. The methods are identical across all our SDKs, so you can use them the same way in Flutter as you would in Web or Server implementations:

// Create pregen wallet
final wallet = await capsuleClient.createWalletPreGen(
  type: WalletType.evm,
  pregenIdentifier: 'user@example.com',
  pregenIdentifierType: PregenIdentifierType.email,
);

// Get user's key share - needs secure storage
final userShare = await capsuleClient.getUserShare();

// Set stored user share when needed
await capsuleClient.setUserShare(userShare);

For more details on pregenerated wallets check out the

Pregenerated Wallets guide.

​

Examples

To help you get started with the Capsule Flutter SDK, we’ve prepared a comprehensive example:

This example repository demonstrates how to handle user authentication, wallet creation, and signing messages using the Capsule SDK in a Flutter application.

​

Next Steps

After integrating Capsule, you can explore other features and integrations to enhance your Capsule experience. Here are some resources to help you get started:

​

Ecosystems

Learn how to use Capsule with popular Web3 clients and wallet connectors. We’ll cover integration with key libraries for EVM, Solana, and Cosmos ecosystems.

If you’re ready to go live with your Capsule integration, make sure to review our go-live checklist:

​

Troubleshooting

If you encounter issues during the integration or usage of the Capsule SDK in your Flutter application, here are some common problems and their solutions:

For more detailed troubleshooting and solutions specific to Flutter, please refer to our comprehensive troubleshooting guide:

​

Integration Support

If you’re experiencing issues that aren’t resolved by our troubleshooting resources, please contact our team for assistance. To help us resolve your issue quickly, please include the following information in your request:

1. 1

   A detailed description of the problem you’re encountering.

2. 2

   Any relevant error messages or logs.

3. 3

   Steps to reproduce the issue.

4. 4

   Details about your system or environment (e.g., device, operating system, software version).

Providing this information will enable our team to address your concerns more efficiently.