---
title: "wavelength-react-native"
description: "React Native transport factory, native passkey ceremony, and data-directory API."
canonical: https://wavelength.lightning.engineering/reference/wavelength-react-native/
---

> Docs index: https://wavelength.lightning.engineering/llms.txt

# wavelength-react-native

React Native transport factory, native passkey ceremony, and data-directory API.

`@lightninglabs/wavelength-react-native` is the React Native transport for the Wavelength SDK: the daemon compiled into the app binary via gomobile bindings, exposed as a standard [`WavelengthClient`](/reference/wavelength-core/#WavelengthClient). [`createNativeWalletEngine()`](#createNativeWalletEngine) wraps that client in a [`WalletEngine`](/reference/wavelength-core/#WalletEngine) in one call, which is the entry point most apps want. It also ships the native (Android Credential Manager / iOS AuthenticationServices) passkey ceremony.

> **One import for the client and every type**
>
> This package re-exports the entire [`@lightninglabs/wavelength-core`](/reference/wavelength-core/) public surface (`export * from '@lightninglabs/wavelength-core'`). You only need to import from `@lightninglabs/wavelength-react-native` to get the client factory, every request/result and nested response type, every core-exported generated string-enum constant, and `defaultConfig()`. This includes `FacadeMethod`, `ActivityStreamOptions`, `EntryProgress`, `CreditPreview`, and the complete activity, list, send, and exit type families. There is no need to also depend on `@lightninglabs/wavelength-core` directly.

## Configuration

## defaultConfig

function

Returns a ready-to-use `RuntimeConfig` for a network, preloaded with the canonical public gRPC host:port addresses the native transport dials, merged with any overrides. This is a shallow merge of top-level `RuntimeConfig` fields. Pass overrides to set `dataDir` or point at your own infrastructure.

```ts
function defaultConfig(
  network: PresetNetwork,
  overrides?: Partial<RuntimeConfig>,
): RuntimeConfig
```

| Parameter   | Type                     | Description                                                                                                                               |
| ----------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `network`   | `PresetNetwork`          | The Bitcoin network to run against; mainnet and regtest are excluded because they have no preset. Use signet for development and testing. |
| `overrides` | `Partial<RuntimeConfig>` | Optional. Fields that override the network preset's defaults. Default: {}.                                                                |

Returns[`RuntimeConfig`](/reference/wavelength-core/#RuntimeConfig)

A complete configuration object for `client.start()` or the engine factory’s `config`.

```ts
import { defaultConfig } from '@lightninglabs/wavelength-react-native';

const config = defaultConfig('signet', { dataDir: '/wallet' });
```

`'mainnet'` and `'regtest'` are not accepted: mainnet has no public deployment yet, and regtest’s local ports vary per development environment. Build their `RuntimeConfig` by hand, mainnet with your own gRPC addresses and `allowMainnet`, regtest with local addresses and the insecure-transport flags. `arkServerAddress` and `swapServerAddress` are gRPC `host:port` values on native, while `walletEsploraUrl` remains an HTTP Esplora endpoint. The per-network endpoint values are on the [wavelength-core reference](/reference/wavelength-core/#Network).

## Creating a client

## createNativeClient

function

Creates and returns a `WavelengthClient` backed by the React Native transport: the daemon compiled into the app via the gomobile bindings. Takes no options in this release; the signature reserves an options object for future use. Activity arrives as typed `activity` events, re-emitted here from native `wavelengthActivity` device events.

```ts
function createNativeClient(): WavelengthClient
```

Returns[`WavelengthClient`](/reference/wavelength-core/#WavelengthClient)

A live client instance. Call `ready()` (resolves immediately, since the runtime is already compiled in) then `start(config)` to boot the daemon.

## createNativeWalletEngine

function

Creates a [`WalletEngine`](/reference/wavelength-core/#WalletEngine) over the React Native transport: the one-call setup for an RN app. It builds the client with `createNativeClient()` internally, so you only need this one factory. Pass the result to `WavelengthProvider` from [wavelength-react](/reference/wavelength-react/).

```ts
function createNativeWalletEngine(
  options?: NativeWalletEngineOptions,
): WalletEngine
```

| Parameter | Type                                                                                         | Description                                                                                      |
| --------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `options` | [`NativeWalletEngineOptions`](/reference/wavelength-react-native/#NativeWalletEngineOptions) | Optional. The engine's config and autoStart; createNativeClient() itself takes no options today. |

Returns[`WalletEngine`](/reference/wavelength-core/#WalletEngine)

A live engine driving a freshly built native client. See [`WalletEngine`](/reference/wavelength-core/#WalletEngine) for its full behavior, including the background processes it runs automatically.

**`NativeWalletEngineOptions`**

[`WalletEngineOptions`](/reference/wavelength-core/#createWalletEngine)’s config/autoStart union minus `client`, which this factory builds for you: the types require a config when autoStart is enabled, so `autoStart: true` without `config` is a compile error.

```ts
type NativeWalletEngineOptions =
  | { config: RuntimeConfig; autoStart: true }
  | { config?: RuntimeConfig; autoStart?: false };
```

| Parameter   | Type                                                         | Description                                                                                                                         |
| ----------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `config`    | [`RuntimeConfig`](/reference/wavelength-core/#RuntimeConfig) | Required when autoStart is true. Default runtime config used by autoStart and by the engine's start() when called with no argument. |
| `autoStart` | `true \| false`                                              | Optional. Start the runtime automatically once it is ready. Setting it to true requires config.                                     |

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

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

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

## Passkeys (native)

## createNativePasskeyCeremony

function

Creates the native implementation of the [`PasskeyCeremony`](/reference/wavelength-core/#PasskeyCeremony) contract (Android Credential Manager, iOS AuthenticationServices). Pass it to `useWalletPasskey` from wavelength-react, or call its methods directly.

```ts
function createNativePasskeyCeremony(
  options: NativePasskeyCeremonyOptions,
): PasskeyCeremony
```

| Parameter | Type                                                                                               | Description                             |
| --------- | -------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `options` | [`NativePasskeyCeremonyOptions`](/reference/wavelength-react-native/#NativePasskeyCeremonyOptions) | Native-specific ceremony configuration. |

Returns[`PasskeyCeremony`](/reference/wavelength-core/#PasskeyCeremony)

The native passkey ceremony. Its `supportsPasskeyPrf()` method is what backs `useWalletPasskey`’s `supported` flag.

Requires the relying-party domain to be associated with your app: `assetlinks.json` on Android, an Associated Domains entitlement plus `apple-app-site-association` on iOS. See the [passkey setup guide](/react-native/get-started/passkey-setup/) for the full walkthrough.

> **iOS support is experimental**
>
> iOS passkey support needs iOS 18 or newer at runtime and is experimental in this release.

## NativePasskeyCeremonyOptions

type

Options for `createNativePasskeyCeremony`.

```ts
type NativePasskeyCeremonyOptions = {
  rpId: string;
};
```

| Parameter | Type     | Description                                                                                                                                                                                                     |
| --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rpId`    | `string` | The WebAuthn relying-party id: the domain whose assetlinks.json (Android) and apple-app-site-association (iOS) vouch for this app. Native apps have no window\.location, so the rpId is explicit configuration. |

## Data directory

## getDefaultDataDir

function

Resolves the platform default wallet data directory: the same directory `createNativeClient`’s client uses when `RuntimeConfig.dataDir` is unset. Exposed for app-level data management (show the storage location, back it up, or wipe it).

```ts
function getDefaultDataDir(): Promise<string>;
```

Returns`Promise<string>`

A plain absolute filesystem path, with no URI scheme. Not guaranteed to exist until the runtime has started.

## See also

- [wavelength-core reference](/reference/wavelength-core/) for `WavelengthClient`, `WalletEngine`, `RuntimeConfig`, `WalletInfo`, `Balance`, `Entry`, and every other re-exported type.
- [wavelength-react reference](/reference/wavelength-react/) for `WavelengthProvider`, `useWalletPasskey`, and the other hooks that consume an engine created here.
- [Passkey setup](/react-native/get-started/passkey-setup/) for the Android and iOS domain-association walkthrough required by `createNativePasskeyCeremony`.