NIP-19: bech32-encoded Entities

Status: Final Authors: jb55, fiatjaf Category: Data Encoding

---

Overview

NIP-19 defines bech32 encoding for Nostr identifiers, making them:

• ✅ Human-readable - Clear prefixes like npub, nsec, note
• ✅ Copy-paste friendly - Easily selected and shared
• ✅ Error-detecting - Built-in checksums catch typos
• ✅ URI-compatible - Safe for URLs and apps

Instead of raw hex strings, NIP-19 creates friendly identifiers like:

• npub1... (public keys)
• note1... (event IDs)
• nprofile1... (profiles with relay hints)

---

Why bech32 Encoding?

The Problem: Hex is Unfriendly

Raw Nostr identifiers are 64-character hex strings:

Public key: 6e468422dfb74a5738702a8823b9b28168abab8655faacb6853cd0ee15deee93
Event ID:   4376c65d2f232afbe9b882a35baa4f6fe8667c4e684749af565f981833ed6a65

Problems:

• Hard to visually distinguish (public key vs event ID?)
• No error detection (typos propagate silently)
• Difficult to select (64 random characters)
• Not user-friendly

The Solution: bech32 with Prefixes

NIP-19 uses bech32 encoding (same as Bitcoin addresses) with descriptive prefixes:

Public key: npub1de5gss7lkafc0pe2s2sz8wjsx6v4hvxxg8l6e60v8uuguvs7m5fsq4qwxm
Event ID:   note1ggh55hf7yg4twmp0pqpm5dzz7mv7znznge85nht6v7vp835m82jskqytt4

Benefits:

• ✅ Clear type (npub = public key, note = event)
• ✅ Error detection (checksum catches typos)
• ✅ Case-insensitive (easier to type)
• ✅ Double-click to select (ends at whitespace)

---

Entity Types

1. npub - Public Keys

Prefix: npub Contains: 32-byte public key (hex → bech32)

Example:

Hex: 6e468422dfb74a5738702a8823b9b28168abab8655faacb6853cd0ee15deee93
npub: npub1de5gss7lkafc0pe2s2sz8wjsx6v4hvxxg8l6e60v8uuguvs7m5fsq4qwxm

Use cases:

• Sharing your public identity
• Mentioning users
• Following someone
• Displaying in profiles

---

2. nsec - Private Keys

Prefix: nsec Contains: 32-byte private key (hex → bech32)

Example:

Hex: L4rK1yDdCWezvXLEeAGXR...
nsec: nsec1l9uxh7pzk30lq74hj89t2nuwwvx7lse9rlmwzxmkcrqd7zfj5nzqpwkfld

⚠️ NEVER share your nsec!

• nsec = your private key
• Anyone with your nsec controls your account
• No recovery if stolen
• Store securely offline

Use cases:

• Backup your key
• Import key to new client
• Private storage only (never share!)

---

3. note - Event IDs

Prefix: note Contains: 32-byte event ID (hex → bech32)

Example:

Hex: 4376c65d2f232afbe9b882a35baa4f6fe8667c4e684749af565f981833ed6a65
note: note1ggh55hf7yg4twmp0pqpm5dzz7mv7znznge85nht6v7vp835m82jskqytt4

Use cases:

• Sharing specific posts
• Linking to events
• Quoting notes
• Bookmarking content

---

4. nprofile - Profiles with Relay Hints

Prefix: nprofile Contains:

• Public key
• Suggested relay URLs
• (Optional) Additional metadata

Structure (TLV-encoded):

0: pubkey (32 bytes)
1: relay URL (variable length, can have multiple)

Example:

nprofile1qqsrhuxx8l9ex335q7he0f09aej04zpazpl0ne2cgukyawd24mayt8gpp4mhxue69uhhytnc9e3k7mgpz4mhxue69uhkg6nzv9ejuumpv34kytnrdaksjlyr9p

Decoded:

• Pubkey: 6e468422dfb74a...
• Relays: wss://relay.damus.io, wss://relay.nostr.band

Use cases:

• Sharing profiles with relay hints
• Deep links to user profiles
• Improving discoverability

---

5. nevent - Events with Context

Prefix: nevent Contains:

• Event ID
• Suggested relay URLs
• (Optional) Author pubkey
• (Optional) Event kind

Structure (TLV-encoded):

0: event ID (32 bytes)
1: relay URL (variable length, can have multiple)
2: author pubkey (32 bytes, optional)
3: kind (4 bytes, optional)

Example:

nevent1qqstna2yrezu5wghjvpqgjhe0qmq0l7ld6fv3p7hsp7q6f2lqvpvpuqpz4mhxue69uhhyetvv9ujuerpd46hxtnfduhszythwden5te0dehhxarj9emkjmn9qyg8wumn8ghj7mn0wd68ytnhd9hx2tmwv43k5mrv9ehx7um5wghxcctwvshsmxhw4

Decoded:

• Event ID: 4376c65d2f23...
• Relays: wss://relay.damus.io, wss://relay.primal.net
• Author: 6e468422dfb7...

Use cases:

• Sharing events with relay information
• Deep linking to specific posts
• Ensuring event discoverability

