Circle User-Controlled Wallets React Native SDK

SDK for integrating Circle's user-controlled wallet into React Native applications

Important

This SDK supports both Expo and bare React Native projects. Select the appropriate guide based on your project type.

• Bare React Native (manages native code manually) → Go to Bare React Native Integration Guide
• Expo project (uses expo prebuild and has app.json/app.config.js) ↓ Continue below

---

Migrating from SDK v1 (Bare React Native)

If you have an existing bare React Native project using SDK v1 and want to upgrade to SDK v2, see the SDK v1 Migration Guide.

You can also find the SDK v1 sample app in the sample app repository's sdk-v1 branch.

System Requirements

Platform	Minimum Version	Recommended Version
React Native	0.60+	0.76-0.81
iOS	15.1+	iOS 17+
Android	API 21+	API 36+
Expo SDK	49+	54+
Node.js	20.19+	20.20+
Xcode	16.1+	16.3+

Installation

Important

Prerequisites: This SDK uses native modules and requires a development build. Expo Go is not supported.

Follow these steps in order. The SDK will be fully configured after running expo prebuild.

Step 1: Generate Native Projects (Skip if android/ios Already Exist)

If you don't have android/ and ios/ directories yet, generate them:

npx expo prebuild

Step 2: Install the SDK Package

npx expo install @circle-fin/w3s-pw-react-native-sdk

Step 3: Configure app.json

Add both required plugins to app.json:

{
  "expo": {
    "plugins": [
      [
        "@circle-fin/w3s-pw-react-native-sdk/plugins/withCopyFiles",
        {
          "sourceDir": "prebuild-sync-src",
          "targetDir": ".",
          "overwrite": true
        }
      ],
      "@circle-fin/w3s-pw-react-native-sdk/plugins/podfile-modifier"
    ]
  }
}

What these plugins do:

• withCopyFiles: Preserves your Android/iOS configurations across rebuilds
• podfile-modifier: Automatically configures iOS Podfile for Circle SDK

Tip

Prefer manual setup? Skip podfile-modifier and follow the iOS configuration in the Bare React Native Integration Guide after prebuild.

Learn more about withCopyFiles plugin

The withCopyFiles plugin copies files from a source directory to your native project during prebuild, ensuring custom configurations are preserved.

Directory structure example:

prebuild-sync-src/
├── android/
│   └── build.gradle
└── ios/
    └── YourApp/Resources/
        ├── CirclePWLocalizable.strings
        └── CirclePWTheme.json

During expo prebuild, files from prebuild-sync-src/android → android/ and prebuild-sync-src/ios → ios/.

Options:

Option	Default	Description
sourceDir	prebuild-sync-src	Root directory with android/ and ios/ folders
overwrite	true	Whether to overwrite existing files

Note: This solves the problem of expo prebuild --clean erasing manual changes.

Step 4: Configure Android Repository

Note

The SDK depends on w3s-android-sdk hosted on GitHub Gradle registry, which requires authentication.

4.1 Create .env in project root with your GitHub credentials:

PWSDK_MAVEN_URL=https://maven.pkg.github.com/circlefin/w3s-android-sdk
PWSDK_MAVEN_USERNAME=<YOUR_GITHUB_USERNAME>
PWSDK_MAVEN_PASSWORD=<YOUR_GITHUB_PAT>

Get a Personal Access Token with read:packages permission.

4.2 Add to android/build.gradle (project-level) in the repositories block:

repositories {
  // Keep your other repositories here
  // google()
  // mavenCentral()

  maven {
    url System.getenv('PWSDK_MAVEN_URL')
    credentials {
      username System.getenv('PWSDK_MAVEN_USERNAME')
      password System.getenv('PWSDK_MAVEN_PASSWORD')
    }
  }
}

Step 5: Create Sync Directory Structure

Create prebuild-sync-src/ folder and copy your modified Android files:

mkdir -p prebuild-sync-src/android
cp android/build.gradle prebuild-sync-src/android/

Important

Place all manual Android/iOS changes in prebuild-sync-src/ to preserve them across rebuilds.

Step 6: Generate Native Code

npx expo prebuild --clean

This command generates native directories and applies all configurations automatically.

Tip

Verify iOS Configuration: Check if the Circle SDK repository was added correctly:

cat ios/Podfile | grep "circlefin"

Expected output: source 'https://github.com/circlefin/w3s-ios-sdk.git'

Step 7: Install iOS Dependencies

cd ios && pod install && cd ..

Step 8: Build and Run

Local development:

For iOS:

npx expo run:ios

For Android:

npx expo run:android

EAS Build:

First, install EAS CLI globally (one-time setup):

npm install -g eas-cli

Then build your app:

eas build --profile development --platform all

Tip

EAS Setup: Add secrets PWSDK_MAVEN_USERNAME and PWSDK_MAVEN_PASSWORD to your EAS project. Learn more

---

Additional Resources

Circle Resources:

• User-Controlled Wallets Documentation - Product overview and architecture
• React Native SDK Documentation - Complete API reference
• UI Customization API - Theming and localization options
• React Native Sample App - Working Expo sample app with integration guide
• SDK v1 Migration Guide - Complete guide for upgrading from bare React Native + SDK v1 to Expo Modules + SDK v2

Expo Resources:

• Expo Development Build
• EAS Build