Quickstart (React Native)

Install the two packages you need: wavelength-react-native for the native wallet runtime and wavelength-react for the React bindings.

npm install @lightninglabs/wavelength-react-native @lightninglabs/wavelength-react

Requires React Native 0.76+ with the New Architecture enabled, iOS 15.1+, and Android minSdk 24. Expo apps need a development build, not Expo Go: the native wallet runtime is a compiled module that Expo Go cannot load. See Requirements for the full platform matrix.

Until hosted binary distribution ships, the native wallet runtime must be staged before the first build; see Installation for the staging step. The native side is built by npx expo run:android / npx expo run:ios (which installs iOS pods automatically), so there is no separate pod step to run by hand.

Create a WalletEngine with createNativeWalletEngine(), and wrap your app with WavelengthProvider. Pass config and autoStart: true to boot the embedded daemon as soon as the runtime is ready, no boot effect needed. Every component below the provider gains access to the wallet through hooks.

import { Text } from 'react-native';
import { createNativeWalletEngine, defaultConfig } from '@lightninglabs/wavelength-react-native';
import { WavelengthProvider, useWallet } from '@lightninglabs/wavelength-react';

const engine = createNativeWalletEngine({
  config: defaultConfig('signet'),
  autoStart: true,
});

export default function App() {
  return (
    <WavelengthProvider engine={engine}>
      <Status />
      {/* your app */}
    </WavelengthProvider>
  );
}

function Status() {
  const { phase } = useWallet();

  return <Text>Wallet phase: {phase}</Text>;
}

defaultConfig(network, overrides?) returns a RuntimeConfig preloaded with public gRPC host:port gateway addresses for that network. Overrides are a shallow merge, so pass only top-level fields such as dataDir. Keep this quickstart on the default config path; see Networks & config for advanced self-hosting fields.

mainnet has no preset: build its RuntimeConfig by hand with allowMainnet: true, and only after you have key-backup UX in place. Mainnet access is also gated to an approved allowlist; see Mainnet access.

Call create from useWalletCreate to generate a new HD seed on the device. The seed is encrypted locally and never transmitted.

import { Button } from 'react-native';
import { useWalletCreate } from '@lightninglabs/wavelength-react';

function Onboard() {
  const { create, createPending } = useWalletCreate();

  const handleCreate = async () => {
    const { mnemonic } = await create({ password: 'a-strong-password' });
    // Back up `mnemonic` securely before the user sends funds.
    console.log('Wallet created');
  };

  return (
    <Button
      title="Create wallet"
      onPress={handleCreate}
      disabled={createPending}
    />
  );
}

Once create resolves, phase from useWallet automatically advances (through 'syncing' when the daemon needs to catch up) to 'ready', so any component watching phase updates without extra wiring.

Call send from useWalletSend with a Lightning invoice or on-chain address. Wavelength routes Lightning payments through the swap server and settles on-chain sends through a cooperative leave with the Ark operator.

import { Button } from 'react-native';
import { useWalletSend } from '@lightninglabs/wavelength-react';

function SendButton() {
  const { send, sendPending } = useWalletSend();

  const handleSend = async () => {
    const result = await send({
      invoice: 'lnbc1…', // or onchainAddress: 'bc1q…'
    });
    console.log('Sent!', result.paymentHash ?? result);
  };

  return <Button title="Send" onPress={handleSend} disabled={sendPending} />;
}

You are all set. Run the app on a device or simulator to see it end to end; see Run the demo app for staging the native runtime binaries and getting a build running.