NIP-21: nostr URI scheme
A portable network needs links that leave the website
NIP-21 is small because the idea is simple: a Nostr identifier needs to be linkable. A profile, event or addressable article can already be expressed as a NIP-19 string. NIP-21 turns that string into a URI that an app, browser, operating system or website can hand to the user's preferred Nostr client.
The scheme is nostr:. The payload after it is a NIP-19 identifier such as npub, nprofile, nevent or naddr. The exception is nsec, because private keys do not belong in shareable URI links.
This is the difference between an identifier and a door. Without NIP-21, a website can display an npub and hope the user copies it. With NIP-21, a page can offer a link that opens a client, you can click through from an article to an author, and a web publisher can connect an HTML page to the Nostr event that carries the same work.
nostr links and HTML relationship tags
The base rule is compact: nostr: plus a NIP-19 identifier. Examples include nostr:npub..., nostr:nprofile... and nostr:nevent.... The actual entity meaning still comes from NIP-19; NIP-21 adds the URI wrapper.
The later HTML addition is important for publishers. A page can include <link rel="alternate" href="nostr:naddr..."> to say that the same content exists as a Nostr event. A page can include rel="me" or rel="author" links to assign authorship to Nostr profiles.
That turns NIP-21 into a bridge between the web and relays. A normal HTML article can point at its Nostr version. A personal site can point at the author's Nostr identity. A client can read those links and offer better open-in-client, verification or author-context behavior.
From a URL scheme to a web-publishing bridge
Fiatjaf added NIP-21 in January 2023 as the nostr: URL scheme. In May 2023, Matt Lorentz corrected the language from URL to URI, a small wording change that matters because the scheme can identify entities beyond ordinary web URLs.
For a while the NIP stayed focused on opening identifiers. In May 2025, fiatjaf added the HTML document association work: rel="alternate" for equivalent Nostr events and rel="me" or rel="author" for profile authorship. In March 2026, mentions of old note1 codes were removed.
That history tracks Nostr's expansion. Early NIP-21 helped client handoff. Later NIP-21 helped websites disclose Nostr-native versions of their content. The same tiny scheme now lives in app deep links, profile links, article publishing and identity verification.
NIP-21 depends on clients, browsers and operating systems
Rust Nostr documents NIP-21 with to_nostr_uri and from_nostr_uri helpers. The Rust crate support table lists NIP-21 as implemented. Nostr Compass explains the scheme as a way for applications, websites and operating systems to register interest in opening Nostr identifiers. Those are three different layers of the same reality: a URI is only useful when something knows how to handle it.
On the web, NIP-21 also inherits ordinary HTML behavior. MDN's rel reference explains alternate and author link relationships in the wider web platform. NIP-21 applies those relationships to Nostr entities, which makes the addition feel less like a protocol island and more like a native web bridge.
The practical product issue is fallback. If a user's system has no Nostr URI handler, the click can fail silently. Good sites display the NIP-19 string as copyable text and offer a web-client fallback beside the nostr: link.
A deep link that fails still needs a graceful path
The first risk is uneven handler support. Mobile apps, desktop clients, browsers and web apps do not behave identically. A perfect NIP-21 link can still be a poor experience if nothing opens or if the wrong app catches it.
The second risk is accidental private-key handling. NIP-21 excludes nsec for good reason. A client or site that treats any bech32 string as linkable can create a dangerous sharing surface. Public identifiers are for links; private keys are not.
Read NIP-21 in the wild
NIP-21 gives Nostr a URI scheme. That tiny `nostr:` prefix is what lets apps, websites, QR codes and operating systems hand a Nostr pointer to a client that knows how to open it.
The risk is handler capture. If one app silently owns the scheme, a portable pointer becomes a platform funnel. Good products let you choose the client and show what kind of object the URI opens before anything sensitive happens.
What changes when you actually use it
For you, NIP-21: nostr: URI scheme is felt when an app either behaves predictably or suddenly loses context. The visible symptom may be a missing reply, a broken link, a strange reaction count, an empty result or a relay error that looks like the whole network failed. The official terms kind 30023, draft, nsec, kind:30023, rel="author" are where that visible behavior begins, so the source is not background material; it is the place where the product promise gets its limits.
What changes for builders and operators
For builders, NIP-21: nostr: URI scheme is compatibility discipline. Implement kind 30023, draft, nsec, kind:30023, rel="author" against more than one relay and more than one library, then test malformed, missing and duplicated data. Core standards fail most painfully when the happy path looks fine and the second client exposes the shortcut.
What the official file makes concrete
The official file is organized around Linking HTML pages to Nostr entities. Inspect kind 30023, draft, nsec, kind:30023, rel="author" because these are the pieces most likely to surface as product behavior. Read it beside NIP-19 before treating it as isolated.
NIP-21: nostr: URI scheme is a shared contract between independent software. The smallest field can become user-visible when two clients disagree about it.
Where it breaks
The failure mode in NIP-21: nostr: URI scheme is often indirect. Nobody complains about kind 30023, draft, nsec, kind:30023, rel="author"; they complain that the feed is wrong, the reply vanished or the relay behaved strangely. Use the official file to diagnose the hidden cause instead of patching only the visual symptom.
Where this appears outside the markdown
In the ecosystem, NIP-21: nostr: URI scheme is not something most people choose directly. It is the invisible grammar behind clients, relays, crawlers, search tools and archives. When a product team treats kind 30023, draft, nsec, kind:30023, rel="author" as implementation detail only, the mistake eventually reaches the surface as missing history, bad threading or state that cannot be reconstructed after a client switch.
The nearby-standard trap
The nearby-standard trap in NIP-21: nostr: URI scheme is assuming the base layer solves the higher-level feature. This NIP may define the common grammar, but publishing, wallets, moderation, media or groups still need their own constraints. Read NIP-19 to see where the base contract ends and the product-specific promise begins.
Language that keeps the feature honest
Good product copy for NIP-21: nostr: URI scheme does not say "the protocol handles it" and move on. It explains the visible consequence: what was sent, what was accepted, what was rejected, what is still loading and what another relay or client may show differently.
What this page does not promise
NIP-21: nostr: URI scheme does not promise a finished social product. It gives software a shared grammar. Feed design, moderation, ranking, notifications, storage duration and recovery remain separate product decisions. That distinction matters because a client can be technically compatible and still give you a weak experience if it hides relay errors, drops context or treats optional fields as if every app understood them.
Read it as a field test
Start NIP-21: nostr: URI scheme with the visible product symptom, then trace it back to kind 30023, draft, nsec, kind:30023, rel="author". That order keeps the article grounded: you see why the field exists, which relay or client behavior depends on it, and where adjacent standards change the story. A core NIP is strong only when it explains both the normal path and the awkward edge case.
Where the standard earns trust
The source links give you places to test the interpretation in public: nips.nostr.com NIP-21 mirror, NIP-19 bech32 entities, Rust Nostr Book: NIP-21, Rust Nostr ToNostrUri trait. Use those links to move from the spec to live libraries, mirrors, pull requests, guides or products.
Official NIP-21 source is the anchor for exact wording, and NIP-21 commit history shows how that wording moved over time. The strongest secondary clues here are nips.nostr.com NIP-21 mirror, NIP-19 bech32 entities, Rust Nostr Book: NIP-21. Treat this evidence chain as part of the article, not as footnotes. A NIP page becomes useful when you can move from claim to source to working behavior without guessing.
Keep the chain visible for NIP-21: nostr: URI scheme: first the human promise, then kind 30023, draft, nsec, kind:30023, rel="author", then the implementation record, then the real-world failure case. That order keeps NIP-21 useful without turning it into marketing copy or protocol trivia.
Three questions to carry forward
- Can two independent clients read the same
kind 30023,draft,nsec,kind:30023without a hidden compatibility rule? - Does the UI explain relay rejection, missing context or state replacement without blaming the whole network?
- Which adjacent standard, especially NIP-19, changes the behavior once the base event leaves the happy path?
What to verify before you rely on it
- Find
kind 30023,draft,nsec,kind:30023,rel="author"in the official file and check where the UI exposes the same concept. - Read NIP-19 as context before treating NIP-21 as a complete product story.
- Open at least one implementation, mirror, pull request or library source from the source links before trusting that the idea is mature.
- Test the unhappy path: missing relays, stale metadata, invalid signatures, blocked events, expired state, revoked permissions or unavailable media.
- Write the user-facing copy in plain language. If a standard changes authority, privacy, money, moderation or recovery, say that before the click.
Direct sources
Use these sources for NIP-21: nostr: URI scheme in that order: Official NIP-21 source for the current wording; NIP-21 commit history for the change record; nips.nostr.com NIP-21 mirror, NIP-19 bech32 entities, Rust Nostr Book: NIP-21 for public context. The article gives you the consequence in plain language, but the source trail is where exact fields, status notes, unresolved debates and implementation proof stay checkable.
