React Native Quickstart

What You'll Build

Use the starter to create or import a wallet, view balances and transfers, and explore optional cloud backup. Or integrate React Native Core into an existing app using the second path below.

The starter's configured networks and assets are listed on its overview. Network support in your own app depends on the wallet modules and providers you configure.

Prerequisites

Before we start, make sure you have:

Quickstart Paths

Choose a starting point:

Option 1: Starter Template

The starter is an alpha app and may introduce breaking changes. It currently uses Expo SDK 55 and React Native 0.83.6. Use Node.js 22+ and npm 11.10.1+; Android builds also require JDK 17. Check its environment guide for native-toolchain setup.

Step 1: Clone the Starter

git clone https://github.com/tetherto/wdk-starter-react-native.git
cd wdk-starter-react-native

Step 2: Install Dependencies

npm install

The starter installs Cloud Backup 1.0.0-beta.1 and Indexer 1.0.1 from npm. Its postinstall script generates the WDK worklet bundle; keep the repository's dependency pins when following this path.

Step 3: Configure Environment

Copy the environment template for the network providers and optional integrations:

cp .env.example .env

To load the Activity tab, add a production WDK Indexer API key:

EXPO_PUBLIC_WDK_INDEXER_API_KEY=your_actual_api_key_here

The starter explicitly selects https://wdk-api.tether.io in src/wdk/indexer.ts; it does not read EXPO_PUBLIC_WDK_INDEXER_BASE_URL. Indexer 1.0.1 defaults to staging (https://wdk-api.tether.su), so retain the explicit production baseUrl if you modify the client setup.

Cloud backup is optional and needs separate Google/CloudKit configuration. Follow the starter's cloud backup setup before testing it. The starter overview explains its storage and backup roles.

Step 4: Run Your App

Generate native project files on the first run:

npx expo prebuild

Then build and launch the app:

npm run ios

After the native build completes, create or import a wallet. Balances and Activity require the integrations configured in Step 3.

→ Skip to What's Next

Option 2: Add to Existing App

Integrate WDK into your existing React Native or Expo project using @tetherto/wdk-react-native-core.

Step 1: Install

npm install @tetherto/wdk-react-native-core@1.0.0-beta.20 react-native-bare-kit
npx expo install expo-crypto

Beta.20 requires expo-crypto >=55.0.0 <57.0.0 and react-native-bare-kit >=0.14.5 as peer dependencies. Confirm that the version selected by npx expo install is both inside the package range and compatible with the app's Expo SDK. If the SDK requires a version outside that range, do not force the peer installation; use compatible releases instead. Bare React Native apps must install and configure Expo modules before installing expo-crypto.

Step 2: Configure Android minSdkVersion

The library requires Android API 29 or higher to support react-native-bare-kit.

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "minSdkVersion": 29
          }
        }
      ]
    ]
  }
}

npx expo install expo-build-properties

Step 3: Configure the Bundle

The WDK engine runs inside a Bare worklet. Use the @tetherto/wdk-worklet-bundler CLI to generate an HRPC bundle with only the modules you need:

# 1. Install the bundler CLI
npm install -g @tetherto/wdk-worklet-bundler@1.0.0-beta.14

# 2. Initialize configuration in your React Native project
wdk-worklet-bundler init

# 3. Edit wdk.config.js to configure your networks (see example below)

# 4. Install required WDK modules (pick the ones you need)
npm install @tetherto/wdk @tetherto/wdk-wallet-evm-erc-4337

# 5. Generate the bundle
wdk-worklet-bundler generate

This generates a .wdk/ directory in your project. Import it:

import { bundle } from './.wdk'

@tetherto/pear-wrk-wdk provides worklet transport and runtime handlers; it does not export a pre-built WDK bundle.

Step 4: Configure WDK Settings

Create a configuration file for your WDK setup (e.g., src/config/wdk.ts):

Set EXPO_PUBLIC_SEPOLIA_TEST_TOKEN_ADDRESS to a six-decimal USD₮ test token currently supported by your configured paymaster on Sepolia. Verify the address, decimals, and paymaster support through the provider's faucet and Sepolia deployment data. The address is public configuration. Use the same value in the wallet configuration and asset used for transfers.

The example uses Expo CLI environment-variable loading. For a bare React Native app, obtain the address through your existing public-config mechanism or replace the exported constant's value with the verified address; installing Expo modules alone does not load this environment variable.

// src/config/wdk.ts
import type { WdkConfigs } from '@tetherto/wdk-react-native-core'

