TL;DR: nostr1 is a protocol that has the power to replace twitter, Telegram, and other things.
WTF is nostr?
nostr is new and confusing but also really cool. It is the simplest open protocol that is able to create a censorship-resistant global “social” network once and for all.
- It doesn’t rely on any trusted central server, hence it is resilient.
- It is based on cryptographic keys and signatures, so it is tamperproof.
- It does not rely on P2P techniques, therefore it works.
Get Started #
While there are many clients, the following three are currently quite popular: Damus for iOS, Amethyst for Android, and Iris for Web.
Download a suitable client:
Not happy with the client choice above? Pick one of the many other clients!
Need help? Check out these guides:
- Guide for Damus (iOS)
- Guide for Amethyst (Android)
- Guide for Iris (Web)
Make sure to take care of your key management!
Learn More #
nostr’s design is very basic:
- There are two components: clients and relays. Each user runs a client. Anyone can run a relay.
- Every user is identified by a public key. Every post is signed. Every client validates these signatures.
- Clients fetch data from relays of their choice and publish data to other relays of their choice. A relay doesn’t talk to another relay, only directly to users.
To use nostr, you need a key and a client.
- Everybody runs a client. It can be a native client, a web client, etc.
- To publish something, you write a post, sign it with your key and send it to multiple relays (servers hosted by someone else, or yourself).
- To get updates from other people, you ask multiple relays if they know anything about these other people.
- Anyone can run a relay. A relay is very simple and dumb. It does nothing besides accepting posts from some people and forwarding to others.
- Relays don’t have to be trusted. Signatures are verified on the client side.
Your keys are your identity. You can think of your public key (
npub...) as your username and your private key (
nsec...) as your password.
Two quick things:
- ⚠️ DO NOT PASTE YOUR PRIVATE KEY INTO WEBSITES2 ⚠️
- Store your keys securely and do not share your private key
Keys exist in two formats,
hex and the above mentioned npub/nsec. You can use a key converter tool3 to convert between the two formats.
Use Alby or nos2x to generate your keys, or generate them using a dedicated tool like rana or nostrogen. The aforementioned extensions will store your keys safely (or at least more safely).
You can also generate your keys by other means if you know what you’re doing.4 It’s still early days, so be prepared to get rekt.
Periodically check nostr.net which keeps a curated list of clients or have a look at the client comparison table.
- Damus (iOS) - Twitter-style iOS client, also works on MacOS5
- Amethyst (Android) - Twitter-style Android client
There are more native clients in development, Nostros6 and Nozzle7 being two of them.
- iris.to - Clean interface & rich in features
- snort.social - Simple interface with automatic image-upload
- yosup.app - Mobile-friendly and twitter-like
- hamstr.to - Twitter interface, multi-account support
- primal.net - Trending posts, most zapped posts
- nostrgram.co - Focus on images and media, supports multiple layout styles
On Android, you can use the Kiwi Browser which allows you to install Alby or nos2x, which in turn allows you to use any web client. Yosup and Hamstr have good mobile experiences, for example.
There’s also Nostr Console, noscl, and nostr-commander if you’re into CLI stuff.
Relays are dumb servers that you can leave behind at any time (so they can’t turn evil). You need to connect your client to a relay for it to work. There are many relays & you can run your own.
Run your own:
nostr can do more than just social media.
Games? WTF? Yes, games:
- Jester - Chess over nostr by theborakompanioni
Tips & Tricks #
Some things work a bit differently and aren’t always obvious, such as:
Finding others #
Use this search query to find nostr keys of people you follow on twitter:
This uses the nostr.directory verification message, but the
&pf=1 limits the twitter search to only people you follow.
Posting images #
Many popular clients support image uploads directly. (Keep in mind that all uploaded images to external hosts are public, so don’t upload confidential things willy-nilly.)
Most clients will display image URLs as images, so you can just upload any image to image sharing sites and post the URL like this:
This also works for videos.
Here are some free image hosts:
You can also use your Twitter display picture by following this guide.
Verifying yourself #
If you have a domain and want to have a “verified” checkmark, here is some useful info:
There are also centralized verification services that you can use, but be aware that all these are centralized and that they can rug-pull you at any moment:
NostrPlebs.com (12.5k sats)
Plebs.Place (5k sats)
no.str.cr ($1.00 USD)
Verified-Nostr.com ($0.99 USD / month)
Nostrich.Love (420 sats)
nostr-relay.org (1000 sats)
Provider missing? Price changed?
Please create a PR or open an issue to fix it!
Receiving Zaps #
Zaps are V4V lightning payments that are broadcast as nostr events, so that clients can display them on user profiles and specific notes.
To receive zaps you need a lightning wallet that supports NIP-57.
Four popular custodial solutions are Wallet of Satoshi, Stacker News, Lightning Tip Bot, and Alby.
To use Lightning Tip Bot in a more private way, you can:
- Use sms4sats to sign up to Telegram
- Create an LN.tips wallet
/nostr add <your_npub>to add your npub
/advancedto see your anonymous lightning address…
- …and add it to your nostr profile. Done!
Mentions & Deep Links #
You can mention a note or a user by putting an “@” before an npub or note like this:
When mentioning a note in another note, the note will be shown as a quote-note.9
Most clients support the
nostr: URL scheme as defined in NIP-21, which means you can link to your nostr profile by putting “nostr:” in front of your npub. This will result in a link that opens in the user’s nostr client, like so: open my nostr profile.
You can use this for http redirects too, which can be used as a way to verify your nostr profile if you own a domain, like so: dergigi.com/npub
There is even a redirect tool that you can use; h/t to David for putting it together.
Ever since Jack joined (and funded some nostr devs) and Elon put it on his naughty list a flood of people came streaming in. Since everything is out in the open, you can see this nicely in the stats.
Some clients will render Lightning invoices natively, showing the recipient, amount, and a pay button. One such client is Damus, which shows a nice little widget and a pay button.
Most clients support search, but there’s also:
You can also create a search bot at sb.nostr.band and then follow it to receive new posts matching a keyword or hashtag right into your feed.
- How to build a nostr gm bot by Gigi
- nostr_bot Rust crate
You can also create an RSS feed with posts matching some keywords at rss.nostr.band and use your favorite RSS reader app to follow different nostr conversations.
- nostrovia - weekly nostr news roundup
- La Cosa Nostr - interviews with relay operators and builders
- Nostr Talks - Nostr related news and interviews
- BR018 - jack, fiatjaf, and jb55 talk nostr with nvk (transcript, archive)
- Lightning Tidbits 769571 - fiatjaf talks nostr with André Neves
- CD63 - building nostr, a censorship resistant alternative to twitter, with fiatjaf, jb55, and kukks, hosted by ODELL (transcript, archive)
- BA691 - A Native Protocol for Social Media by jack
- BTC111 - Decentralized Social Media & Bitcoin with jb55 hosted by Preston Pysh (transcript, archive)
- What’s new with Stacker.News and Nostr? a conversation with Keyan Kousha and Max Webster (transcript, archive)
There are multiple privacy issues when it comes to using nostr.
Your IP address is exposed to the relays you connect to, so consider using a VPN or similar. Some clients also support connecting via Tor. Tor nostr relays exist, but not all clients support Tor nostr relays.
Relays also know which public keys you are requesting, meaning your public key will be tied to your IP address.
Privacy & Image Uploads #
Some third party media hosters may be able to see, and share your IP address.
Privacy & Direct Messages #
Only the message content is encrypted on Nostr: the sender, recipient and timestamp are visible to everyone.
More info #
- nostr.how by Jeff Gardner
- nostr.net aka awesome-nostr by @aaaljaz
- nostr-protocol/nostr by fiatjaf
Articles and explainers:
- What Is Nostr and How Do I Use It? by Walker V.
- usenostr.org by Pluja
- What is Nostr, and how to start using Nostr by Vishal
- Nostr, an Introduction by Greg Heartsfield
- Nostr Newcomers Most Common Questions and Answers by pitiunited
- Why Nostr Matters by Jameson Lopp
- Video: How To Use NOSTR by BTC Sessions
It’s still very early days.
Get Involved #
nostr is an open protocol and most clients are open-source. You are encouraged to report bugs and create pull requests!
Check out awesome-nostr for links to other clients, libraries, relay implementations, and related projects to work on.
Also make sure to have a look at the various nostr bounties if you’re in the mood to earn sats.
This site is open source too. If you can, please improve this page. You can also create a translation.
- Chinese translation by Cakksakkas
- French translation by Marco.BTC.fr
- Spanish translation by BitByBit
- German translation by cercatrova
- Italian translation by avallanosterza
- Brazilian Portuguese translation por fernandoporazzi
Please create a PR to add your translation to the list above.
This project evolved out of a gist that was quite hastily put together. Its purpose was to help people wrap their heads around nostr, and I guess this is the purpose still.
Some of the text above is copied from nostr-protocol/nostr and nostr.net. I just left some stuff out, so consider the descriptions and explanations an opinionated summary.
If you found a typo, please fix it. If you have suggestions, please create an issue. If you want to scream at me because you think this whole thing is stupid, please find me on nostr.
nostr = Notes and Other Stuff Transmitted by Relays ↩
You have to trust whoever is running the website, obviously, and some clients are vulnerable to XSS attacks. A lot of people got rekt already, and had to re-build their nostr identity because of it. ↩
There’s also the damus.io/key but DO NOT use it for private key conversions. Don’t paste your private key into websites. Just don’t. ↩
Apple Silicone only (M1 or M2 chip) ↩
Fork with small modifications/fixes: Install a nostr relay ↩
How’s that for a tongue twister? ↩