NIP-47 defines a secure communication protocol between a client app and a wallet service using Nostr-based encrypted messages. This allows applications to request payments or wallet actions without directly handling sensitive credentials.
| Component | Description |
|---|---|
| Client (app4) | The user's app that initiates transactions (e.g., a mobile app). |
| Wallet Service (app5) | The server managing the user's Lightning wallet, processing transactions. |
| NWC URI (nostr+walletconnect://…) | A connection string generated by app5 containing a secret key for app4. |
| Secret (Private Key) | A randomly generated key in the NWC URI, used by app4 for signing and encrypting. |
| Public Key | Derived by app4 from the secret and used for secure messaging with app5. |
nostr+walletconnect://b889ff5b1513b641e2a139f661a661364979c5beee91842f8f0ef42ab558e9d4?relay=wss%3A%2F%2Frelay.damus.io&secret=71a8c14c1407c113601079c4302dab36460f0ccd0ad506f1f2dc73b5100e4f3c
nostr+walletconnect://<wallet_service_pubkey>?relay=<relay_url>&secret=<random_secret>
- The wallet service (app5) generates an NWC URI and provides it to the client (app4).
- This URI contains a randomly generated secret key (not linked to the client’s main Nostr keypair).
- The client (app4) derives its public key from this secret.
- The client (app4) signs and encrypts messages using the secret key from the NWC URI.
- It does not generate its own Nostr keypair but instead uses the provided secret.
- Requests are sent to the wallet service (app5) as Nostr events (kind 23194).
- The wallet service (app5) listens for incoming requests from the public key derived from the secret.
- It decrypts the messages, executes the requested action (e.g., sending a payment), and responds with a confirmation event (kind 23195).
✅ The client (app4) never generates its own Nostr keypair. It uses the provided secret to derive a public key.
✅ The secret in the NWC URI is not the wallet service’s (app5) private key but a randomly generated key for secure communication.
✅ The wallet service (app5) expects requests from the exact public key derived from the secret in the NWC URI.
✅ Every request must be signed with the secret, ensuring authenticity.
- Stateless & Lightweight: No persistent key storage is needed—everything is derived dynamically.
- Interoperability: Any app can integrate with an NWC-enabled wallet service (app5) using this protocol.
1️⃣ Wallet Service (app5) generates an NWC URI → Includes a secret key.
2️⃣ Client (app4) receives the NWC URI → Uses the secret as a private key and derives a public key.
3️⃣ Client (app4) signs and encrypts requests using the secret key.
4️⃣ Wallet Service (app5) processes the request from the derived public key and executes the action.
5️⃣ Wallet Service (app5) responds with a confirmation event.
🔹 NWC ensures seamless, secure Lightning transactions using Nostr's event system.
🔹 It removes the need for direct key exchanges, reducing exposure to security risks.
🔹 App4 never generates new keys—it strictly follows the key derivation from the NWC URI.
- This guide should provide a foundational understanding of NIP-47! 🚀
- For technical docs visit the official repo NIP-47