export const sepoliaTestTokenAddress: string = process.env.EXPO_PUBLIC_SEPOLIA_TEST_TOKEN_ADDRESS ?? ''
if (!/^0x[0-9a-fA-F]{40}$/.test(sepoliaTestTokenAddress)) {
  throw new Error('Set EXPO_PUBLIC_SEPOLIA_TEST_TOKEN_ADDRESS to your verified test token')
}

export const wdkConfigs: WdkConfigs = {
  networks: {
    ethereum: {
      blockchain: 'ethereum',
      config: {
        chainId: 11155111, // Sepolia testnet
        safeModulesVersion: '0.3.0',
        provider: 'https://rpc.sepolia.org',
        bundlerUrl: 'https://api.candide.dev/public/v3/11155111',
        paymasterUrl: 'https://api.candide.dev/public/v3/11155111',
        paymasterAddress: '0x8b1f6cb5d062aa2ce8d581942bbb960420d875ba',
        transferMaxFee: 5000000,
        paymasterToken: {
          address: sepoliaTestTokenAddress,
        },
      },
    },
    // Add more networks as needed
  },
}

Step 5: Add WdkAppProvider

Wrap your app with WdkAppProvider to enable wallet functionality throughout your app.

// app/_layout.tsx
import { WdkAppProvider } from '@tetherto/wdk-react-native-core'
import { bundle } from '../.wdk'
import { Stack } from 'expo-router'
import { wdkConfigs } from '../src/config/wdk'

export default function RootLayout() {
  return (
    <WdkAppProvider bundle={{ bundle }} wdkConfigs={wdkConfigs}>
      <Stack />
    </WdkAppProvider>
  )
}

Step 6: Use Hooks

Now you can use the WDK hooks in any component inside WdkAppProvider:

React Native Core beta.17 and later never guesses which wallet to unlock. Keep the selected wallet ID in your authenticated application state and pass it explicitly. LOCKED.walletId is only an optional hint while a specific wallet is already being targeted.

import { useWdkApp, useWalletManager, useAccount } from '@tetherto/wdk-react-native-core'

function WalletScreen({
  walletId,
  authenticate,
}: {
  walletId: string
  authenticate: () => Promise<boolean>
}) {
  const { state } = useWdkApp()
  const { createWallet, unlock } = useWalletManager()
  const { address } = useAccount({ network: 'ethereum', accountIndex: 0 })

  const create = async () => {
    if (await authenticate()) await createWallet(walletId)
  }

  const open = async () => {
    if (await authenticate()) await unlock(state.walletId ?? walletId)
  }

  switch (state.status) {
    case 'INITIALIZING':
    case 'REINITIALIZING':
      return <Text>Loading...</Text>
    case 'NO_WALLET':
      return <Button title="Create Wallet" onPress={create} />
    case 'LOCKED':
      return <Button title="Unlock" onPress={open} />
    case 'READY':
      return <Text>Address: {address}</Text>
    case 'ERROR':
      return <Text>Error: {state.error.message}</Text>
  }
}

For the full list of available hooks and their parameters, see the React Native Core API Reference.

Step 7: Rebuild and Run

npx expo prebuild --clean
npx expo run:ios
# or
npx expo run:android

Congratulations! You've successfully integrated WDK into your React Native app!

What's Next?

Now that you have WDK integrated, here's what you can explore:

Send Transactions

Use the useAccount() hook to send transactions:

// src/screens/SendScreen.tsx
import { useAccount, BaseAsset } from '@tetherto/wdk-react-native-core'
import { sepoliaTestTokenAddress } from '../config/wdk'

const usdt = new BaseAsset({
  id: 'usdt-ethereum',
  network: 'ethereum',
  symbol: 'USDT',
  name: 'Tether USD',
  decimals: 6,
  isNative: false,
  address: sepoliaTestTokenAddress,
})

function SendScreen({ recipient }: { recipient: string }) {
  const { address, send } = useAccount({ network: 'ethereum', accountIndex: 0 })

  const handleSend = async () => {
    if (!address) return

    const result = await send({
      to: recipient,
      asset: usdt,
      amount: '1000000', // 1 USDt (6 decimals)
    })

    if (result.success) {
      console.log('TX hash:', result.hash, 'Fee:', result.fee)
    } else {
      console.error('TX failed:', result.error)
    }
  }

  return <Button title="Send 1 USDt" onPress={handleSend} />
}

