---

LaWallet NWC

Lightning Address Platform and Nostr CRM

An open-source platform for creating, managing, and serving Lightning Addresses connected via NWC. Built on a progressive self-custody model — users start receiving payments instantly through address aliasing, then upgrade to NWC and eventually self-hosting at their own pace.

Pre-Alpha — Do not use real funds. Expect breaking changes.

Try Demo 👇

One Click Deploy 👇

Vercel provisions Postgres for you. On Netlify, bring a Postgres connection string (Neon and Supabase both have free tiers) — see the Netlify guide. Both one-click flows prompt for a dedicated NWC_VAULT_SECRET; it encrypts every stored RemoteWallet NWC connection and the optional proxy credentials. Keep it stable, back it up, and copy the same value to the listener. The NIP-57 signing nsec is entered later in Admin Settings, not as an environment variable.

For Docker or Coolify, generate every required secret and enable the bundled listener in one command:

pnpm deploy:env

For Vercel or Netlify with a separately hosted listener, generate matched web.env and listener.env files:

pnpm deploy:env:cloud

The generator creates independent 256-bit secrets, uses private file permissions, and refuses to overwrite existing output. See the environment-variable guide for what each value does and where to place it.

---

Features

Admin Dashboard

• Nostr-based login (NIP-07 browser extension, NIP-46 remote signing, nsec)
• BoltCard fleet management — designs, NTAG424 cards, OTC activation
• Lightning Address management — domain claim, alias / NWC modes, LUD-16 routing
• Multi-tab Settings — Branding (8 presets + image uploads), Wallet, Infrastructure
• Activity Log + real-time stats via Server-Sent Events

User Wallet

• Onboarding flow with Send / Receive / Scan
• Lightning Address claim and management
• BoltCard pairing and NFC tap-to-pay
• NWC connection (Alby, Primal, or any NWC-compatible wallet)
• Offline cache for resilience

Developer Surface

• OpenAPI 3.1 spec + interactive Scalar Playground
• TypeScript SDK + @lawallet-nwc/react hooks — package extraction in progress (Month 7)
• One-click deploy to Vercel or Netlify; Docker, Umbrel, and Start9 targets available

The public marketing site lives in lawallet-landing. This repo's / redirects there; the product entrypoint is /admin.

---

Architecture

Three independent containerized services with no shared infrastructure:

Service	Container	Status	Role
Web Application	lawallet-web	Active	Next.js frontend, REST API, Lightning Address resolution, dashboards, wallet
Payment Listener	lawallet-listener	Active	Monitors NWC relays, dispatches payment webhooks (transport-only)
NWC Proxy	lawallet-nwc-proxy	M7 (planned)	Provisions courtesy NWC connections via external providers

---

Tech Stack

Layer	Technology
Language	TypeScript 5.9
Framework	Next.js 16 (App Router)
Database	PostgreSQL via Prisma 7.10
Styling	Tailwind CSS 3.4 + shadcn/ui + Radix UI
Lightning / NWC	Alby SDK 8, nostr-tools, @nostrify/nostrify
Testing	Vitest 5 + MSW + happy-dom
Tooling	pnpm 11 workspaces + Turborepo 2
Runtime	Node.js ≥24.21

---

Open Standards

Standard	Protocol	Usage
NIP-47	Nostr Wallet Connect	Payment connections
NIP-05	Nostr Identity	User verification
NIP-07 / NIP-46	Nostr Signing	Browser + remote auth
NIP-57	Zaps	Lightning tips via Nostr
LUD-16	Lightning Address	Address resolution
LUD-21	Verify	Payment verification
LUD-22	Webhooks	Payment notifications
BoltCard	NFC Lightning	NFC card payments

---

Getting Started

Quick Start (development)

Prerequisites: Node v24.21 (nvm use), pnpm 11 (via Corepack), and Docker.

git clone https://github.com/lawalletio/lawallet-nwc.git
cd lawallet-nwc
pnpm start:dev-server

That single command installs dependencies, writes local env files (including a generated JWT_SECRET), starts an isolated per-checkout Postgres, migrates and seeds a fresh database, and serves the admin dashboard at the printed URL. Re-runs are safe: existing data is preserved (pnpm dev:db:reset wipes it on purpose). Use pnpm dev:setup for the same bootstrap without launching the server.

The same flow gives every git worktree its own database, ports, and env — parallel checkouts never collide.

Bootstrap With the CLI

