API Reference

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

const wdkConfigs = {
  networks: {
    ethereum: {
      blockchain: 'ethereum',
      config: {
        chainId: 1,
        provider: 'https://eth.drpc.org',
      },
    },
  },
}

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

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

function AppRouter({
  walletId,
  authenticate,
}: {
  walletId: string
  authenticate: () => Promise<boolean>
}) {
  const { state } = useWdkApp()
  const { createWallet, unlock } = useWalletManager()

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

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

  switch (state.status) {
    case 'INITIALIZING':
    case 'REINITIALIZING':
      return <LoadingScreen />
    case 'NO_WALLET':
      return <Button title="Create Wallet" onPress={create} />
    case 'LOCKED':
      return <Button title="Unlock" onPress={open} />
    case 'READY':
      return <MainApp walletId={state.walletId} />
    case 'ERROR':
      return <ErrorScreen error={state.error} />
  }
}

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

function OnboardingScreen({
  walletId,
  authenticate,
  presentMnemonicForBackup,
}: {
  walletId: string
  authenticate: () => Promise<boolean>
  presentMnemonicForBackup: (mnemonic: string) => Promise<void>
}) {
  const { createWallet, restoreWallet, generateMnemonic } = useWalletManager()

  const handleCreate = async () => {
    if (!(await authenticate())) return
    await createWallet(walletId)
  }

  const handleRestore = async (mnemonic: string) => {
    if (!(await authenticate())) return
    await restoreWallet(mnemonic, walletId)
  }

  const handlePreview = async () => {
    if (!(await authenticate())) return
    const mnemonic = await generateMnemonic(12)
    await presentMnemonicForBackup(mnemonic)
  }

  return (
    <View>
      <Button title="Create Wallet" onPress={handleCreate} />
      <Button title="Generate Mnemonic" onPress={handlePreview} />
    </View>
  )
}

interface UseAccountResponse {
  success: boolean
  error?: string
}

import { Button, Text, View } from 'react-native'
import { useAccount, BaseAsset } from '@tetherto/wdk-react-native-core'

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

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

  if (isLoading) return <Text>Deriving address...</Text>
  if (!address) return <Text>No account available</Text>

  const handleSend = async () => {
    const txParams = {
      to: recipientAddress,
      asset: usdt,
      amount: '1000000', // 1 USDt (6 decimals)
    }

    // Estimate fee first
    const estimate = await estimateFee(txParams)
    console.log('Estimated fee:', estimate.fee)

    // Send the transaction
    const result = await send(txParams)
    if (result.success) {
      console.log('TX hash:', result.hash)
    } else {
      console.error('TX failed:', result.error)
    }
  }

  return (
    <View>
      <Text>Address: {address}</Text>
      <Button title="Send 1 USDt" onPress={handleSend} />
    </View>
  )
}

// Type parameter provides type-safe access to chain-specific methods
const { extension } = useAccount<{ getTransfers: () => Promise<Transfer[]> }>({
  network: 'bitcoin',
  accountIndex: 0,
})

// Safe to call at any time - waits for wallet initialization internally
const btcApi = extension()
const transfers = await btcApi.getTransfers()

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

type SwapProtocol = {
  quoteSwap: (params: {
    tokenIn: string
    tokenOut: string
    tokenInAmount: string
  }) => Promise<{ tokenOutAmount: string; fee: string }>
}

function SwapQuoteScreen() {
  const swap = useProtocol<SwapProtocol>({
    network: 'ethereum',
    accountIndex: 0,
    protocolType: 'swap',
    protocolName: 'velora',
  })

  const loadQuote = async () => {
    const quote = await swap.quoteSwap({
      tokenIn: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
      tokenOut: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
      tokenInAmount: '1000000',
    })

    console.log('Quoted output:', quote?.tokenOutAmount)
  }

  return <Button title="Quote" onPress={loadQuote} />
}

type UseModuleProxy<T extends object> = T & {
  on: (event: string, listener: ModuleEventListener) => () => void
}

type ModuleEventListener = (payload: unknown) => void

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

type PreferencesModule = {
  getTheme: () => Promise<'light' | 'dark'>
  setTheme: (theme: 'light' | 'dark') => Promise<void>
}

