---
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. Get test coins from the [signet faucet](https://robinet.eldamar.icu/). |
| `'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, its mailbox ID, which `wavecli getinfo` reports as `identity_pubkey`.

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: 'https://headers.example.com/block-headers.bin',
  walletFilterHeadersSource: 'https://headers.example.com/filter-headers.bin',
  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. Some daemon-only options (such as the LND wallet backend) are deliberately not exposed through `RuntimeConfig`.

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.