---
title: "Networks & config"
description: "How to configure the Wavelength SDK for signet, testnet, or mainnet with flat RuntimeConfig fields, defaultConfig presets, and platform-specific endpoints."
canonical: https://wavelength.lightning.engineering/concepts/networks-and-config/
---

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

# 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:

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

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

```ts
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:

| Network     | Typical use                                                                               |
| ----------- | ----------------------------------------------------------------------------------------- |
| `'signet'`  | Default for docs live embeds and the demo app; public Lightning Labs test infrastructure. |
| `'testnet'` | Bitcoin testnet3 with hosted Ark/swap gateways.                                           |

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.

> **Caution**
>
> `allowMainnet` is an explicit safety rail. Do not enable it in example code or demos that users might copy against production networks by accident.

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](https://docs.google.com/forms/d/e/1FAIpQLScX-AwTYPCRqD9WI2LOtalgL25PSOJ__I6Gf4D8xW04WyWCpA/viewform). 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:

```ts
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](/reference/wavelength-core/).

## Next steps

Once your client is configured and started, see [Handle phases and errors](/guides/handle-phases-and-errors/) for surfacing startup and runtime failures, or [Installation](/web/get-started/installation/) if you still need to add the SDK packages to your app.