# Wavelength

> Embed a self-custodial Lightning wallet in your app: send and receive
> Lightning payments with no node to run, no channels to open, and no inbound
> liquidity to manage.

Notes for agents:

- Every docs page has a markdown twin at the same URL with .md appended.
  Fetch the .md URLs below instead of the HTML.
- Check the npm registry for current @lightninglabs/wavelength-* versions
  instead of relying on memorized ones.
- For integration work, install the Wavelength skills:
  npx skills add lightninglabs/wavelength-sdk (goes live at launch)
  npx skills add wavelength.lightning.engineering
- The full corpus in one file: https://wavelength.lightning.engineering/llms-full.txt

## SDK

- [What is the Wavelength SDK?](https://wavelength.lightning.engineering/introduction/what-is-wavelength-sdk.md): An overview of the Wavelength SDK as a self-custodial Bitcoin, Lightning, and Ark wallet that embeds in your web or mobile app.
- [The Wavelength system](https://wavelength.lightning.engineering/introduction/the-wavelength-system.md): How Wavelength turns self-custodial Bitcoin and Lightning payments into a few API calls, and where Wavelength, the client you run, fits into the larger system.
- [System architecture](https://wavelength.lightning.engineering/introduction/system-architecture.md): How Wavelength's embedded wallet daemon connects to the Ark, Lightning, and Bitcoin backend gateways to enable payments, boarding, swaps, and exits.
- [Balances & VTXOs](https://wavelength.lightning.engineering/concepts/balances-and-vtxos.md): How Wavelength represents spendable funds as Virtual Transaction Outputs (VTXOs) and tracks their lifecycle from boarding through Ark rounds to final confirmation.
- [Activity & events](https://wavelength.lightning.engineering/concepts/activity-and-events.md): How the Wavelength SDK exposes wallet history and real-time state changes through its activity stream and event model.
- [Wallet lifecycle & auth](https://wavelength.lightning.engineering/concepts/wallet-lifecycle-and-auth.md): The phases a Wavelength wallet moves through from creation to unlock, and how password-based and passkey-based authentication differ.
- [Keys, backup & recovery](https://wavelength.lightning.engineering/concepts/keys-backup-and-recovery.md): How the Wavelength SDK derives the wallet seed from a passkey or password, what is stored where, and how users get their funds back on a new device.
- [Lightning payments = swaps](https://wavelength.lightning.engineering/concepts/lightning-payments-are-swaps.md): How Wavelength sends and receives Lightning as Lightning↔Ark atomic swaps.
- [Networks & config](https://wavelength.lightning.engineering/concepts/networks-and-config.md): How to configure the Wavelength SDK for signet, testnet, or mainnet with flat RuntimeConfig fields, defaultConfig presets, and platform-specific endpoints.
- [Leaving Ark](https://wavelength.lightning.engineering/concepts/leaving-ark.md): The two paths for withdrawing funds from Ark - cooperative leave for speed and unilateral exit for trustlessness - and when to choose each.
- [Quickstart (React)](https://wavelength.lightning.engineering/web/get-started/quickstart.md): Get a Wavelength-powered React app running in five minutes - install the packages, wire the provider, create a wallet, and send your first payment.
- [Run the demo app](https://wavelength.lightning.engineering/web/get-started/run-the-demo-app.md): How to clone, install, and run the Wavelength demo app locally against regtest, testnet, or a custom backend.
- [Demo app](https://wavelength.lightning.engineering/web/support/demo-app.md): An overview of the Wavelength reference integration app - what it demonstrates and how to run it locally.
- [Installation](https://wavelength.lightning.engineering/web/get-started/installation.md): How to add the wavelength-web and wavelength-react packages to your project, including required peer dependencies.
- [Requirements](https://wavelength.lightning.engineering/web/get-started/requirements.md): The browser support matrix, cross-origin isolation prerequisites, and backend services needed to integrate the Wavelength SDK.
- [Hosting runtime assets](https://wavelength.lightning.engineering/web/get-started/hosting-runtime-assets.md): How the Wavelength SDK loads its WebAssembly runtime, and how to obtain and host the asset set for your deployment.
- [Cross-origin isolation](https://wavelength.lightning.engineering/web/get-started/cross-origin-isolation.md): Why the Wavelength SDK's WebAssembly runtime requires cross-origin isolation and how to set the COOP/COEP headers on your server.
- [Data & persistence](https://wavelength.lightning.engineering/web/runtime/data-and-persistence.md): How Wavelength stores wallet data using OPFS or localStorage and how storage responsibilities are split between the main thread and the worker.
- [Browser support](https://wavelength.lightning.engineering/web/support/browser-support.md): The compatibility matrix showing which browsers and versions support the Wavelength SDK's WebAssembly runtime, OPFS storage, and passkey features.
- [Troubleshooting / FAQ](https://wavelength.lightning.engineering/web/support/troubleshooting.md): Solutions to common Wavelength SDK integration errors and guidance for diagnosing stuck or pending sends.
- [Quickstart (React Native)](https://wavelength.lightning.engineering/react-native/get-started/quickstart.md): Get a Wavelength-powered React Native app running - install the packages, wire the provider, create a wallet, and send your first payment.
- [Run the demo app](https://wavelength.lightning.engineering/react-native/get-started/run-the-demo-app.md): Build and run the React Native reference wallet on a device or simulator.
- [Installation](https://wavelength.lightning.engineering/react-native/get-started/installation.md): Install the React Native packages, enable the New Architecture, and stage the native wallet runtime.
- [Requirements](https://wavelength.lightning.engineering/react-native/get-started/requirements.md): Platform, OS, and passkey requirements for the React Native SDK.
- [Passkey setup](https://wavelength.lightning.engineering/react-native/get-started/passkey-setup.md): Associate your relying-party domain with your app so native passkeys work on Android and iOS.
- [Troubleshooting](https://wavelength.lightning.engineering/react-native/troubleshooting.md): Fixes for the common React Native integration failure modes.
- [Native iOS & Android overview](https://wavelength.lightning.engineering/native-ios-android/overview.md): The Wavelength native mobile SDK - idiomatic Kotlin and Swift wrappers over the embedded wallet daemon, for apps built without React Native.
- [Native SDK architecture](https://wavelength.lightning.engineering/native-ios-android/architecture.md): How the embedded wallet daemon runs inside a native iOS or Android app - the in-process daemon, the gomobile facade, the JSON boundary, and the callback-free API.
- [Quickstart (native iOS & Android)](https://wavelength.lightning.engineering/native-ios-android/quickstart.md): Run the embedded Wavelength wallet from the wavelength-mobile checkout - stage the bindings, boot the daemon, create a wallet, and read the balance from Kotlin or Swift.
- [React](https://wavelength.lightning.engineering/integrations/react.md): How to integrate the Wavelength SDK into a React application using the provider-injected engine, the available hooks, and the passkey ceremony helpers.
- [Create a wallet (password)](https://wavelength.lightning.engineering/guides/create-a-wallet.md): Create a password-protected Wavelength wallet in a React app, with inline code at each step.
- [Restore a wallet](https://wavelength.lightning.engineering/guides/restore-a-wallet.md): Rebuild a Wavelength wallet from a recovery phrase, and bring back balances and history with background server-assisted recovery.
- [Get a deposit address](https://wavelength.lightning.engineering/guides/get-a-deposit-address.md): How to derive a Wavelength boarding address for on-chain deposits into Ark.
- [Show balance & activity](https://wavelength.lightning.engineering/guides/show-balance-and-activity.md): How to read the Wavelength balance and subscribe to the activity stream to display transaction history in your UI.
- [Send a payment](https://wavelength.lightning.engineering/guides/send-a-payment.md): How to send sats over Lightning (send swap) or on-chain (cooperative leave) using the prepare then confirm flow.
- [Receive a Lightning payment](https://wavelength.lightning.engineering/guides/receive-a-lightning-payment.md): How to generate a Lightning invoice via an atomic swap and wait for the payment to settle.
- [Use a passkey](https://wavelength.lightning.engineering/guides/use-a-passkey.md): How to create and unlock a Wavelength wallet using platform passkeys instead of a password.
- [Handle phases & errors](https://wavelength.lightning.engineering/guides/handle-phases-and-errors.md): How to respond to Wavelength wallet phase transitions and interpret structured error codes in your application.
- [Unilateral exit & status](https://wavelength.lightning.engineering/guides/unilateral-exit.md): Choose between a cooperative leave and a unilateral exit, start one with useWalletExit or useWalletExitBatch, and track it with the status and summary hooks.
- [wavelength-core](https://wavelength.lightning.engineering/reference/wavelength-core.md): Cross-platform interfaces, shared types, and error codes that every Wavelength SDK platform target builds on.
- [wavelength-react](https://wavelength.lightning.engineering/reference/wavelength-react.md): React bindings for the Wavelength SDK - the WavelengthProvider component and hooks for balance, activity, and wallet operations.
- [wavelength-web](https://wavelength.lightning.engineering/reference/wavelength-web.md): Browser SDK factory, configuration, and passkey ceremony API for Wavelength web apps.
- [wavelength-react-native](https://wavelength.lightning.engineering/reference/wavelength-react-native.md): React Native transport factory, native passkey ceremony, and data-directory API.
- [Glossary](https://wavelength.lightning.engineering/glossary.md): Definitions of key Wavelength, Ark, and Lightning Network terms used throughout the documentation.

## API

- [API](https://wavelength.lightning.engineering/api.md): Remote gRPC and REST access to the wallet daemon for server-side integrations.
- [Get started](https://wavelength.lightning.engineering/api/get-started.md): Build waved with the wallet API enabled and make your first call over gRPC or REST.
- [REST conventions](https://wavelength.lightning.engineering/api/rest.md): The request, error, and streaming shape shared by every wallet API route.
- [Create - API reference](https://wavelength.lightning.engineering/api/wallet/create.md): Create initializes a new wallet from a freshly generated aezeed mnemonic. The daemon generates the seed, encrypts it with the supplied password, and returns the mnemonic so the caller can record it. For recovery flows the caller MAY supply an existing mnemonic in the request; in that case the same mnemonic is echoed back. Proxies waverpc.GenSeed + waverpc.InitWallet server-side.
- [Unlock - API reference](https://wavelength.lightning.engineering/api/wallet/unlock.md): Unlock decrypts the on-disk wallet seed using the supplied password and starts the wallet subsystem. Proxies waverpc.UnlockWallet.
- [Status - API reference](https://wavelength.lightning.engineering/api/wallet/status.md): Status returns a wallet-level readiness summary: daemon readiness, wallet-unlocked state, balance summary, pending-entry count. Kept in the proto for programmatic callers; not surfaced as a CLI verb (the `getinfo` CLI verb covers the human-facing readiness view).
- [PrepareSend - API reference](https://wavelength.lightning.engineering/api/wallet/prepare-send.md): PrepareSend validates and previews an outbound payment without moving funds. The response carries a short-lived send_intent_id that must be consumed by Send.
- [Send - API reference](https://wavelength.lightning.engineering/api/wallet/send.md): Send dispatches a previously prepared outbound payment. The request is intentionally intent-only: callers must use PrepareSend first so they can present amount, rail, fee, and total-outflow details before funds move.
- [Recv - API reference](https://wavelength.lightning.engineering/api/wallet/recv.md): Recv asks the daemon for a Lightning invoice the caller can hand out. Internally the daemon sets up the inbound receive via its owned swap subsystem; the invoice is signed with a daemon-managed key, not an ephemeral process-local key.
- [Deposit - API reference](https://wavelength.lightning.engineering/api/wallet/deposit.md): Deposit returns a boarding onchain address the caller can fund. The daemon rolls the boarding output into a VTXO during the next round. Surfaced internally and via `recv --onchain`; not a top-level CLI verb.
- [Balance - API reference](https://wavelength.lightning.engineering/api/wallet/balance.md): Balance returns the unified balance across confirmed VTXOs and in-flight inbound and outbound amounts.
- [List - API reference](https://wavelength.lightning.engineering/api/wallet/list.md): List returns the unified wallet view selected by ListRequest.view: ACTIVITY (default) is the merged WalletEntry stream; VTXOS is the live VTXO inventory; ONCHAIN is the boarding-plus-sweep on-chain history. The body oneof on ListResponse discriminates the typed result so agents see a tagged union, not a polymorphic blob.
- [SubscribeWallet - API reference](https://wavelength.lightning.engineering/api/wallet/subscribe-wallet.md): SubscribeWallet streams activity updates as they happen. The stream is resumable: each response carries a monotonic cursor the client can reconnect from to replay everything after it without gaps.
- [InspectActivity - API reference](https://wavelength.lightning.engineering/api/wallet/inspect-activity.md): InspectActivity returns a technical trace for one WalletEntry id.
- [GetExitPlan - API reference](https://wavelength.lightning.engineering/api/wallet/get-exit-plan.md): GetExitPlan previews unilateral-exit readiness for one VTXO. The response includes CPFP fee input requirements and, when funding is needed, a backing-wallet address callers can fund before forced unroll.
- [Exit - API reference](https://wavelength.lightning.engineering/api/wallet/exit.md): Exit queues a cooperative leave for the specified VTXO outpoint by default. When the caller supplies force_unroll_ack exactly, the daemon starts a unilateral unroll instead after checking that the outpoint is present in the local backing wallet's UTXO set.
- [ExitStatus - API reference](https://wavelength.lightning.engineering/api/wallet/exit-status.md): ExitStatus reports the current phase of an unroll job for the specified VTXO outpoint, including recovery chain progress and sweep state. Proxies waverpc.GetUnrollStatus.
- [ExitSummary - API reference](https://wavelength.lightning.engineering/api/wallet/exit-summary.md): ExitSummary reports the wallet-wide portfolio of in-progress exits: one row per active exit plus aggregate totals for the amount still being recovered, the estimated fees, and the estimated net recoverable.
- [SweepWallet - API reference](https://wavelength.lightning.engineering/api/wallet/sweep-wallet.md): SweepWallet previews or broadcasts a normal backing-wallet sweep to a caller-supplied Bitcoin address. This sweeps wallet-managed funds left after CPFP/change/unroll proceeds and does not sweep boarding outputs.

## CLI

- [wavecli](https://wavelength.lightning.engineering/cli.md): The command-line client for the wallet daemon. It issues gRPC calls to a running waved and prints structured JSON suitable for humans and agents.
- [create](https://wavelength.lightning.engineering/cli/create.md): Create a new wallet from a fresh seed, or recover an existing wallet from a mnemonic.
- [unlock](https://wavelength.lightning.engineering/cli/unlock.md): Unlock an existing wallet by decrypting its on-disk seed and starting the wallet subsystem.
- [send](https://wavelength.lightning.engineering/cli/send.md): Send an outbound payment over Lightning (a BOLT-11 invoice) or on-chain (a bech32 address).
- [recv](https://wavelength.lightning.engineering/cli/recv.md): Materialize an inbound payment surface, either a Lightning invoice or a fresh on-chain boarding address.
- [activity](https://wavelength.lightning.engineering/cli/activity.md): Show the merged wallet activity feed, and inspect a single entry with its correlated swap, VTXO, and ledger detail.
- [balance](https://wavelength.lightning.engineering/cli/balance.md): Display the unified wallet balance across confirmed, in-flight inbound, and in-flight outbound amounts.
- [exit](https://wavelength.lightning.engineering/cli/exit.md): Cooperatively exit a VTXO to an on-chain address, or start a forced unilateral unroll.
- [wallet-sweep](https://wavelength.lightning.engineering/cli/wallet-sweep.md): Preview or broadcast a sweep of every confirmed backing-wallet UTXO to a single destination address.
- [getinfo](https://wavelength.lightning.engineering/cli/getinfo.md): Display daemon status, including version, network, wallet state, block height, and identity pubkey.
- [schema](https://wavelength.lightning.engineering/cli/schema.md): Dump machine-readable method schemas as JSON so an agent can self-serve the CLI surface at runtime.
- [mcp](https://wavelength.lightning.engineering/cli/mcp.md): Run a Model Context Protocol server over stdio that exposes each daemon RPC as a typed tool call.
- [ark](https://wavelength.lightning.engineering/cli/ark.md): Advanced, low-level Ark protocol commands over the raw daemon RPC, covering VTXO inventory and lifecycle, round state, out-of-round sessions, boarding, sweeps, fees, and raw sends.
- [recovery](https://wavelength.lightning.engineering/cli/recovery.md): Advanced control-plane commands for daemon-owned vHTLC recovery rows, to inspect, escalate, or cancel already-armed recoveries.
- [dev](https://wavelength.lightning.engineering/cli/dev.md): Generated low-level access to every daemon gRPC method, built automatically from the daemon proto descriptors.

## Agents

- [Build with agents](https://wavelength.lightning.engineering/agents.md): Point your coding agent at the Wavelength docs and let it do the integration work, with installable skills, markdown mirrors, and ready-made prompts.