function PreferencesScreen() {
  const preferences = useModule<PreferencesModule>('preferences')

  useEffect(() => {
    return preferences.on('changed', payload => {
      console.log('Preferences changed:', payload)
    })
  }, [preferences])

  // Module calls are asynchronous.
  // const theme = await preferences.getTheme()
}

type AddressInfoResult =
  | { network: string; accountIndex: number; success: true; address: string }
  | { network: string; accountIndex: number; success: false; reason: Error }

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

function AddressesScreen() {
  const { data, isLoading, loadAddresses, getAddressesForNetwork } = useAddresses()

  useEffect(() => {
    loadAddresses([0]).then((results) => {
      const failed = results.filter((r) => !r.success)
      if (failed.length > 0) {
        console.warn('Some addresses failed to load:', failed)
      }
    })
  }, [])

  const ethAddresses = getAddressesForNetwork('ethereum')

  if (isLoading) return <Text>Loading addresses...</Text>

  return (
    <View>
      {ethAddresses.map(({ address, accountIndex }) => (
        <Text key={address}>Account {accountIndex}: {address}</Text>
      ))}
    </View>
  )
}

type UseBalanceResult = Omit<UseQueryResult<BalanceFetchResult | undefined, Error>, 'isLoading' | 'error'> & {
  isLoading: boolean
  error: Error | null
}

import { useBalance, BaseAsset } from '@tetherto/wdk-react-native-core'

const eth = new BaseAsset({
  id: 'eth',
  network: 'ethereum',
  symbol: 'ETH',
  name: 'Ether',
  decimals: 18,
  isNative: true,
})

function BalanceDisplay() {
  const { data: balance, isLoading } = useBalance(0, eth, {
    refetchInterval: 30000, // Refresh every 30s
  })

  if (isLoading) return <Text>Loading...</Text>

  if (balance?.success) {
    return <Text>ETH Balance: {balance.balance}</Text>
  }

  return <Text>Failed to fetch balance</Text>
}

type UseBalancesForWalletResult = Omit<UseQueryResult<BalanceFetchResult[], Error>, 'isLoading' | 'error'> & {
  isLoading: boolean
  error: Error | null
}

import { useBalancesForWallet, BaseAsset } from '@tetherto/wdk-react-native-core'

const assets = [
  new BaseAsset({ id: 'eth', network: 'ethereum', symbol: 'ETH', name: 'Ether', decimals: 18, isNative: true }),
  new BaseAsset({ id: 'usdt-eth', network: 'ethereum', symbol: 'USDT', name: 'Tether USD', decimals: 6, isNative: false, address: '0xdAC17F958D2ee523a2206206994597C13D831ec7' }),
]

function PortfolioScreen() {
  const { data: balances, isLoading } = useBalancesForWallet(0, assets, {
    refetchInterval: 60000,
  })

  if (isLoading) return <Text>Loading balances...</Text>

  return (
    <View>
      {balances?.map((b) => (
        <Text key={b.assetId}>
          {b.assetId}: {b.success ? b.balance : 'Error'}
        </Text>
      ))}
    </View>
  )
}

type UseBalancesForWalletsResult = Omit<UseQueryResult<BalanceFetchResult[], Error>, 'isLoading' | 'error'> & {
  isLoading: boolean
  error: Error | null
}

import { useBalancesForWallets, BaseAsset } from '@tetherto/wdk-react-native-core'

const assets = [
  new BaseAsset({ id: 'eth', network: 'ethereum', symbol: 'ETH', name: 'Ether', decimals: 18, isNative: true }),
  new BaseAsset({ id: 'usdt-eth', network: 'ethereum', symbol: 'USDT', name: 'Tether USD', decimals: 6, isNative: false, address: '0xdAC17F958D2ee523a2206206994597C13D831ec7' }),
]

function AccountsPortfolioScreen() {
  const { data: balances, isLoading } = useBalancesForWallets([0, 1, 2], assets, {
    concurrencyLimit: 2,
    refetchInterval: 60000,
  })

  if (isLoading) return <Text>Loading balances...</Text>

  return (
    <View>
      {balances?.map((b) => (
        <Text key={`${b.accountIndex}-${b.assetId}`}>
          Account {b.accountIndex} {b.assetId}: {b.success ? b.balance : 'Error'}
        </Text>
      ))}
    </View>
  )
}

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

