# React Native Core

**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

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

### 2. Wrap Your App

```tsx
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

```tsx
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](/start-building/react-native-quickstart.md).

## 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:

```bash
# 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`:

```javascript
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:

```typescript
import { bundle } from './.wdk'

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

For full bundler documentation, see [wdk-worklet-bundler](https://github.com/tetherto/wdk-worklet-bundler).

### Pre-built Bundle

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

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

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

{% hint style="info" %}
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.
{% endhint %}

## 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
```

***

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-code">:code:</i></td><td><strong>API Reference</strong></td><td>Complete reference for all hooks, components, types, and utilities</td><td><a href="/pages/r50Nl9r25f6eibbrnFuH">/pages/r50Nl9r25f6eibbrnFuH</a></td></tr><tr><td><i class="fa-mobile-alt">:mobile-alt:</i></td><td><strong>React Native Quickstart</strong></td><td>Step-by-step integration guide for new and existing apps</td><td><a href="/pages/fQOkhG991Dhou3lYFTN4">/pages/fQOkhG991Dhou3lYFTN4</a></td></tr></tbody></table>

***

## Need Help?

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-discord">:discord:</i></td><td><strong>Discord Community</strong></td><td>Connect with developers, ask questions, share your projects</td><td><a href="https://discord.gg/arYXDhHB2w" class="button primary">Join Community</a></td><td><a href="https://discord.gg/arYXDhHB2w">https://discord.gg/arYXDhHB2w</a></td></tr><tr><td><i class="fa-github">:github:</i></td><td><strong>GitHub Issues</strong></td><td>Report bugs, request features, and get technical help</td><td><a href="https://github.com/tetherto/wdk-core" class="button secondary">Open an Issue</a></td><td><a href="https://github.com/tetherto/wdk-core">https://github.com/tetherto/wdk-core</a></td></tr><tr><td><i class="fa-envelope">:envelope:</i></td><td><strong>Email Contact</strong></td><td>For sensitive or private matters, contact our team directly</td><td><a href="mailto:wallet-info.tether.io" class="button secondary">Send an email</a></td><td><a href="mailto:wallet-info.tether.io">mailto:wallet-info.tether.io</a></td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.wdk.tether.io/tools/react-native-core.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.