The standalone bootstrap flow is designed for a hosted curl | bash install:

curl -fsSL https://raw.githubusercontent.com/lawalletio/lawallet-nwc/main/install.sh | bash

To force Docker mode and skip prompts:

curl -fsSL https://raw.githubusercontent.com/lawalletio/lawallet-nwc/main/install.sh | \
  bash -s -- --mode docker --yes

That installer:

• installs a user-owned lawallet CLI under ~/.lawallet/bin
• downloads a bundled Node.js runtime when the machine does not already have a compatible one
• persists the CLI on your shell PATH
• runs lawallet install, which clones lawallet-nwc and brings up web, docs, openapi, and PostgreSQL

For local development of the CLI from this repo, use the wrapper script instead:

bash ./scripts/install-lawallet-cli.sh

That wrapper reuses the same root install.sh flow, but installs the CLI package directly from apps/cli instead of npm.

Once an instance is installed, the generated app-management commands are available from apps/web through pnpm service <status|start|stop|restart>.

Useful bootstrap env vars:

LAWALLET_REPO_URL=https://github.com/your-org/lawallet-nwc.git
LAWALLET_CLI_NPM_SPEC=@lawallet-nwc/cli@latest
LAWALLET_INSTALL_SKIP_RUN=true
LAWALLET_INSTALL_SKIP_PROFILE=true

To smoke-test the published bootstrap flow inside Docker, run:

bash ./scripts/test-install-cli-docker.sh

1. Install dependencies

Set the correct Node version with nvm:

nvm use

Install dependencies:

pnpm install

2. Set up environment variables

cp .env.example .env

Edit .env with your own values.

3. Generate Prisma client and run migrations

pnpm prisma generate
pnpm prisma migrate deploy
pnpm prisma db seed

4. Run the development server

pnpm dev

For an isolated one-command worktree setup with its own generated database, environment and seed data, run:

pnpm start:dev-server

This writes local development env files, starts a per-worktree Postgres service, migrates the database (seeding it only when fresh), and prints the ready /admin URL. Existing data is preserved across restarts — run pnpm dev:db:reset (or set DEV_DB_RESET=true) for an explicit wipe.

5. Open your browser

Surface	Local URL
Admin Dashboard	http://localhost:3000/admin
User Wallet	http://localhost:3000/wallet
API Playground	http://localhost:3000/api-docs
Landing redirect	http://localhost:3000 → NEXT_PUBLIC_LAWALLET_LANDING_URL

---

Documentation

The full rendered docs live at docs.lawallet.io. The interactive REST reference is at beta.lawallet.io/api-docs. Source documents in this repo:

Document	Description
ARCHITECTURE.md	System design, data flow, address resolution
ROADMAP.md	8-month development timeline and current progress
ONBOARDING.md	Progressive self-custody: alias → NWC → self-hosted
SDK.md	TypeScript Client SDK + React Hooks reference
TESTING.md	Testing strategy (Vitest, MSW, Playwright)
DOCKER.md	Docker setup and containerized deployment
VISION.md	Long-term vision: CRM + AI + Nostr communications (Beyond M8)

Roadmap by Month

Month	Phase	Focus	Status
1	Foundation	Backend infrastructure + testing	✅ Completed · Report
2	Foundation	CI/CD + Auth flow upgrade	✅ Completed · Report
3	Enhancement	Admin Dashboard + Nostr login + E2E	✅ Completed · Report
4	Enhancement	User Wallet + Admin E2E + schema rewrite	✅ Completed · Report
5	Expansion	Remote Wallets + card system apps + platform polish	✅ Completed · Report
6	Expansion	NWC Payment Listener + deploy targets + backup & restore	✅ Completed · Report
7	Monetization	Subscription Manager + Nostr Chat (DMs) + carried-over M6 closeout	🟡 In Progress
8	Intelligence	AI Agents (own LN address, NWC wallet, scheduled tasks)	⏳ Planned

All eight months are covered by the OpenSats Fifteenth Wave grant (Dec 2025 – Sep 2026). Full month-by-month detail in ROADMAP.md.

---

Contributing

Contributions are welcome. Open an issue to discuss bugs, features, or roadmap items before sending a PR. See docs/TESTING.md for the testing strategy and CLAUDE.md for repo conventions.

---

License

MIT © LaWallet contributors

Developed and maintained by github.com/agustinkassis

---

_{Demo · Docs · API Playground · GitHub}