Nostr Wallet Connect

Anna is listening to a podcast and wants to send its creator a small amount over the Lightning Network. With NWC, the player can ask her wallet to pay directly. The wallet service checks the connection’s permissions before carrying out an allowed request. NWC does not determine who holds the bitcoin keys: the other end may be her own node or a service holding funds for her. The same “Connect wallet” button can therefore imply very different control over money. Depending on the rights granted, the app may also act without a fresh confirmation for each individual payment. [1] [2]

The wallet usually supplies a QR code or text connection string, technically a URI. It contains the wallet service’s public key, a relay address and secret, the private key for this client connection. This is not the wallet’s seed, its initial private value, or its Seed Phrase, the recovery words. It is still not a harmless public link: someone with a usable copy can exercise the same permissions. The potential damage depends on the functions and limits allowed. Separate connections for different apps make access distinguishable and individually revocable, while also reducing links between those connections. [1]

An app may need only to read a balance, or it may also send money. These are different permissions. The public info event advertises what the service supports; get_info returns methods available to a particular connection. A method is a named command: pay_invoice asks for payment, make_invoice creates a payment request, lookup_invoice checks its state, and get_balance reads the balance. get_info itself is also part of the core set. History, keysend—payment without a pre-created invoice—and notifications are optional extensions. A server supporting a command does not mean every connected app is authorized to invoke it. [1] [3] [5]

Anna may want to give the player only a limited budget. If the service offers spending, method or expiry limits, the service itself must enforce them. A number displayed only in the player does not protect against an app sending a different request. Check whether the allowance is one-off or replenishes, and how fees count toward it. When Anna stops using the app, she should revoke its permission at the wallet service. Merely deleting the app or removing its local connection is not proof that access has been revoked. Revocation blocks future requests; it does not reverse a completed payment. [1]

A Lightning invoice is a payment request, for example in BOLT11 format, not evidence that someone paid. NIP-47 expresses amounts and fees in msat, thousandths of a satoshi: 1000 msat = 1 sat. Confusing units changes the amount a thousandfold. make_invoice only creates a request. Successful pay_invoice returns a preimage. A hash, a short checking value, is calculated from it. This must match the payment hash in the invoice; the returned preimage thus serves as evidence of payment completion. An error response uses error. lookup_invoice can retrieve the state. The app must handle the actual result, not display success merely because it sent a message. [1]

Anna taps Pay, but the app receives no reply. A timeout—the end of the waiting period—does not establish what happened to the money. NWC uses ephemeral events for requests and responses; a disconnected relay or unavailable service can cause a message to be lost. But the missing message may be only the response to an already completed payment. First check the state using lookup_invoice or the wallet itself. Silence is not confirmation of failure. A new request cannot be assumed to be a safely repeatable version of the original action; establish its outcome first. [1]

The app and wallet exchange encrypted messages. Current negotiation prefers nip44_v2, while deprecated nip04 remains for compatibility; a missing encryption tag means the older mode. NIP-44 does not provide forward secrecy, protection for earlier communication if a long-term key is compromised later. A relay can also see event types, tags, public connection keys and timing. NWC should therefore not use the main identity key with which someone publishes on Nostr. Separate keys help reduce links between payments and a public profile; they do not guarantee complete anonymity. [1] [4]

Ordinary users need not memorize message numbers, but they matter when building an integration. Info uses kind 13194, requests 23194, and responses 23195. kind identifies the event type. The p tag identifies the counterparty, while the response’s e tag refers to the original request. The client verifies the signature, expected wallet service key, that request association and result_type, the command to which the result belongs. It must not treat just any message from a relay as confirmation. Otherwise, a response from someone else or to another action might be mistaken for this payment’s result. [1]