React Native Core

Hooks-based React Native library for building multi-chain wallet apps with WDK

React Native Core provides a hooks-based API for wallet management, balance fetching, account operations inside any React Native app.

Features

• Hooks-based architecture - useWdkApp, useWalletManager, useAccount, useBalance, and more

• TanStack Query caching - automatic balance fetching, per-token fallback for modules without batch balance support, cache invalidation, and optimistic updates

• Zustand state management - persisted wallet state with MMKV storage

• Worklet runtime - runs WDK in an isolated Bare worklet

• Biometric authentication - secure storage with device biometrics

• Multi-wallet support - create, restore, switch, lock, unlock, and delete wallets

• TypeScript-first - full type safety with exported types and interfaces

Quick Start

1. Install

npm install @tetherto/wdk-react-native-core

2. Wrap Your App

import { WdkAppProvider } from '@tetherto/wdk-react-native-core'
import { bundle } from './.wdk' // See Bundle Configuration below

export default function App() {
  return (
    <WdkAppProvider bundle={{ bundle }} wdkConfigs={configs}>
      <YourApp />
    </WdkAppProvider>
  )
}

3. Use Hooks

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

function WalletScreen() {
  const { state } = useWdkApp()
  const { createWallet, unlock } = useWalletManager()
  const { address, isLoading } = useAccount({ network: 'ethereum', accountIndex: 0 })

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

For a full integration guide, see the React Native Quickstart.

Bundle Configuration

The WDK engine runs inside a Bare worklet. You need to provide a bundle - there are two approaches:

Custom Bundle (Recommended)

Use the @tetherto/wdk-worklet-bundler CLI to generate a bundle with only the blockchain modules you need:

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

# 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
npm install @tetherto/wdk @tetherto/wdk-wallet-evm-erc-4337

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

Example wdk.config.js:

module.exports = {
  modules: {
    core: '@tetherto/wdk',
    erc4337: '@tetherto/wdk-wallet-evm-erc-4337',
  },
  networks: {
    ethereum: {
      module: 'erc4337',
      chainId: 1,
      blockchain: 'ethereum',
      provider: 'https://eth.drpc.org',
    },
    polygon: {
      module: 'erc4337',
      chainId: 137,
      blockchain: 'polygon',
      provider: 'https://polygon.drpc.org',
    },
  },
}

After running wdk-worklet-bundler generate, import and use the bundle:

import { bundle } from './.wdk'

<WdkAppProvider bundle={{ bundle }} wdkConfigs={configs}>
  <App />
</WdkAppProvider>

For full bundler documentation, see wdk-worklet-bundler.

Pre-built Bundle

For quick prototyping, use the pre-built bundle from @tetherto/pear-wrk-wdk which includes all blockchain modules:

import { bundle } from '@tetherto/pear-wrk-wdk'

<WdkAppProvider bundle={{ bundle }} wdkConfigs={configs}>
  <App />
</WdkAppProvider>

The pre-built bundle includes all blockchain modules, resulting in a larger bundle size. For production apps, generate a custom bundle with only the modules you need.

Architecture

WdkAppProvider
+-- QueryClientProvider (TanStack Query)
+-- Worklet Runtime (react-native-bare-kit)
|   +-- WDK engine (runs in isolated Bare worklet)
+-- Zustand Stores
|   +-- workletStore - worklet lifecycle, initialization state
|   +-- walletStore - addresses, balances, wallet list (persisted to MMKV)
+-- Hooks (public API)
    +-- useWdkApp()         - app state (INITIALIZING, NO_WALLET, LOCKED, READY, ERROR)
    +-- useWalletManager()  - create, restore, lock, unlock, delete wallets
    +-- useAccount()        - address, send, sign, verify, estimateFee
    +-- useAddresses()      - load and query addresses
    +-- useBalance()        - single balance with TanStack Query
    +-- useBalancesForWallet() - bulk balance fetch with per-token fallback
    +-- useRefreshBalance() - invalidate and refetch balances

---

API Reference

Complete reference for all hooks, components, types, and utilities

React Native Quickstart

Step-by-step integration guide for new and existing apps

---

Need Help?

Discord Community

Connect with developers, ask questions, share your projects

Join Community

GitHub Issues

Report bugs, request features, and get technical help

Open an Issue

Email Contact

For sensitive or private matters, contact our team directly

Send an email