---

6. naddr - Parameterized Replaceable Events

Prefix: naddr Contains:

• Event kind
• Author pubkey
• D-tag identifier
• Suggested relay URLs

Structure (TLV-encoded):

0: special (string, d-tag identifier)
1: relay URL (variable length, can have multiple)
2: author pubkey (32 bytes)
3: kind (4 bytes)

Use cases:

• Long-form articles (kind 30023)
• User profiles (kind 0)
• Replaceable event references

---

7. nrelay - Relay URLs

Prefix: nrelay Contains: Relay WebSocket URL

Example:

nrelay1qq28wumn8ghj7un9d3shjtnyv9kh2uewd9hsc5ztda

Decoded: wss://relay.damus.io

Use cases:

• Sharing relay URLs
• Relay recommendations
• Client relay configuration

---

Encoding & Decoding

Encoding Example (JavaScript)

import { nip19 } from 'nostr-tools';

// Encode public key
const npub = nip19.npubEncode('6e468422dfb74a5738702a8823b9b28168abab8655faacb6853cd0ee15deee93');
// Result: npub1de5gss7lkafc0pe2s2sz8wjsx6v4hvxxg8l6e60v8uuguvs7m5fsq4qwxm

// Encode event ID
const noteId = nip19.noteEncode('4376c65d2f232afbe9b882a35baa4f6fe8667c4e684749af565f981833ed6a65');
// Result: note1ggh55hf7yg4twmp0pqpm5dzz7mv7znznge85nht6v7vp835m82jskqytt4

// Encode profile with relay hints
const nprofile = nip19.nprofileEncode({
  pubkey: '6e468422dfb74a5738702a8823b9b28168abab8655faacb6853cd0ee15deee93',
  relays: ['wss://relay.damus.io', 'wss://relay.nostr.band']
});

// Encode event with context
const nevent = nip19.neventEncode({
  id: '4376c65d2f232afbe9b882a35baa4f6fe8667c4e684749af565f981833ed6a65',
  relays: ['wss://relay.damus.io'],
  author: '6e468422dfb74a5738702a8823b9b28168abab8655faacb6853cd0ee15deee93',
  kind: 1
});

---

Decoding Example (JavaScript)

import { nip19 } from 'nostr-tools';

// Decode npub
const { type, data } = nip19.decode('npub1de5gss7lkafc0pe2s2sz8wjsx6v4hvxxg8l6e60v8uuguvs7m5fsq4qwxm');
console.log(type); // "npub"
console.log(data); // "6e468422dfb74a5738702a8823b9b28168abab8655faacb6853cd0ee15deee93"

// Decode nprofile
const { type, data } = nip19.decode('nprofile1qqsr...');
console.log(data.pubkey); // Public key hex
console.log(data.relays); // Array of relay URLs

// Decode nevent
const { type, data } = nip19.decode('nevent1qqst...');
console.log(data.id);      // Event ID
console.log(data.relays);  // Relay hints
console.log(data.author);  // Author pubkey
console.log(data.kind);    // Event kind

---

TLV Encoding (Type-Length-Value)

For complex entities (nprofile, nevent, naddr), NIP-19 uses TLV encoding:

Structure

Each field is encoded as:

[type: 1 byte][length: 1 byte][value: variable]

Example: nprofile

Type 0 (pubkey):    00 20 [32 bytes of pubkey]
Type 1 (relay):     01 15 [21 bytes: "wss://relay.damus.io"]
Type 1 (relay):     01 17 [23 bytes: "wss://relay.nostr.band"]

This TLV data is then bech32-encoded with prefix nprofile.

---

Practical Usage

Sharing Your Profile

Option 1: Just the public key (npub)

npub1de5gss7lkafc0pe2s2sz8wjsx6v4hvxxg8l6e60v8uuguvs7m5fsq4qwxm

Users will find you if you’re on common relays.

Option 2: Profile with relay hints (nprofile)

nprofile1qqsrhuxx8l9ex335q7he0f09aej04zpazpl0ne2cgukyawd24mayt8gpp4mhxue69uhhytnc9e3k7mgpz4mhxue69uhkg6nzv9ejuumpv34kytnrdaksjlyr9p

Includes your preferred relays—better discoverability.

---

Sharing a Note

Option 1: Just the event ID (note)

note1ggh55hf7yg4twmp0pqpm5dzz7mv7znznge85nht6v7vp835m82jskqytt4

Clients query all relays to find this event.

Option 2: Event with context (nevent)

nevent1qqstna2yrezu5wghjv...

Includes relay hints and author—faster discovery.

---

Deep Linking

Many Nostr clients support nostr: URI scheme:

nostr:npub1de5gss7lkafc0pe2s2sz8wjsx6v4hvxxg8l6e60v8uuguvs7m5fsq4qwxm
nostr:note1ggh55hf7yg4twmp0pqpm5dzz7mv7znznge85nht6v7vp835m82jskqytt4
nostr:nprofile1qqsr...

Example in HTML:

<a href="nostr:npub1de5gss...">Follow Alice on Nostr</a>

Clicking opens the user’s default Nostr client.

---

Security Considerations

Private Keys (nsec)

