React Native Starter (Alpha)

The React Native Starter Alpha is an Expo + React Native app with wallet creation/import, balances, transfers, and optional cloud backup. It runs WDK through React Native Core and BareKit worklets, with app-owned components and theming.

Prerequisites: Node.js 22+, npm 11.10.1+, and either Xcode (iOS) or Android SDK API 29+ with JDK 17 (Android). The starter uses Expo SDK 55 and React Native 0.83.6. Check the repository's environment guide before installing.

Quickstart

Clone and Install

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

The install's postinstall script generates the WDK worklet bundle.

Configure Environment

cp .env.example .env

To load the Activity tab, obtain a production WDK Indexer API key from the Indexer setup guide and set:

EXPO_PUBLIC_WDK_INDEXER_API_KEY=your_actual_api_key_here

The starter selects https://wdk-api.tether.io in src/wdk/indexer.ts. It does not read an EXPO_PUBLIC_WDK_INDEXER_BASE_URL variable. Balance reads and transfers use the network providers configured in .env; review the RPC, bundler, and paymaster settings in .env.example.

Cloud backup has separate Google/CloudKit credentials and can be skipped during initial setup. Follow the starter's cloud backup setup before enabling it.

Run Your App

For first-time setup, generate native project files:

npx expo prebuild

Then run the app:

npm run ios     # iOS Simulator
npm run android # Android Emulator

The starter mixes testnet and mainnet configuration: Ethereum is configured for Sepolia, while Arbitrum and Polygon use mainnet. Before funding or sending, verify the selected network, token, and provider in .env and src/wdk/networks.ts. For Bitcoin, align the wallet's btcNetwork with its Blockbook endpoint; the example testnet endpoint does not change the current btcNetwork: 'bitcoin' address derivation.

Need detailed instructions? Follow the React Native Quickstart for the starter setup, or its separate path for integrating WDK into an existing app.

Features

Networks and assets

The current app configures Bitcoin and EVM networks, including Sepolia, Arbitrum, and Polygon. Assets include BTC and Tether-family tokens. Check src/wdk/networks.ts for the current assets and network mappings. TON and Tron are not wired into this starter.

Wallet management

Seed generation and import: Create or import 12- or 24-word mnemonic phrases through React Native Core.
Seed persistence: Handled by React Native Core's secure-storage layer.
App password vault: Uses wdk-utils encryption and Expo SecureStore; this is separate from seed persistence.
Multi-account support: Derive and switch accounts from a wallet's seed.
Optional cloud backup: Upload encrypted wallet material through @tetherto/wdk-backup-cloud@1.0.0-beta.1 from npm, using Google Drive or CloudKit. The starter's restore screen is not implemented yet; review its cloud backup guide and the Cloud Backup SDK usage before relying on a recovery flow.

Asset management

Balances: Read through React Native Core wallet hooks and the configured network providers.
Transaction history: Fetch recent transfers for configured assets through WDK Indexer; an API key is required.
Price conversion: Fetch fiat prices through the pricing provider.

User experience

Receive QR codes: Display the selected account's address as a QR code.
Send/receive flows: Select an asset and account for transfers.
Network and token selection: Choose from the app's configured registry.
Activity feed: View the transfer history returned by the Indexer.

Indexer Client

The starter installs @tetherto/wdk-indexer-http@1.0.1 from npm. This client requires Node.js 22+ and defaults to the staging endpoint, https://wdk-api.tether.su. The starter explicitly sets the production endpoint to match its API-key registration:

import { WdkIndexerClient } from '@tetherto/wdk-indexer-http'

const apiKey = process.env.EXPO_PUBLIC_WDK_INDEXER_API_KEY
if (!apiKey) throw new Error('Set EXPO_PUBLIC_WDK_INDEXER_API_KEY')

const client = new WdkIndexerClient({
  apiKey,
  baseUrl: 'https://wdk-api.tether.io'
})

Its batch transfer handling uses isApiError() to skip failed items before reading transfers. The earlier isTokenTransfersResponse() helper is no longer exported by the 1.0.1 client. See src/wdk/indexer.ts for the integration.

Project Structure

src/
├── app/                    # Expo Router screens
├── components/             # App-owned UI components
├── data/                   # Data adapters
├── domain/                 # App models and interfaces
├── state/                  # Account and session state
├── theme/                  # Palettes, tokens, ThemeProvider
└── wdk/                    # Networks, wallet hooks, Indexer, cloud backup

See the repository's architecture guide for the wallet and worklet integration.

Available Scripts

Script	Description
`npm start`	Start the Expo development server
`npm run android`	Build and run the Android app
`npm run ios`	Build and run the iOS app
`npm run prebuild`	Regenerate native projects with `expo prebuild --clean`; preserve any manual native changes first
`npm run lint`	Run Expo's lint command
`npm run typecheck`	Run TypeScript without emitting files

Technology Stack

Expo: SDK 55
React Native: 0.83.6
React: 19.2.0
Wallet runtime: React Native Core with BareKit worklets
UI: Local components in src/components and theme definitions in src/theme
Cloud backup: @tetherto/wdk-backup-cloud@1.0.0-beta.1
Indexer client: @tetherto/wdk-indexer-http@1.0.1

The versions above describe this starter's dependencies. Follow its package manifest when upgrading.

Next Steps

Customize the UI

Edit the starter's src/components and src/theme. The local ThemeProvider supplies palettes and design tokens; it does not use the WDK React Native UI Kit.

Add functionality

React Native Core - Work with wallet hooks and providers
WDK SDK - Add wallet and protocol modules
Cloud Backup - Configure encrypted cloud storage
WDK Indexer - Understand the data API

Need Help?

Discord CommunityConnect with developers, ask questions, share your projects

Join Community

GitHub IssuesReport bugs, request features, and get technical help

Open an Issue

Email ContactFor sensitive or private matters, contact our team directly

Send an email

React Native Starter (Alpha)

On this page