Installation

The packages

The Wavelength SDK ships as three npm packages. You install one or two of them depending on your stack:

Package	What it is
`@lightninglabs/wavelength-core`	Types, the `WavelengthClient` interface, errors, and enums. Pulled in transitively; you rarely install it directly.
`@lightninglabs/wavelength-web`	The browser WASM transport. Framework-agnostic: use it from vanilla JS, Vue, Svelte, or React. Re-exports everything from `core`.
`@lightninglabs/wavelength-react`	React provider and hooks. Transport-agnostic: it takes an injected engine and depends only on `core`.

React apps need the web transport and the React bindings:

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

Vanilla JS, Vue, Svelte, or other non-React frameworks need only the web transport:

npm install @lightninglabs/wavelength-web

Before wiring up the code samples below, make sure the browser environment you’re deploying to meets the requirements and serves your app with the headers described in Cross-origin isolation. The Wavelength SDK’s WebAssembly runtime will not start without them.

Peer deps

@lightninglabs/wavelength-react declares react as a peer dependency, with an accepted range of ^18.0.0 || ^19.0.0. Your app must also provide react-dom (or the equivalent for your React renderer). Either major version, 18 or 19, works:

npm install react react-dom

Build the wallet engine once near the root of your app. createWebWalletEngine accepts WebWalletEngineOptions (for example runtimeBaseUrl pointing at hosted WASM assets, see Hosting runtime assets), plus config and autoStart to boot the embedded daemon as soon as the runtime is ready, no boot effect needed.

import { WavelengthProvider, useWallet, useWalletBalance } from '@lightninglabs/wavelength-react';
import { createWebWalletEngine, defaultConfig } from '@lightninglabs/wavelength-web';

// Configure transport options once. runtimeBaseUrl points at the hosted WASM
// asset folder.
const engine = createWebWalletEngine({
  runtimeBaseUrl: 'https://your-host/wavewalletdk/',
  config: defaultConfig('signet'),
  autoStart: true,
});

export function App() {
  return (
    <WavelengthProvider engine={engine}>
      <Wallet />
    </WavelengthProvider>
  );
}

function Wallet() {
  const { phase, error } = useWallet();
  const balance = useWalletBalance();

  if (phase !== 'ready') {
    return <p>Loading… ({phase})</p>;
  }

  return <p>Spendable: {balance?.confirmedSat ?? 0} sats</p>;
}

error from useWallet holds the last fatal runtime-level error: set when the initial runtime load fails or when start/stop fails. Render it instead of dropping the failure on the floor.

For a non-React app, skip the provider and call start on the client directly after ready() resolves:

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

const client = createWebClient({
  runtimeBaseUrl: 'https://your-host/wavewalletdk/',
});

await client.ready();
await client.start(defaultConfig('signet'));

Next steps

Requirements: confirm the browser support matrix and backend services the Wavelength SDK needs.
Hosting runtime assets: obtain the WebAssembly runtime asset set and serve it from your own host.
Quickstart: wire up the provider, create a wallet, and send your first payment.