wavelength-web

Integrates a self-custodial Lightning wallet into web and React apps via WebAssembly.

4|4|Updated Jun 24, 2026
One-click install
npx skills add https://github.com/lightninglabs/wavelength-sdk --skill wavelength-web-lightninglabs
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: wavelength-web
Source: https://github.com/lightninglabs/wavelength-sdk/tree/main/skills/wavelength-web
Command: npx skills add https://github.com/lightninglabs/wavelength-sdk --skill wavelength-web-lightninglabs

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Embedding Lightning payments in a browser app normally requires running a node, managing channels, and handling inbound liquidity. This Skill guides the integration of the Wavelength SDK, which runs a self-custodial Lightning wallet as WebAssembly inside the user's browser, eliminating all server-side infrastructure. ## Core Features & Use Cases - Wallet Engine Setup: Create the wallet engine with createWebWalletEngine() from @lightninglabs/wavelength-web and inject it into React via <WavelengthProvider>. - Payments and Passkeys: Send and receive Lightning payments in the browser and add passkey protection using the injected webPasskeyCeremony with useWalletPasskey. - Runtime Asset Hosting: Self-host the wasm runtime assets, configure runtimeBaseUrl, and set a CSP allowing script-src blob: to avoid the most common integration failures. - Use Case: A React app needs in-browser Lightning payments. Install the web and react packages, copy the wasm assets to a public directory, wire the provider, and confirm the engine phase reaches ready and an invoice can be created. ## Quick Start Use the wavelength-web skill to integrate a self-custodial Lightning wallet into my React app, including engine setup, runtime asset hosting, and a test invoice.

Frequently Asked Questions about wavelength-web

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I embed a Lightning wallet in a web app?

Install @lightninglabs/wavelength-web and @lightninglabs/wavelength-react, create the engine with createWebWalletEngine(), and inject it via <WavelengthProvider engine={...}>. The wallet runs as WebAssembly in a Web Worker with no node or channels to manage.

How do I set up WavelengthProvider in a React app?

Create the engine using createWebWalletEngine() from wavelength-web, then pass it to <WavelengthProvider engine={...}>. The react package is transport-agnostic and deliberately has no dependency on the web transport, so never import wavelength-web inside react-only modules.

Why does the Wavelength SDK fail to load in the browser?

The most common failure is a missing or wrong runtimeBaseUrl, since the wasm runtime assets must be self-hosted in a public directory. Also verify your Content-Security-Policy allows script-src blob:, because the loader executes bootstrap scripts from a blob URL.

Does the Wavelength web wallet persist state across page reloads?

Yes, the daemon persists wallet state to OPFS in the browser, so the wallet survives reloads. Test flows should unlock the existing wallet rather than recreating it on every page load.

How do I add passkey protection to a Wavelength wallet?

Passkey ceremonies are injected rather than implemented manually. Pass webPasskeyCeremony from wavelength-web into useWalletPasskey(ceremony); do not write WebAuthn calls by hand.