⚠️ Critical Security Rules:

1. Never share nsec: Anyone with it controls your account
2. Never post nsec: Not on social media, not in DMs, nowhere
3. Encrypt backups: Use strong encryption for nsec storage
4. No screenshots: Malware can access clipboard and screenshots
5. Use secure clients: Clients should never transmit nsec

Safe nsec usage:

• ✅ Encrypted offline backup
• ✅ Hardware wallets (when supported)
• ✅ Import to trusted client on secure device
• ❌ Never paste in web forms
• ❌ Never send in messages
• ❌ Never share online

---

Error Detection

bech32 includes a checksum that detects:

• ✅ Single character errors
• ✅ Transposed characters
• ✅ Insertion/deletion errors

Example:

Valid:   npub1de5gss7lkafc0pe2s2sz8wjsx6v4hvxxg8l6e60v8uuguvs7m5fsq4qwxm
Invalid: npub1de5gss7lkafc0pe2s2sz8wjsx6v4hvxxg8l6e60v8uuguvs7m5fsq4qWxm
                                                                      ^ typo detected

Clients will reject invalid identifiers.

---

Client Support

Full Support

• Damus - Displays npub, note, supports nevent/nprofile
• Primal - Full NIP-19 support, deep linking
• Amethyst - All entity types, QR codes
• Snort - Encoding/decoding, sharing
• Iris - Profile sharing with nprofile
• Nostrudel - Advanced NIP-19 tools

Common Features

• Display npub in user profiles
• Share notes as note1...
• Deep link support (nostr: URIs)
• QR code generation

See our Client Directory for details.

---

Conversion Tools

Online Converters

• nostr.com - Hex ↔ NIP-19 converter
• nostrid.com - Multi-format converter
• nostr.guru - Developer tools

Command-Line Tools

Using nostr-tools:

npm install -g nostr-tools

# Encode
nostr encode npub 6e468422dfb74a5738702a8823b9b28168abab8655faacb6853cd0ee15deee93

# Decode
nostr decode npub1de5gss7lkafc0pe2s2sz8wjsx6v4hvxxg8l6e60v8uuguvs7m5fsq4qwxm

---

Common Questions

Should I use npub or nprofile?

npub: Simple, shorter, works if you’re on popular relays nprofile: Better discoverability, includes relay hints

Recommendation: Use nprofile when sharing your profile publicly.

---

Can I convert hex to npub and back?

Yes, they’re the same data in different encodings:

Hex: 6e468422dfb74a5738702a8823b9b28168abab8655faacb6853cd0ee15deee93
npub: npub1de5gss7lkafc0pe2s2sz8wjsx6v4hvxxg8l6e60v8uuguvs7m5fsq4qwxm

Use libraries like nostr-tools to convert.

---

What’s the difference between note and nevent?

note: Just the event ID nevent: Event ID + relay hints + author + kind

nevent provides more context for finding the event.

---

Why are NIP-19 identifiers so long?

They include:

• The actual data (32 bytes = 64 hex chars)
• bech32 encoding overhead
• Checksum for error detection
• (For nprofile/nevent) Relay URLs and metadata

Trade-off: Longer but safer and more informative.

---

Related NIPs

• NIP-01 - Basic protocol (event structure)
• NIP-21 - nostr: URI scheme
• NIP-27 - Mentions with NIP-19 identifiers

---

For Developers

Implementation Checklist

Display:

• Show npub instead of hex in UIs
• Convert event IDs to note for sharing
• Support nprofile/nevent with relay hints

Encoding:

• Encode public keys as npub
• Encode event IDs as note
• Support nprofile for profile sharing
• Support nevent for event sharing

Decoding:

• Parse and validate bech32
• Decode TLV for nprofile/nevent
• Handle all entity types
• Validate checksums

Security:

• Never transmit nsec over network
• Warn users when displaying nsec
• Encrypt nsec in storage
• Clear nsec from memory after use

---

Recommended Libraries

JavaScript:

import { nip19 } from 'nostr-tools';

// All encoding/decoding handled by library

Python:

from nostr.nip19 import encode, decode

npub = encode('npub', pubkey_hex)
decoded = decode(npub)

Rust:

use nostr_sdk::nips::nip19;

let npub = nip19::encode_pubkey(&public_key);
let decoded = nip19::decode(npub)?;

---

Technical Specification

For complete technical details, see NIP-19 on GitHub.

---

Summary

NIP-19 makes Nostr identifiers user-friendly:

✅ npub - Public keys (shareable identity) ✅ nsec - Private keys (never share!) ✅ note - Event IDs (link to posts) ✅ nprofile - Profiles with relay hints ✅ nevent - Events with context ✅ naddr - Parameterized replaceable events ✅ nrelay - Relay URLs

Benefits:

• Human-readable prefixes
• Error detection via checksums
• Copy-paste friendly
• URI-compatible

Remember: Always use npub publicly, never share nsec.

---

Next Steps:

• Learn about mentions in NIP-27
• Explore reactions in NIP-25
• Understand event deletion in NIP-09
• Browse all NIPs in our reference

---

Last updated: January 2024 Official specification: GitHub