CraysBitcoinLink
BitcoinLink turns a limited wallet connection into claimable Lightning links. It is simple on the surface, but the security model is all about NWC permissions, encrypted Nostr events, relay availability and the fact that the link itself carries the key to claim.
A payment link with a wallet behind it
BitcoinLink looks almost too simple when you first open it. The live page asks for a number of links, a sats amount per link and a wallet path such as Alby or Mutiny. The promise is familiar: create single-use links that someone else can redeem through Lightning. The interesting part is what the app avoids. It does not ask the sender to deposit into a BitcoinLink account, and the repository describes no server database that owns a balance while links wait to be claimed.
The project solves that problem by making Nostr the storage and coordination layer and Nostr Wallet Connect the spending path. The sender gives the app a limited wallet connection. BitcoinLink creates encrypted Nostr events that contain the NWC URL and amount for each link. The receiver gets a claim URL that can find and decrypt one of those events. When the receiver supplies a payment destination, the app asks the sender's wallet connection to pay.
That is why BitcoinLink belongs with finance and payment tools rather than ordinary social clients. The Nostr part is essential, but the reader's main question is not how to post or follow. The question is whether a link can safely carry spend authority from a sender to a receiver without a hosted balance, and what assumptions must be true for that to work.
What the sender is really authorizing
The sender side starts with a budgeted wallet relationship. In the Alby flow, the code uses the Alby SDK to create a new NWC client secret and request a connection that can pay invoices. The requested maximum amount is based on the number of links multiplied by the sats per link, the permission is not editable in the flow, and the renewal is set to never. That is the right kind of shape for a payment-link app: the connection should be narrow, temporary in spirit and sized to the links being created.
The Mutiny path is different. BitcoinLink builds a nostr+walletauth URI for Nostr Wallet Auth, points it at the Mutiny relay, requests pay_invoice and waits for a response event. When that response arrives, the app decrypts it, extracts the wallet service details and builds an NWC URL. The end result is similar from the claimer's perspective, but the setup path shows that BitcoinLink is not hard-coded to one wallet brand. It is trying to use NWC as a wallet-control interface.
The important reader point is that a BitcoinLink is not funded by BitcoinLink itself. It is funded by the sender's wallet authorization. If the NWC relationship allows pay_invoice up to a certain budget, the link can spend within that limit. If the budget is exhausted, revoked, misconfigured or unreachable, the link cannot pay. That makes the wallet permission the real money boundary.
The link is the claim key
The claim URL is not just a pretty pointer. It carries the material needed to claim. BitcoinLink encodes a JSON object into a URL-safe base64 slug. That object includes the encrypted event ID, the receiver private key, the relay list and an amount hint. The receiver private key is used to decrypt the gift-wrapped event that contains the real payment payload.
That design keeps the pending link out of a central BitcoinLink account, but it also gives the URL bearer power. If someone forwards the link to the wrong chat, stores it in a shared note, posts it publicly or lets a browser extension leak it, another person can open the claim page and try to redeem. The project can check whether a deletion event says the link was already claimed, but possession of an unclaimed link is still the practical claim right.
Readers should treat BitcoinLink URLs like cash vouchers. They are convenient because there is no account recovery process, no login dance for the receiver and no custodial balance to withdraw from BitcoinLink. They are risky for the same reason. The link must stay private until the intended receiver claims it.
What lives on relays
BitcoinLink uses Nostr relays as the place where pending encrypted links live. The repository defines a default relay set that includes relay.damus.io, relay.nostr.band, nos.lol and nostr.mutinywallet.com. A generated link can also carry relay configuration, so the claim page knows where to look for the encrypted event and the later claimed marker.
The event containing the payment payload is a gift-wrapped event. The content is encrypted; the tests explicitly check that plaintext strings such as the NWC URL and the BitcoinLink marker do not appear in the published event content. That is the right privacy direction. Relays help distribute and retain the pending link event, but they should not learn the NWC URL simply by storing the event.
Relay dependence still matters. If the event is not published, the receiver cannot claim. If relays are down, slow or filtering, the claim page may not find the gift wrap. If a deletion event is missed by a relay, another client might not see that the link was already claimed. Nostr gives BitcoinLink a portable storage layer, not a guarantee that every relay has the same view at the same time.
Why Gift Wrap matters
BitcoinLink's use of NIP-17 style gift wrap is one of the strongest parts of the design. The app creates a receiver keypair for each link, encrypts a direct-message payload to the receiver public key and wraps that message in a kind 1059 event. The receiver private key is then placed in the claim URL. That means the pending payment instruction is public enough to be stored on relays but private enough that relays and ordinary observers cannot read it.
The payload inside the gift wrap is deliberately small. It records that the event is a BitcoinLink payload, carries the NWC URL and sets the amount. The decrypt path rejects the wrong event kind, invalid keys, malformed JSON, missing NWC URLs and invalid amounts. The tests cover wrong keys, truncated keys, zero amounts, very large amounts, unique event IDs, unique receiver private keys and concurrent link creation.
For a reader, gift wrap changes the trust model. You do not have to trust a BitcoinLink database to remember the pending link. You do have to trust the code that creates and decrypts the event, the browser environment that handles the NWC string and claim key, and the relay path that stores the encrypted event until it is claimed.
How a claim actually pays
On the receiver side, the claim page decodes the slug, computes the receiver public key from the private key in the URL and checks whether a NIP-09 deletion event already references the gift-wrap event. If the link appears unclaimed, the page fetches the kind 1059 event by ID, decrypts it with the receiver key and reads the NWC URL and amount from the decrypted payload.
The receiver can enter a BOLT11 invoice, an LNURL pay endpoint or a Lightning Address. For Lightning Address input, the app resolves the well-known lnurlp endpoint, checks the payRequest response, sends the amount in millisatoshis to the callback and receives an invoice. For LNURL input, it follows the pay request flow. For BOLT11 input, it validates that the invoice shape is acceptable before trying to pay.
Once the invoice is ready, BitcoinLink creates an NWC client from the encrypted payload's NWC URL, initializes the connection, calls pay_invoice and expects a preimage. The app disconnects afterward in a finally path. That payment is the moment the sender's wallet budget becomes real money movement. Everything before that is setup, storage and validation.
Deletion events are useful, not magic
After a successful payment, BitcoinLink publishes a NIP-09 deletion event from the receiver key and tags the original gift-wrap event ID. The claim page treats that deletion event as the claimed marker. On later visits, the page can find the marker and show that the link has already been claimed.
That marker is useful because it uses the same Nostr storage layer as the pending link. It also has limits. A deletion request on Nostr is not an atomic database lock. Relays can miss it, reject it, prune it or disagree about whether it exists. The code also treats deletion publication failure after a successful payment as non-fatal, because the payment already happened. That is the right user experience after money moves, but it means the claimed marker is not the same thing as the payment itself.
The safest way to use BitcoinLink is to make the wallet budget match the links you intended to create. If the sender creates ten links of 100 sats each, the NWC budget should not quietly allow far more than 1,000 sats. A deletion marker helps the interface. A tight NWC budget limits damage if a relay view, browser state or claim retry behaves badly.
Alby and Mutiny take different paths
The Alby path is the most straightforward for many readers. BitcoinLink asks Alby to create a scoped NWC relationship and then generates encrypted links from the resulting connection string. Alby is doing the wallet-service work; BitcoinLink is the link generator and claim interface. The sender should still inspect the wallet-side permission, amount and expiration before creating links.
The Mutiny path is more protocol-shaped. BitcoinLink constructs a Nostr Wallet Auth URI with requested commands, budget and relay details, opens that flow and listens for a response event. That response becomes the NWC relationship used by the generated links. The code makes Mutiny support feel native without making the whole app custodial.
Both paths illustrate the same larger idea. NWC lets a web app ask a wallet to perform a narrow payment job without holding the funds. That can be powerful for vouchers, rewards, giveaways, refunds, onboarding links and small social payments. It also means the wallet provider's reliability, permissions, security prompts and revocation controls are part of the product.
Lightning Address, LNURL and BOLT11 receiving
BitcoinLink is friendly to receivers because it does not require them to understand NWC. The receiver can paste a Lightning Address, an LNURL pay value or a BOLT11 invoice. The app then turns that input into the invoice the sender's wallet has to pay. That separation is important. The sender uses NWC to authorize payment, while the receiver uses the Lightning address or invoice format they already have.
Lightning Address support follows the familiar user@domain pattern. The app fetches the LNURL pay metadata from the domain, checks the amount against minSendable and maxSendable and calls the callback with the link amount in millisatoshis. For wallets and services that expose Lightning Address well, this makes a claim feel almost like entering an email address.
The receiver still has responsibility. A wrong Lightning Address sends money to the wrong destination. A malicious LNURL endpoint can return unexpected metadata or fail at the callback. A BOLT11 invoice can expire. BitcoinLink can validate formats and handle errors, but it cannot prove that the receiver intended every destination they paste.
Where the amount is trusted
The claim URL includes an amount field, but the decrypted gift-wrap payload is the stronger source. The tests cover cases where the URL amount is tampered with and the decrypted payload preserves the real amount. That is a useful detail. The link can show an initial amount quickly, but the payment logic should rely on what was encrypted when the link was created.
Amount handling is also where budgets and invoices meet. The sender chooses a sats amount per link. The wallet connection is requested with a total budget. The receiver's Lightning Address or LNURL endpoint must accept the amount in millisatoshis. The NWC wallet must then pay an invoice for that amount. Several systems have to agree before a link settles.
If a claim fails, the reason may be outside BitcoinLink. The wallet budget may be insufficient. The Lightning Address may have min or max limits. The invoice may be invalid. The wallet service may be offline. A relay may not return the gift wrap. The practical debugging path is to check the link event, the receiver destination and the sender wallet permission separately.
The security model in plain language
BitcoinLink's security model is easiest to state plainly. The sender should assume the NWC URL can spend within its allowed permission and budget. The receiver should assume the claim URL is a secret. Relays should be treated as public storage for encrypted events and claimed markers, not as trusted payment servers. The browser should be treated as the place where sensitive material is briefly assembled.
That model is reasonable for small links, demos, rewards and social payments. It is not the same as a regulated voucher system, a bank transfer, a withdrawal queue or an escrow contract. BitcoinLink does not make a third party guarantee a claim. It gives the sender and receiver a Nostr-native way to coordinate a limited wallet payment.
The biggest practical risks are over-permissioned NWC connections, leaked claim URLs, stale relay state and user confusion after partial success. A good first test is tiny: create one link for a few sats, claim it to your own Lightning Address, reload the claim page, verify the claimed state, inspect the source wallet history and revoke the wallet connection.
What the tests say about edge cases
The repository has a strong test surface for a small app. The test files cover gift-wrap creation, link generation, claim flow, NWC payment calls, BOLT11 helpers and many failure paths. The tests check wrong keys, truncated keys, special characters, long NWC URLs, amount boundaries, tampered URL data, relay configuration, concurrent link creation and multiple links using the same NWC URL.
The NWC payment tests mock the wallet client and check success with a preimage, disconnect behavior, missing preimage errors, initialization failure, insufficient budget, payment timeout and disconnect errors. That is exactly where a payment-link app should be defensive. A pretty link generator is easy. A link generator that admits wallet and relay failures is more useful.
Tests are not the same as a security audit, but they tell you what the maintainer knows can go wrong. BitcoinLink's tests show awareness of the right categories: encryption, secret leakage, amount tampering, concurrency, wallet failure and relay configuration. If you plan to use it beyond casual amounts, read those tests before trusting the interface.
What to verify before using it
Start with the official site and repository. The live app is at bitcoinlink.app and the source is in Austin Kelsay's GitHub repository. Check that the app you are using points to the expected domain, then read the README and the source paths for link generation, gift wrap, claim handling and NWC payments. A payment-link app should not be evaluated from screenshots alone.
Then check the wallet connection. Which wallet created it? Which commands are allowed? What is the budget? Can you revoke it? Does the wallet show pending permissions clearly? If the NWC connection can pay more than the links require, shrink it before creating links. If the wallet does not show you what was authorized, use a different wallet path for testing.
Finally, decide the right use case. BitcoinLink is well suited for small rewards, conference handouts, private gifts, onboarding experiments and Nostr-native payment demos. It is less suited for large transfers, public giveaways with no abuse limits or situations where the receiver must have formal redemption guarantees. The product is clever because it keeps custody out of the app. That same design asks the sender and receiver to handle links, wallet permissions and relay assumptions carefully.
Sources worth opening
Open the live app, the repository, the README, the claim flow, gift-wrap code, NWC client, tests and the Nostr and LNURL specifications together. BitcoinLink is easiest to understand when the pleasant link surface is read beside the exact event and wallet calls.
- BitcoinLink live app
- BitcoinLink GitHub repository
- BitcoinLink README
- BitcoinLink main page
- BitcoinLink claim page
- BitcoinLink Alby NWC hook
- BitcoinLink Mutiny modal
- BitcoinLink link generator
- BitcoinLink link encoder
- BitcoinLink gift-wrap code
- BitcoinLink Nostr client
- BitcoinLink NWC client
- BitcoinLink relay defaults
- BitcoinLink claim-flow tests
- BitcoinLink gift-wrap tests
- BitcoinLink link-generator tests
- BitcoinLink NWC payment tests
- BitcoinLink BOLT11 tests
- BitcoinLink package manifest
- BitcoinLink project overview notes
- BitcoinLink security notes
- BitcoinLink sender-flow notes
- BitcoinLink receiver-flow notes
- snstr repository
- NIP-09: Event deletion
- NIP-17: Private direct messages and gift wrap
- NIP-44: Versioned encryption
- NIP-47: Nostr Wallet Connect
- NWC introduction
- NWC reference API overview
- Alby JavaScript SDK
- WebLN documentation
- LNURL LUD-06 payRequest
- LNURL LUD-16 Lightning Address
- BOLT11 invoice specification
- Nostr protocol NIPs repository
- Vercel deployment platform
