Bare Workflow - Para Docs

The Para SDK for React Native allows you to easily integrate secure and scalable wallet functionalities into your mobile applications, utilizing the device’s Native Passkeys for secure wallet management. This guide covers the installation, setup, and usage of the Para SDK.

Prerequisites

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

Don’t have an API key yet? Request access to the Developer Portal to create API keys, manage billing, teams, and more.

Dependency Installation

Install the required packages for Para SDK integration:

npm install @getpara/react-native-wallet@alpha @react-native-async-storage/async-storage react-native-keychain react-native-modpow react-native-passkey react-native-quick-base64 @craftzdog/react-native-buffer react-native-quick-crypto react-native-config react-native-inappbrowser-reborn

Project Setup

Platform-Specific Configuration

In order for passkeys to work, you need to set up associated domains in your Xcode project linked to the Para domain.

Set Up Associated Domains

Open your project in Xcode
Select your target and go to “Signing & Capabilities”
Click ”+ Capability” and add “Associated Domains”
Add the following domains:
- webcredentials:app.beta.usecapsule.com
- webcredentials:app.usecapsule.com

For additional information on associated domains, refer to the Apple Developer documentation.

Important: Your teamId + bundleIdentifier must be registered with the Para team to set up associated domains. For example, if your Team ID is A1B2C3D4E5 and Bundle Identifier is com.yourdomain.yourapp, provide A1B2C3D4E5.com.yourdomain.yourapp to Para. This is required by Apple for passkey security. Note: Allow up to 24 hours for domain propagation.

Install CocoaPods for native dependencies:

cd ios
bundle install
bundle exec pod install
cd ..

Remember to run pod install after adding new dependencies to your project.

In order for passkeys to work, you need to set up associated domains in your Xcode project linked to the Para domain.

Set Up Associated Domains

Open your project in Xcode
Select your target and go to “Signing & Capabilities”
Click ”+ Capability” and add “Associated Domains”
Add the following domains:
- webcredentials:app.beta.usecapsule.com
- webcredentials:app.usecapsule.com

For additional information on associated domains, refer to the Apple Developer documentation.

Install CocoaPods for native dependencies:

cd ios
bundle install
bundle exec pod install
cd ..

Remember to run pod install after adding new dependencies to your project.

Set Up Digital Asset Links

For Android setup, you need to provide your app’s SHA-256 certificate fingerprint to Para.

Quick Testing Option: You can use com.getpara.example.reactnative as your package name for immediate testing. This package name is pre-registered and works with the SHA-256 certificate from the default debug.keystore.

To get your SHA-256 fingerprint:

For debug builds: keytool -list -v -keystore ~/.android/debug.keystore
For release builds: keytool -list -v -keystore <your_keystore_path>

For production apps, you’ll need to: 1. Upgrade your plan in the Developer Portal 2. Register your actual package name 3. Provide your app’s SHA-256 fingerprint 4. Wait up to 24 hours for the Digital Asset Links to propagate

Device Requirements

To ensure passkey functionality works correctly:

Enable biometric or device unlock settings (fingerprint, face unlock, or PIN)
Sign in to a Google account on the device (required for Google Play Services passkey management)

Configure Metro Bundler

Create or update metro.config.js in your project root:

metro.config.js

const { getDefaultConfig, mergeConfig } = require("@react-native/metro-config");

const config = {
  resolver: {
    extraNodeModules: {
      crypto: require.resolve("react-native-quick-crypto"),
      buffer: require.resolve("@craftzdog/react-native-buffer"),
    },
  },
};

module.exports = mergeConfig(getDefaultConfig(__dirname), config);

Add Para Shim

Import the Para shim as the FIRST import in your application’s entry file (typically index.js):

import "@getpara/react-native-wallet/shim";
// Other imports...

Important: The shim import must come before any other imports to ensure required modules are available.

Using the Para SDK

The Para SDK provides two main authentication methods: email-based and phone-based. Each method supports creating a new user and logging in an existing user. Both flows utilize Native Passkeys for secure and seamless authentication. Follow the steps below to implement these flows in your React Native application.