This token configuration is for Sepolia. Validate the recipient for the configured chain and require the user to review the recipient, asset, amount, and fee before calling send().

Lock the Wallet

Use lock() to clear the active wallet identity and local address state:

function LockButton() {
  const { lock } = useWalletManager()

  const handleLock = async () => {
    // This does not stop the worklet or confirm disposal completion.
    await lock()
  }

  return <Button title="Lock" onPress={handleLock} />
}

When a wallet is active, lock() sends a one-way full WDK disposal request and then resets local lifecycle flags. The Bare worklet and IPC connection stay running, and the call does not wait for worklet cleanup acknowledgement. Treat it as an application access boundary, not evidence that every seed or key copy was erased from memory.

Refresh Balances

import { useRefreshBalance } from '@tetherto/wdk-react-native-core'

const { mutate: refreshBalance } = useRefreshBalance()

// Refresh all balances for account 0
refreshBalance({ accountIndex: 0, type: 'wallet' })

Troubleshooting

Android build fails with "Execution failed for task ':app:checkDebugAarMetadata'"

This means your minSdkVersion is too low. Make sure you've set it to 29:

{
  "expo": {
    "plugins": [
      ["expo-build-properties", { "android": { "minSdkVersion": 29 } }]
    ]
  }
}

Then rebuild:

npx expo prebuild --clean
npx expo run:android

"useWdkApp must be used within WdkAppProvider"

Ensure your component is rendered inside WdkAppProvider. The provider must be at the root of your component tree:

// Correct
<WdkAppProvider bundle={{ bundle }} wdkConfigs={configs}>
  <MyComponent />  {/* Can use useWdkApp() here */}
</WdkAppProvider>

// Wrong - hook used outside provider
<MyComponent />  {/* Cannot use useWdkApp() here */}
<WdkAppProvider bundle={{ bundle }} wdkConfigs={configs}>
  ...
</WdkAppProvider>

No biometric prompt appears before a wallet operation

React Native Core beta.20 does not enforce biometrics and does not accept a requireBiometrics provider prop. Run your app's biometric, passcode, or other authentication flow before calling createWallet(), restoreWallet(), unlock(), switchWallet(), or key-access methods.

For background locking, revoke the app's authenticated UI state synchronously, then call and catch lock(). The lifecycle mutex rejects instead of queuing when another guarded operation is running, so track a pending lock and retry it after the in-flight guarded operation settles. Require authentication again on foreground and do not treat the SDK session as locked until a retry succeeds.

Worklet startup reports an error

After fixing the reported bundle, configuration, or native startup cause, restart the application so it creates a fresh JavaScript runtime. React Native Core beta.20 has no supported in-process recovery from a failed worklet start; remounting WdkAppProvider in the same runtime does not reset its readiness state.

Metro cache issues

If you see stale module errors after upgrading, clear the Metro cache:

npx expo start --clear
# or
npx react-native start --reset-cache

TypeScript cannot resolve React Native Core

Beta.20's published default and types export targets are absent. Configure TypeScript to select the included React Native source export:

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "customConditions": ["react-native"]
  }
}

Use a current React Native or Expo Metro configuration that honors package exports and retains the react-native condition. skipLibCheck can suppress checks inside declarations after resolution; it cannot repair the missing beta.20 export targets.

Complete Setup Checklist

For Expo projects:

• Install @tetherto/wdk-react-native-core plus its expo-crypto and react-native-bare-kit peer dependencies
• Configure Android minSdkVersion to 29 in app.json
• Set up bundle (custom or pre-built)
• Create WdkConfigs configuration
• Add WdkAppProvider to app/_layout.tsx
• Use hooks (useWdkApp, useWalletManager, useAccount, useBalance)
• Run npx expo prebuild --clean before building

For bare React Native:

• Install @tetherto/wdk-react-native-core plus its expo-crypto and react-native-bare-kit peer dependencies
• Install and configure Expo modules before adding expo-crypto
• Set minSdkVersion to 29 in android/build.gradle
• Set up bundle (custom or pre-built)
• Create WdkConfigs configuration
• Wrap root component with WdkAppProvider
• Rebuild native code

Learn More

Ready to dive deeper? Check out these resources:

Core Concepts

• React Native Core Docs - Full documentation for @tetherto/wdk-react-native-core
• API Reference - Complete hook and type reference
• Chain Configuration - Configure blockchain networks

Examples & Starters

• React Native Starter - Full-featured starter app
• Customize the starter UI - Edit its app-owned components and theme

Need Help?