# nostr-protocol/nips: The Specification Repository Behind Nostr Clients and Relays > NIPs are the numbered documents that describe what Nostr relays and clients may implement, and this repository is where they live. Here is how the repo is organized, what it refuses to be, and where it falls short for an implementer. **nostr-protocol/nips** — Nostr Implementation Possibilities - Repository: https://github.com/nostr-protocol/nips - Stars: 3,107 · Forks: 796 - Language: Unknown - License: not declared - Published: 2026-09-24 · Updated: 2026-09-24 · Language: en - Canonical page: https://hysenlabs.com/projects/nostr-protocol-nips ## What NIPs Are, and the Problem the Repository Solves NIP stands for Nostr Implementation Possibilities. The README states plainly what they are for: to document what may be implemented by Nostr-compatible relay and client software. That phrasing is doing real work. A NIP is not a requirement, a certification, or a version of a product. It is a written description of a behavior that some software may choose to support. The problem this solves is coordination without a governing body. If two client authors want their apps to exchange the same kind of event, they need a shared description of that event: which kind number it uses, which tags it carries, how it is signed. NIPs are that shared description, and each one lives in its own numbered file in the repository root, from 01.md through the alphanumeric ones such as 5A.md and A0.md. The audience is narrow and specific: people writing relay software and people writing clients. If you are evaluating Nostr as a user, this repository is not the product. It is the paper trail behind the product. The README's own framing sets the tone for everything else: NIPs listed here are not a protocol checklist. ## One File per NIP, and a README That Is the Index The architecture is flat and deliberately boring, which is the right call for a specification set. The repository root holds one Markdown file per NIP. The README is the index: a list of links to those files, each with a short title and, for deprecated entries, a strikethrough and a reason. The README also carries tables that map identifiers to documents. There is an Event Kinds table listing kind numbers such as `0` for User Metadata, `1` for Short Text Note, `3` for Follows, `5` for Event Deletion Request, and `7` for Reaction, each pointing at the NIP that defines it. There are also Message Types tables split into Client to Relay and Relay to Client. The README notes the event kinds table is not exhaustive and points at a separate machine-readable registry of all known event kinds for that purpose. That separation matters. The prose documents are the normative text; the tables in the README are a convenience index. If you are generating code from the tables, you are generating from a summary, not from the specification. ## No Package to Install: Reading a NIP Locally There is no package to install. The README describes no build step, no CLI, and no published artifact. The unit of consumption is a Markdown file, and the repository is the delivery mechanism. The README does not give a clone command, so the only step it implies is obtaining the repository and opening the numbered file you need. The repository root holds files named 01.md, 10.md, 17.md, 44.md and 59.md, among others, and the README links each of them by name. From there, open the file for the NIP you are implementing. The README links NIP-01 first in its list, titled Basic protocol flow description, followed by NIP-02, Follow List, and NIP-05, Mapping Nostr keys to DNS-based internet identifiers. What you find in those files is prose and examples describing events and messages, not executable code. This is the entire workflow: get the repository, open the numbered file, read it. ## The Unrecommended List Is the Most Useful Part The README does something many specification repositories avoid: it marks NIPs as unrecommended in the index itself, with a reason. NIP-04, Encrypted Direct Message, is struck through as deprecated in favor of NIP-17. NIP-08, Handling Mentions, is deprecated in favor of NIP-27. NIP-28, Public Chat, points readers to NIP-29 instead. NIP-96, HTTP File Storage Integration, is marked replaced by Blossom. NIP-90, Data Vending Machines, is struck through with the note that it got totally out of control and that use-case-specific microstandards are preferred. For an implementer this is the highest-value content in the repository. It tells you which numbers to avoid before you write code, and it tells you where the replacement lives. A client author who reads only the first NIP they find on a topic may implement a deprecated design. The honesty is also a limitation. A struck-through NIP is still a file in the repository, still linked, still readable, and still implemented by software in the wild. The README's warning about NIPs existing outside this repository and already being deployed applies in reverse here too: deprecated does not mean absent. ## No Checklist, No Compliance, and Other Real Constraints The README is explicit that nothing forces any software to implement any NIP and that each app picks the subset relevant to its use case, with the instruction not to implement something just because it exists in the repo. That is a design philosophy, and it has a direct cost for anyone hoping for interoperability guarantees. Two relays can both claim Nostr support and share almost no optional features. A client can implement NIP-01 and NIP-10 and nothing else. There is no conformance test in this repository, no reference implementation, and no version number that tells you what a given piece of software supports. The event kinds table in the README is described as not exhaustive, so even the index of numbers is a starting point rather than an authority. The repository is also documentation only. It contains no code that runs, so it cannot fail at runtime, and it cannot fix a bug in your implementation. If you need a library, a validator, or a test harness, this is the wrong repository. The README does not document a rollback process for a NIP that turns out to be a bad idea; the mechanism visible in the index is marking the entry unrecommended and pointing at a successor, which leaves the old text in place. ## How This Compares to a Conventional Standards Body The obvious alternative is a formal standards organization, where a specification is ratified, versioned, and paired with a compliance program. That model produces a single answer to what a compliant implementation looks like. This repository produces the opposite: a set of documents that software may implement in part, with the README stating that other standards and NIPs may exist outside the repository and may already be deployed. A closer comparison is a language's request-for-comments series, where numbered documents accumulate and some are superseded rather than deleted. The difference here is the acceptance criteria section in the README, which describes how a NIP gets into the repository in the first place, and the section asking whether the repository is a centralizing factor, which acknowledges the tension of hosting shared specifications in one place. Neither model is strictly better. A ratified standard gives you a target to test against. This repository gives you a description and leaves the coordination to the implementers, which is faster to change and weaker as a guarantee. ## Maintenance, Licence, and What to Verify Before You Build The repository is not archived, and the last push was on 2026-09-23, so the text is current as of that date. There are no retrieved releases, which fits a repository whose output is documents rather than artifacts. Upgrading means pulling the latest commit and re-reading the NIPs you depend on, because a NIP can be edited in place, marked unrecommended, or superseded by a new number with no version bump to alert you. The README has a License section, but the licence identifier is not stated in the description available here, so check that section in the repository before you reuse the text. Practically, the licence matters less for reading a specification than for republishing or vendoring it into your own documentation. What to verify first is the status of the specific NIP you plan to implement. Open its file in the repository root, confirm the README does not strike it through, and check whether the README points to a successor. NIP-01 is the entry point the README itself links first, and it is not marked unrecommended. ## Conclusion Adopt this repository as a reference if you are building a Nostr relay or client and need the current text of a NIP, and start from NIP-01 because the README links it as the basic protocol flow description. Do not treat it as a dependency, a conformance suite, or a compatibility guarantee: the README states that nothing forces any software to implement any NIP, and several NIPs are marked unrecommended in the list itself. Before you build against a specific number, open that file and check whether it is struck through, then verify what the clients and relays you care about actually deploy, since the README notes other standards and NIPs may exist outside this repository and may already be deployed in the wild. ## FAQ ### What does NIP stand for in nostr-protocol/nips? NIP stands for Nostr Implementation Possibilities. The README describes them as documents of what may be implemented by Nostr-compatible relay and client software. ### Do I have to implement every NIP in the repository? No. The README states that nothing forces any software to implement any NIP, that each app picks the subset relevant to its use case, and that you should not implement something just because it exists in the repo. ### Which NIP should I start with in nostr-protocol/nips? The README lists NIP-01 first, titled Basic protocol flow description, and it is not marked unrecommended. It is the natural entry point before the numbered NIPs that build on it. ### Why are some NIPs struck through in the README? The README marks certain NIPs as unrecommended with a reason, such as NIP-04 being deprecated in favor of NIP-17 or NIP-96 being replaced by Blossom. The files remain in the repository, so the strikethrough is a signal in the index rather than a deletion. ### Can you explain the Nostr protocol and how it works? This repository documents the pieces rather than the whole: the README links NIP-01 as the basic protocol flow description and provides tables of event kinds and message types split into client-to-relay and relay-to-client. The README also notes that other standards and NIPs may exist outside this repository and may already be deployed. ## Sources - [Issues](https://github.com/nostr-protocol/nips/issues) - [nostr-protocol/nips on GitHub](https://github.com/nostr-protocol/nips) - [README](https://github.com/nostr-protocol/nips/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nostr-protocol-nips