Beta Testing Credentials In the BETA Environment, you can use any email ending in @test.getpara.com (like dev@test.getpara.com) or US phone numbers (+1) in the format (area code)-555-xxxx (like (425)-555-1234). Any OTP code will work for verification with these test credentials. These credentials are for beta testing only. You can delete test users anytime in the beta developer console to free up user slots.

Create New User with Email

This flow guides you through the process of registering a new user with email, verifying their email, and setting up their wallet.

Initialize Para Client

First, set up the Para client to enable SDK interactions:

import { ParaMobile, Environment } from "@getpara/react-native-wallet";

const para = new ParaMobile(
  Environment.BETA, 
  YOUR_API_KEY, 
  undefined, 
  { disableWorkers: true }
);

Para offers two hosted environments: Environment.BETA (alias Environment.DEVELOPMENT) for testing, and Environment.PROD (alias Environment.PRODUCTION) for live use. Select the environment that matches your current development phase.

Use the signUpOrLogIn method to handle both new user registration and existing user authentication:

const handleContinue = async (email: string) => {
  try {
    const authState = await para.signUpOrLogIn({ auth: { email } });
    
    if (authState?.stage === 'verify') {
      // New user - show OTP verification
      setShowOTP(true);
    } else if (authState?.stage === 'login') {
      // Existing user - proceed with passkey login
      await para.loginWithPasskey();
    }
  } catch (error) {
    // Handle error
  }
};

Verify Email

Once the user receives the verification code, call the verifyNewAccount method to confirm their email:

const handleVerifyEmail = async (verificationCode: string) => {
  try {
    const authState = await para.verifyNewAccount({ verificationCode });
    return authState;
  } catch (error) {
    // Handle error
  }
};

Register Passkey

Use the returned authState to register the user’s passkey:

const handleRegisterPasskey = async (authState: any) => {
  try {
    await para.registerPasskey(authState);
  } catch (error) {
    // Handle error
  }
};

Complete New User Flow

Implement the full flow by combining all the previous steps:

const handleNewUserFlow = async (email: string, verificationCode: string) => {
  try {
    // Step 1: Sign up or log in
    const authState = await para.signUpOrLogIn({ auth: { email } });
    
    if (authState?.stage === 'verify') {
      // Step 2: Verify email
      const verifiedAuthState = await para.verifyNewAccount({ verificationCode });
      
      // Step 3: Register passkey
      await para.registerPasskey(verifiedAuthState);
    }
  } catch (error) {
    // Handle error
  }
};

This flow demonstrates how to authenticate an existing user using their email and passkey.

For existing users, use the signUpOrLogIn method which will return a login stage, then use loginWithPasskey:

const handleLogin = async (email: string) => {
  try {
    const authState = await para.signUpOrLogIn({ auth: { email } });
    
    if (authState?.stage === 'login') {
      await para.loginWithPasskey();
    }
  } catch (error) {
    // Handle error
  }
};

Create New User with Email

This flow guides you through the process of registering a new user with email, verifying their email, and setting up their wallet.

Initialize Para Client

First, set up the Para client to enable SDK interactions:

import { ParaMobile, Environment } from "@getpara/react-native-wallet";

const para = new ParaMobile(
  Environment.BETA, 
  YOUR_API_KEY, 
  undefined, 
  { disableWorkers: true }
);

Use the signUpOrLogIn method to handle both new user registration and existing user authentication:

const handleContinue = async (email: string) => {
  try {
    const authState = await para.signUpOrLogIn({ auth: { email } });
    
    if (authState?.stage === 'verify') {
      // New user - show OTP verification
      setShowOTP(true);
    } else if (authState?.stage === 'login') {
      // Existing user - proceed with passkey login
      await para.loginWithPasskey();
    }
  } catch (error) {
    // Handle error
  }
};

Verify Email

Once the user receives the verification code, call the verifyNewAccount method to confirm their email:

const handleVerifyEmail = async (verificationCode: string) => {
  try {
    const authState = await para.verifyNewAccount({ verificationCode });
    return authState;
  } catch (error) {
    // Handle error
  }
};

Register Passkey

Use the returned authState to register the user’s passkey:

const handleRegisterPasskey = async (authState: any) => {
  try {
    await para.registerPasskey(authState);
  } catch (error) {
    // Handle error
  }
};

