Networks & config

Backend endpoints

Starting the embedded daemon requires backend endpoints that serve the same Bitcoin network. Your app never calls them directly. Misaligned endpoints are a common cause of stuck deposits or swaps that never fund.

RuntimeConfig uses one flat, camelCase shape on both platforms. The endpoint values differ by transport:

1. arkServerAddress is the Ark operator and mailbox edge. It handles rounds, boarding, VTXO relay, cooperative leave, and mailbox traffic. Use a REST URL on web and a host:port gRPC address on React Native. There is no separate mailbox field.
2. swapServerAddress is the swap server for Lightning to Ark atomic swaps. Use a REST URL on web and a host:port gRPC address on React Native.
3. walletEsploraUrl is an HTTP Esplora endpoint on both platforms for chain queries and UTXO lookups. It must implement the Esplora /address/:addr/utxo API (electrs or mempool.space compatible).

All configured services must point at the same network. A mismatched Esplora endpoint or swap server is a common source of “stuck deposit” or “swap never funds” bugs.

defaultConfig presets

For public test networks, use your transport package’s defaultConfig(network) instead of hand-typing URLs. It returns a ready RuntimeConfig with canonical endpoints merged with any overrides you pass:

import { createWebClient, defaultConfig } from '@lightninglabs/wavelength-web';

const client = createWebClient();
const config = defaultConfig('signet', { dataDir: 'my-app-wallet' });
await client.start(config);

import { createNativeClient, defaultConfig } from '@lightninglabs/wavelength-react-native';

const client = createNativeClient();
const config = defaultConfig('signet', { dataDir: 'my-app-wallet' });
await client.start(config);

Presets ship for:

Hosted test-network gateways use TLS. The web preset uses REST URLs, while the React Native preset uses matching host:port gRPC addresses. defaultConfig accepts only these preset networks. 'mainnet' and 'regtest' are excluded: mainnet has no public deployment yet, and regtest’s local ports vary per development environment. Build a RuntimeConfig for either by hand: mainnet with your own endpoints and allowMainnet (see below), regtest with local endpoints and the insecure-transport flags.

Pass overrides as the second argument to change data directory, point at your own operator, or toggle advanced flags without losing the rest of the preset.

allowMainnet

Mainnet is deliberately gated. Set allowMainnet: true together with network: 'mainnet' and your own arkServerAddress, swapServerAddress, and walletEsploraUrl. Without allowMainnet, the SDK rejects the configuration before startup.

Test networks ignore allowMainnet; it exists only for mainnet runs.

Mainnet access

Signet and testnet are open to anyone. Mainnet is different: the mainnet server accepts only clients on an approved allowlist, so allowMainnet on its own is not enough to connect. Access is keyed to your client’s identity, which is its mailbox ID.

To request access, initialize and unlock your wallet, run wavecli getinfo, and copy the identity_pubkey value (a 66-character hex string). Submit that value through the mainnet access request form. Once approved, your client can register and connect. If you re-initialize with a new seed, the identity changes and you have to request access again for the new identity_pubkey.

Complete configuration

Most apps only need defaultConfig(network) plus an optional data directory. Do not copy this advanced example into a quickstart. It shows the flat fields available for self-hosting and specialized deployments:

const config: RuntimeConfig = {
  network: 'signet',
  walletType: 'btcwallet',
  walletFeeUrl: 'https://fees.example.com',
  walletBlockHeadersSource: 'neutrino',
  walletFilterHeadersSource: 'neutrino',
  walletRecoveryWindow: 250,
  maxOperatorFeeSat: 100,
  signingWorkers: 4,
  bufferSize: 64,
};

Common fields

• network, allowMainnet, dataDir, and debugLevel select the network, mainnet safety gate, storage root, and daemon log verbosity.
• arkServerAddress, arkServerTlsCertPath, and arkServerInsecure configure the Ark endpoint. On web, arkServerAddress is a REST URL and filesystem certificate paths for arkServerTlsCertPath are rejected. On React Native, it is a host:port gRPC address.
• swapServerAddress, swapServerTlsCertPath, swapServerInsecure, and swapDatabaseFileName configure the swap service and its state. The web transport accepts swapServerTlsCertPath only when disableSwaps: true, which suppresses every swap field.
• disableSwaps: true disables Lightning swaps and suppresses both preset and override swap fields.
• maxOperatorFeeSat, signingWorkers, and bufferSize are numeric runtime limits. They must be nonnegative safe integers.

Embedded wallet backend fields

• walletEsploraUrl, walletPasswordFile, and walletPollIntervalSeconds apply only to lwwallet.
• walletFeeUrl, walletBlockHeadersSource, and walletFilterHeadersSource apply only to btcwallet.
• walletRecoveryWindow applies to both supported embedded backends.

lwwallet is the default backend. The SDK rejects incompatible backend fields and invalid numeric values before it starts the daemon. LND and eager-round-join disable are intentionally unavailable through this mobile start contract.

On regtest, set both insecure flags yourself because local web gateways speak plain HTTP. On hosted networks, leave them unset so connections stay TLS-verified. If you self-host Ark or swap infrastructure, replace the preset endpoints while keeping the network aligned with your Esplora instance. Full field documentation is in the wavelength-core reference.

Next steps

Once your client is configured and started, see Handle phases and errors for surfacing startup and runtime failures, or Installation if you still need to add the SDK packages to your app.