nostr is a protocol

01

keys and accounts

In Nostr you don't need to register for an account by giving personal data. There is no email, no phone, no password.

Like in Bitcoin, you just need a set of keys. Two keys, to be precise:

You should save your private key. It is the only way to recover and re-login to your account in the future.

getting a set of keys

The easy way is to use nstart.me. It generates a keypair, walks you through a backup, lets you pick a name and good relays, and then sends you off to a client of your choice.

Most clients can also generate keys for you on first launch. Either way works, but if it's your first time, the Nstart flow above is friendlier.

signers: don't paste your nsec into random apps

Your nsec is the keys to the house. Pasting it into a trusted app that keeps it only on your device is fine (plenty of good clients work this way), but once you paste it somewhere you don't know well, it's no longer a secret. The safer default is to let a signer hold the key and sign events on behalf of the apps you use.

• Amber on Android.
• nsec.app in the browser, no install.
• nos2x or Alby as browser extensions.

a readable handle (NIP-05)

An npub1… is not exactly memorable. NIP-05 lets you claim a nicer handle like alice@example.com by hosting a small JSON file on a domain you control. It's not a central registry, just DNS.

profile info

You can attach metadata to your keys: a display name, a bio, an avatar, a banner. Most clients let you edit all of this. Under the hood it's just another signed event.

02

events

The only object type that exists in Nostr is the event. Events are small, signed, text-only structures. Everything your client sends to a relay is an event: a post, a reply, a like, a profile update, a zap, a direct message, a long-form article.

Here's what an event looks like:

// kind 1, a plain-text note
{
  "id":         "c011…4c43",
  "pubkey":     "dec1…4fb3",
  "created_at": 1761522400,
  "kind":       1,
  "tags":       [],
  "content":    "good morning!",
  "sig":        "e1dc…5f1"
}

Breaking it down:

• The content and created_at fields speak for themselves.
• The id is a unique identifier for this event. It's how the network refers to it.
• The pubkey is the public key (the user) that created the event.
• The sig is a cryptographic proof that whoever published the event holds the private key that matches the pubkey.
• The tags field can contain any tags you want: references to other events, other users, URLs, hashtags. When you reply to a note, for example, its id ends up in a tag here.

kinds

The event kind is one of the most interesting parts of Nostr. It's a number that says what type of event this is. The interesting bit: kinds aren't limited, so people can invent new ones for whatever they want to build.

Some common kinds:

• 0 profile info (name, bio, picture)
• 1 a short text note (the "tweet")
• 3 your contact list (who you follow)
• 6 a repost
• 7 a reaction (like, emoji)
• 1059 a private message (NIP-17)
• 9735 a zap receipt (NIP-57)
• 10002 your relay list (NIP-65)
• 30023 a long-form article (NIP-23)
• 30311 a live stream

The full list lives in the NIPs repo. Anyone can propose a new one.

03

relays

Relays are an essential piece of Nostr. They receive events from clients, store them, and pass them along to anyone subscribed. That's all they do.

Relays don't talk to each other. Only the relays you are connected to will receive and store your events. This is important, so worth saying twice: relays do not communicate between themselves.

You want to be connected to several relays. Clients let you pick as many as you like, and you can choose whether to read, write, or both from each one. For example, you might connect to a relay just to read content, but not publish there.

If I'm only connected to relay A and you are only on relay B, we won't see each other's posts even though we are both on Nostr. To fix it, one of us has to connect to a relay the other one uses.

It may sound confusing at first, but it's actually a very useful property. You can run a relay that you never share with anyone and publish all your events there as a personal backup. You can connect to a relay dedicated to football, and if you don't care about football, just don't add it.

the outbox model

To make this less of a guessing game, there's NIP-65. You publish a small event that says "these are the relays I write to, these are the ones I read from". Modern clients (Damus, Amethyst, Primal, Coracle and others) read this list and figure out where to look automatically.

If someone can't see your posts, it's almost always because you don't share a relay. Publish to a couple of popular ones and your own, and this stops being a problem.

fighting censorship

Relays are cheap and easy to run. A relay can run on a small VPS, or even on a low-end phone. Because relays don't talk to each other, shutting one down doesn't affect the others. If someone tries to take a relay offline, a new one can pop up somewhere else in minutes.

There are hundreds of relays spread around the world, and the number keeps growing.

→ guide: set up your own relay

04

zaps

One of the coolest things Nostr has is native Bitcoin payments. A zap is a Lightning tip attached to a post or profile. You tap a little lightning bolt, sats move, and a public receipt shows up on the post.

Zaps are not just tips. They're a stronger signal than a "like": a like costs nothing, a zap costs something. Popular posts often show their zap totals right next to the reply and repost counts.

one-tap zaps

To make zaps feel as easy as hitting "like", clients use Nostr Wallet Connect (NWC). You paste a nostr+walletconnect:// link from your wallet into the client once, and from then on zaps happen in a single tap. No QR codes, no invoice copying.

Wallets that support NWC include Alby Hub, Primal Wallet, Coinos, Zeus, and Phoenix.

To receive zaps you need a Lightning address, like you@getalby.com. Most modern wallets give you one automatically.

05

private messages

You can send private end-to-end encrypted messages to other users. The modern way to do this is NIP-17, also called gift-wrapped messages. Each message is encrypted, then wrapped in an outer event so that relays can't even tell who is talking to whom, or when.

Clients that support modern DMs include Damus, Amethyst, Primal, 0xchat and Coracle.

For group chat, there's NIP-29, which puts groups inside a relay (a bit like Discord channels). See Flotilla for that.

06

what you can do with it

As mentioned earlier, Nostr is a very flexible protocol for sharing data. People can build whatever they want on top of it. It's still young, but here's some of what already works:

A more complete list lives at nostrapps.com and nostr.net.

07

build on nostr

There's a lot you can still build on Nostr. A client is anything that opens a WebSocket and subscribes. A relay is anything that accepts signed JSON over WebSocket. The bar is low.

Some resources to get you started: