Nostr Wallet Connect (NWC) explained

Before Nostr Wallet Connect, every Nostr client had to build its own wallet integration, or ship without zap functionality entirely. This produced two bad outcomes: clients that shipped zaps were forced to run a wallet, and clients that did not want to run a wallet could not support zaps.

NWC fixed this by separating the wallet from the client. The wallet is its own app; the client sends spend requests over Nostr itself; everybody wins.

If you use zaps on any non-built-in-wallet client, you are using NWC whether you think about it or not. This guide makes the mechanism explicit so you understand what the connection string does, what its limits are, and how to revoke it.

TL;DR. NWC is a protocol (NIP-47) for a Nostr client to ask a Lightning wallet to pay invoices. The pairing is a string that looks like nostr+walletconnect://.... The string grants spend permission up to a configurable budget. Any wallet can speak NWC to any NWC-aware client, so the pairing works across the whole ecosystem.

When you are ready, grab your @nostr.blog address →

The problem before NWC

Pre-NWC, a Nostr client that wanted to support zaps had three bad options.

Option 1: Bake a wallet into the client. Manage Lightning channels, handle custody, be a wallet company. Most clients could not afford the engineering.

Option 2: Ask the user for their nsec and their wallet credentials. Sign events client-side and send invoice-pay requests to the wallet API directly. This meant the client saw the wallet's API key, which is a security nightmare.

Option 3: Do not support zaps. Some clients took this path, which made them less useful.

NWC decouples the wallet from the client by using Nostr itself as the signaling channel. The client never sees wallet credentials. The wallet never has to know anything Nostr-specific except how to receive requests.

How the protocol works

NWC is defined in NIP-47. The flow:

1. Wallet generates a connection string. Contains a Nostr relay URL, a pubkey the wallet listens on, and a shared secret for encryption.
2. User pastes the string into the client. Or scans a QR code. Either way, the client now knows where to send requests.
3. Client sends encrypted spend requests over Nostr. "Pay this invoice for 1000 sats" goes in an encrypted event to the wallet's listening pubkey at the specified relay.
4. Wallet receives the request and pays. If the amount is within the connection's budget, the wallet pays the invoice immediately.
5. Wallet replies with the result. Encrypted Nostr event back to the client: payment succeeded or failed, here is the proof.

The whole thing happens in under a second. The client never handles Lightning directly; it just talks to Nostr. The wallet never has to understand Nostr social features; it just listens for spend requests.

What the connection string contains

A typical NWC string:

nostr+walletconnect://abc123def456...?relay=wss://relay.example.com&secret=xyz789...

Three parts.

A pubkey. The wallet's listening identity on Nostr. The client sends requests to this pubkey.

A relay. Where the wallet is listening. The client and the wallet both connect to this relay to exchange messages.

A secret. Used to encrypt messages between the client and the wallet, so the relay sees only ciphertext.

Together, these three values give the client permission to send spend commands to the wallet. The relay is the mailbox; the pubkey is the address; the secret is the lock.

Budget and permissions

Every NWC connection has limits set by the wallet when the connection was created.

• Max amount per payment. Typically 10,000 to 100,000 sats depending on what you set. Spending more requires a fresh approval.
• Max amount per day/week/month. Rolling budget that refills on a schedule.
• Expiration date. Some wallets auto-expire connections after a period; others leave them open until revoked.
• Allowed methods. Some wallets let you grant "pay invoice" only, denying "lookup balance" or "list transactions."

The budget means even if a connection string leaks, the damage is bounded. An attacker cannot drain the whole wallet; they can spend up to the budget, at which point the wallet refuses further requests until you top up the limit or generate a new connection.

Setting up NWC, step by step

Concrete flow for a typical user pairing a wallet with a Nostr client.

1. Open your Lightning wallet. Wallet of Satoshi, Phoenix, Alby Hub, Zeus, or any NWC-supporting wallet.
2. Find the NWC settings. Look for "Connections," "Nostr Wallet Connect," or "Apps" in the settings menu. Every wallet puts it in a slightly different place.
3. Create a new connection. Give it a name so you remember which app it is for. Set a budget.
4. Copy the generated NWC string. Or get a QR code.
5. Open your Nostr client. Go to settings, find "Lightning wallet" or "Zap settings."
6. Paste the NWC string or scan the QR. The client tests the connection.
7. Success. Zap buttons light up; your next zap goes through the paired wallet.

If the client shows "connection failed" after pairing, the most common cause is a relay mismatch (the relay in the NWC string is one the client cannot reach) or a firewall blocking WebSocket connections.

Why this beats a built-in wallet

Three real advantages to NWC over baked-in wallets.

Portability. You can switch Nostr clients without switching wallets. Your balance, history, and channels stay put; the new client just pairs with the same wallet via a new NWC connection.

Specialization. Wallet developers focus on Lightning infrastructure; client developers focus on social UX. Each side gets better at its own domain, and the interoperability works across combinations.

Security boundary. The client never has wallet credentials. A buggy client can at worst send wrong invoices; it cannot drain the wallet or export the seed phrase.

The only case where built-in is clearly better is for users who want maximum friction-free onboarding. A client with a bundled wallet gets the user zapping one step faster than pairing an external wallet. This is why the nostr.blog signup includes a wallet by default, and users can still pair external wallets via NWC later if they prefer.

Revoking an NWC connection

If you lose a device, stop using a client, or want to rotate credentials, revoke the connection from the wallet side.

1. Open the wallet.
2. Find the connection in the settings list.
3. Tap revoke or delete.
4. The connection string no longer works; any client holding it gets "unauthorized" on the next request.

This is instant. Unlike API keys you might leak into a GitHub repo, NWC connections can be killed in seconds and no lingering sessions persist. This is a meaningful safety property.

Common NWC issues

"Connection timed out." The relay in the NWC string is unreachable from your network, or the wallet is offline. Check that the wallet app is open and connected; some wallets require the app to be active to respond.

"Payment failed" despite a valid invoice. The wallet's channels may lack the liquidity to route the payment. This is a Lightning-layer issue, not NWC-specific. Try a different amount or a different time.

"Permission denied." The connection's budget is exhausted, the connection has expired, or the request type is not in the allowed methods. Check the wallet's connection settings.

"Client cannot detect wallet." After pasting, the client hangs. Close and reopen the client; some clients cache the connection state and only recheck on launch.

Where NWC is going

NIP-47 is not final. Active work in 2026 covers:

• Richer permissions. More granular than "can spend up to X per period," with per-recipient or per-amount rules.
• Multi-wallet routing. A client paired with multiple wallets chooses the best one for each payment based on balance, fee, or route.
• Better error reporting. Standardized error codes so clients can show useful messages when payments fail.
• Offline wallet support. Current NWC assumes both sides are online; drafts allow queued requests that settle when the wallet reconnects.

The protocol is stable enough for daily use in 2026 and will keep evolving. Pairing a wallet today is a one-minute operation; nothing about the current design will break later.