Complete New User Flow

Implement the full flow by combining all the previous steps:

const handleNewUserFlow = async (email: string, verificationCode: string) => {
  try {
    // Step 1: Sign up or log in
    const authState = await para.signUpOrLogIn({ auth: { email } });
    
    if (authState?.stage === 'verify') {
      // Step 2: Verify email
      const verifiedAuthState = await para.verifyNewAccount({ verificationCode });
      
      // Step 3: Register passkey
      await para.registerPasskey(verifiedAuthState);
    }
  } catch (error) {
    // Handle error
  }
};

This flow demonstrates how to authenticate an existing user using their email and passkey.

For existing users, use the signUpOrLogIn method which will return a login stage, then use loginWithPasskey:

const handleLogin = async (email: string) => {
  try {
    const authState = await para.signUpOrLogIn({ auth: { email } });
    
    if (authState?.stage === 'login') {
      await para.loginWithPasskey();
    }
  } catch (error) {
    // Handle error
  }
};

Create New User with Phone

This flow guides you through the process of registering a new user with a phone number, verifying it, and setting up their wallet.

Initialize Para Client

First, set up the Para client to enable SDK interactions:

import { ParaMobile, Environment } from "@getpara/react-native-wallet@alpha";

const para = new ParaMobile(
  Environment.BETA, 
  YOUR_API_KEY, 
  undefined, 
  { disableWorkers: true }
);

Use the signUpOrLogIn method to handle both new user registration and existing user authentication:

const handleContinue = async (phone: string) => {
  try {
    const authState = await para.signUpOrLogIn({ auth: { phone } });
    
    if (authState?.stage === 'verify') {
      // New user - show OTP verification
      setShowOTP(true);
    } else if (authState?.stage === 'login') {
      // Existing user - proceed with passkey login
      await para.loginWithPasskey();
    }
  } catch (error) {
    // Handle error
  }
};

Verify Phone

Once the user receives the verification code, call the verifyNewAccount method to confirm their phone number:

const handleVerifyPhone = async (verificationCode: string) => {
  try {
    const authState = await para.verifyNewAccount({ verificationCode });
    return authState;
  } catch (error) {
    // Handle error
  }
};

Register Passkey

Use the returned authState to register the user’s passkey:

const handleRegisterPasskey = async (authState: any) => {
  try {
    await para.registerPasskey(authState);
  } catch (error) {
    // Handle error
  }
};

Complete Phone-based Flow

Here’s an example of a complete phone-based authentication flow:

const handleNewUserFlow = async (phone: string, verificationCode: string) => {
  try {
    // Step 1: Sign up or log in
    const authState = await para.signUpOrLogIn({ auth: { phone } });
    
    if (authState?.stage === 'verify') {
      // Step 2: Verify phone
      const verifiedAuthState = await para.verifyNewAccount({ verificationCode });
      
      // Step 3: Register passkey
      await para.registerPasskey(verifiedAuthState);
    }
  } catch (error) {
    // Handle error
  }
};

// Resend verification code if needed
const resendOTP = async () => {
  await para.resendVerificationCode();
};

This flow demonstrates how to authenticate an existing user using their phone number and passkey.

For existing users, use the signUpOrLogIn method which will return a login stage, then use loginWithPasskey:

const handleLogin = async (phone: string) => {
  try {
    const authState = await para.signUpOrLogIn({ auth: { phone } });
    
    if (authState?.stage === 'login') {
      await para.loginWithPasskey();
    }
  } catch (error) {
    // Handle error
  }
};

By following these steps, you can implement a secure and user-friendly authentication system in your React Native application using the Para SDK, with support for both email and phone-based authentication methods.

Wallet Management

After successful authentication, you must create wallets for the blockchain networks you want to use:

Creating Wallets

import { WalletType } from "@getpara/react-native-wallet";

// Create wallets for different blockchain types
await para.createWallet({type: WalletType.EVM, skipDistribute: false});
await para.createWallet({type: WalletType.SOLANA, skipDistribute: false});
await para.createWallet({type: WalletType.COSMOS, skipDistribute: false});

Retrieving Wallet Information