function RefreshButton() {
  const { mutate: refreshBalance, isPending } = useRefreshBalance()

  return (
    <Button
      title="Refresh All Balances"
      disabled={isPending}
      onPress={() => refreshBalance({ accountIndex: 0, type: 'wallet' })}
    />
  )
}

new BaseAsset(config: AssetConfig)

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

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

console.log(usdt.getSymbol())          // 'USDT'
console.log(usdt.isNative())           // false
console.log(usdt.getContractAddress()) // '0xdAC17F958D2ee523a2206206994597C13D831ec7'

interface IAsset {
  getId(): string
  getNetwork(): string
  getSymbol(): string
  getName(): string
  getDecimals(): number
  isNative(): boolean
  getContractAddress(): string | null
}

interface WdkConfigs<TNetwork = Record<string, unknown>, TProtocol = Record<string, unknown>> extends WdkWorkletConfig {
  networks: {
    [blockchain: string]: WdkNetworkConfig<TNetwork>
  }
  protocols?: {
    [protocolName: string]: WdkProtocolConfig<TProtocol>
  }
  modules?: {
    [moduleName: string]: Record<string, unknown>
  }
}

interface WdkNetworkConfig<T = Record<string, unknown>> extends NetworkConfig {
  blockchain: string
  config: T
}

interface WdkProtocolConfig<T = Record<string, unknown>> extends ProtocolConfig {
  blockchain: string
  protocolName: string
  config: T
}

type AssetConfig<T = Record<string, unknown>> = T & {
  id: string           // Unique identifier
  network: string      // Network this asset belongs to
  symbol: string       // Ticker symbol
  name: string         // Human-readable name
  decimals: number     // Decimal places
  isNative: boolean    // true for native chain currency
  address?: string | null  // Token contract address (null for native)
}

interface BalanceFetchResult {
  success: boolean        // Whether the fetch succeeded
  network: string         // Network name
  accountIndex: number    // Account index
  assetId: string         // Asset identifier
  balance: string | null  // Balance as string (null if failed)
  error?: string          // Error message (only if success is false)
}

interface BundleConfig {
  bundle: string  // Compiled JavaScript bundle for the worklet runtime
}

interface BalanceQueryOptions {
  enabled?: boolean              // Whether the query is enabled (default: true)
  refetchInterval?: number | false  // Refetch interval in ms (false to disable)
  staleTime?: number             // Stale time in ms
}

interface WalletInfo {
  identifier: string  // Wallet identifier (e.g., user email)
  exists: boolean     // Whether wallet exists in secure storage
}

interface AccountInfo {
  accountIndex: number              // Account index (0-based)
  addresses: Record<string, string> // Address for each network
}

import { createSecureStorage } from '@tetherto/wdk-react-native-core'
import type { SecureStorage } from '@tetherto/wdk-react-native-core'

const storage: SecureStorage = createSecureStorage()

import {
  createSecureStorage,
  DEFAULT_IDENTIFIER,
} from '@tetherto/wdk-react-native-core'

const storage = createSecureStorage()
const hasLegacyWallet = await storage.hasWallet(DEFAULT_IDENTIFIER)

function validateMnemonic(mnemonic: string): boolean

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

validateMnemonic('word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12')
// true

validateMnemonic('only three words')
// false

const balanceQueryKeys = {
  all: ['balances'],
  byWallet: (walletId: string, accountIndex: number) => [...],
  byNetwork: (network: string) => [...],
  byWalletAndNetwork: (walletId: string, accountIndex: number, network: string) => [...],
  byToken: (walletId: string, accountIndex: number, network: string, assetId: string) => [...],
}

import { balanceQueryKeys } from '@tetherto/wdk-react-native-core'
import { useQueryClient } from '@tanstack/react-query'

const queryClient = useQueryClient()

// Invalidate all balances for a specific wallet
queryClient.invalidateQueries({
  queryKey: balanceQueryKeys.byWallet('user@example.com', 0),
})