lawallet-web

Overview

The main application in lawallet-nwc serves the frontend, REST API, and LUD-16 lightning address resolution.

Container: lawallet-web Port: 3000 Storage: Own PostgreSQL database (Prisma ORM)

---

Responsibilities

• Serve frontend (React + Tailwind/shadcn)
• Expose REST API for cards, card designs, users, settings, JWT auth, and remote connections
• Resolve lightning addresses via /api/lud16/[username]
• Optionally create Alby Hub sub-accounts during user creation
• Serve placeholder landing, admin, and wallet pages

Not implemented in the current repo:

• .well-known/lnurlp and .well-known/nostr.json
• Redirect-based address resolution
• Webhook management and payment history APIs
• A completed user dashboard UI

---

Tech Stack

• Framework: Next.js 16 (App Router)
• Language: TypeScript
• Frontend: React + Tailwind CSS + shadcn/ui
• Database: PostgreSQL via Prisma ORM
• NWC: @getalby/sdk
• Testing: Vitest + React Testing Library + MSW
• Logging: pino

---

Directory Structure

---

Key Endpoints

Authentication

• POST /api/jwt — Exchange a NIP-98 request for a JWT
• GET /api/jwt — Validate an existing JWT
• GET /api/jwt/protected — Example protected JWT route
• POST /api/jwt/protected — Example protected JWT route

Users and Addresses

• GET /api/users/me — Load or create the current user
• PUT /api/users/:id/lightning-address — Assign or replace a username
• PUT /api/users/:id/nwc — Store an NWC URI for the user
• GET /api/lightning-addresses — Admin list of lightning addresses
• GET /api/lightning-addresses/counts — Admin counts
• GET /api/lightning-addresses/relays — Relay information
• GET /api/lud16/:username — LUD-16 payRequest for NWC-backed users
• GET /api/lud16/:username/cb — LUD-16 callback

Cards and Card Designs

• GET /api/cards and POST /api/cards — Card listing and creation
• GET /api/cards/:id and DELETE /api/cards/:id — Card detail and deletion
• GET /api/cards/:id/write — Card write payload
• GET /api/cards/:id/scan — LNURL-withdraw style card scan response
• GET /api/cards/:id/scan/cb — Card scan callback
• GET /api/cards/otc/:otc — OTC lookup
• POST /api/cards/otc/:otc/activate — OTC activation
• GET /api/card-designs/list — Card designs
• GET /api/card-designs/count — Card-design count
• GET /api/card-designs/get/:id — Card-design detail
• POST /api/card-designs/import — Import card designs

Admin and Device Flows

• GET /api/settings and POST /api/settings — Settings management
• GET /api/admin/assign and POST /api/admin/assign — Admin assignment
• GET /api/root/assign and POST /api/root/assign — Root assignment
• GET /api/remote-connections/:externalDeviceKey — Remote connection bootstrap
• POST /api/remote-connections/:externalDeviceKey/cards — Remote card initialization

---

External Integrations

• Alby Hub: Optional REST integration used during user creation when automatic provisioning is enabled
• PostgreSQL: Primary datastore

Planned but not currently wired into this repo:

• lncurl courtesy-wallet provisioning
• lawallet-listener payment listener integration