// Get existing wallets by type
const evmWallet = para.getWalletsByType(WalletType.EVM)[0];
const solanaWallet = para.getWalletsByType(WalletType.SOLANA)[0];
const cosmosWallet = para.getWalletsByType(WalletType.COSMOS)[0];

// Check if wallet exists and get address
if (evmWallet?.address) {
  console.log('EVM Address:', evmWallet.address);
}

Complete Integration Example

const setupEVMWallet = async () => {
  try {
    // Check if EVM wallet exists, create if not
    let wallet = para.getWalletsByType(WalletType.EVM)[0];
    if (!wallet) {
      await para.createWallet({type: WalletType.EVM, skipDistribute: false});
      wallet = para.getWalletsByType(WalletType.EVM)[0];
    }
    
    // Now ready for EVM operations
    return wallet?.address;
  } catch (error) {
    console.error('Wallet setup failed:', error);
  }
};

Important: Wallet creation must be completed after authentication but before any blockchain operations (signing transactions, getting balances, etc.).

Examples

For practical implementation of the Para SDK in React Native environments, check out our GitHub repository:

React Native Integration Examples

Explore our repository containing React Native implementations, along with shared UI components demonstrating Para integration.

Troubleshooting

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

Para SDK initialization fails

Native modules are not found or linked

Passkey operations fail or throw errors

Crypto-related errors or undefined functions

"Cannot create URL for blob" errors

Authentication fails or API requests are rejected

For a more comprehensive list of solutions, visit our troubleshooting guide:

Troubleshooting

Our troubleshooting guide provides solutions to common integration and usage problems.

Next Steps

After integrating Para, you can explore other features and integrations to enhance your Para experience.

EVM Integration

Learn how to use Para with EVM-compatible libraries like ethers.js, viem, and wagmi.

Solana Integration

Discover how to integrate Para with solana-web3.js.

Cosmos Integration

Explore Para integration with Cosmos ecosystem using CosmJS, Cosmos Kit, and Graz.

Introduction

Setup

Guides

API & Troubleshooting

​Prerequisites

​Dependency Installation

​Project Setup

​Platform-Specific Configuration

​Set Up Associated Domains

​Install CocoaPods for native dependencies:

​Set Up Associated Domains

​Install CocoaPods for native dependencies:

​Set Up Digital Asset Links

​Device Requirements

​Configure Metro Bundler

​Add Para Shim

​Using the Para SDK

​Create New User with Email

​Initialize Para Client

​Sign Up or Log In

​Verify Email

​Register Passkey

​Complete New User Flow

​Login Existing User with Email

​Login Existing User

​Create New User with Email

​Initialize Para Client

​Sign Up or Log In

​Verify Email

​Register Passkey

​Complete New User Flow

​Login Existing User with Email

​Login Existing User

​Create New User with Phone

​Initialize Para Client

​Sign Up or Log In

​Verify Phone

​Register Passkey

​Complete Phone-based Flow

​Login Existing User with Phone

​Login Existing User

​Wallet Management

​Creating Wallets

​Retrieving Wallet Information

​Complete Integration Example

​Examples

React Native Integration Examples

​Troubleshooting

Troubleshooting

​Next Steps

EVM Integration

Solana Integration

Cosmos Integration

Prerequisites

Dependency Installation

Project Setup

Platform-Specific Configuration

Set Up Associated Domains

Install CocoaPods for native dependencies:

Set Up Associated Domains

Install CocoaPods for native dependencies:

Set Up Digital Asset Links

Device Requirements

Configure Metro Bundler

Add Para Shim

Using the Para SDK

Create New User with Email

Initialize Para Client

Sign Up or Log In

Verify Email

Register Passkey

Complete New User Flow

Login Existing User with Email

Login Existing User

Create New User with Email

Initialize Para Client

Sign Up or Log In

Verify Email

Register Passkey

Complete New User Flow

Login Existing User with Email

Login Existing User

Create New User with Phone

Initialize Para Client

Sign Up or Log In

Verify Phone

Register Passkey

Complete Phone-based Flow

Login Existing User with Phone

Login Existing User

Wallet Management

Creating Wallets

Retrieving Wallet Information

Complete Integration Example

Examples

Troubleshooting

Next Steps