nips-overview.md raw

Nostr Implementation Possibilities (NIPs) - Complete Overview

This document provides detailed descriptions of all standard NIPs from the nostr-protocol/nips repository.

Core Protocol NIPs

NIP-01: Basic Protocol Flow Description

Status: Mandatory for all implementations

The foundational NIP that defines the entire Nostr protocol.

Events

Events are the only object type in Nostr. Structure:

{
  "id": "<32-bytes lowercase hex>",
  "pubkey": "<32-bytes lowercase hex>",
  "created_at": "<unix timestamp>",
  "kind": "<integer>",
  "tags": [["<key>", "<value>", ...]],
  "content": "<string>",
  "sig": "<64-bytes hex>"
}

Event ID Calculation:

  1. Serialize to JSON array: [0, pubkey, created_at, kind, tags, content]
  2. UTF-8 encode
  3. Calculate SHA256 hash
  4. Result is the event ID

Signature:

Communication Protocol

All communication happens over WebSocket.

Client Messages:

  1. ["EVENT", <event>] - Publish event
  2. ["REQ", <subscription_id>, <filter>, ...] - Subscribe
  3. ["CLOSE", <subscription_id>] - Unsubscribe

Relay Messages:

  1. ["EVENT", <subscription_id>, <event>] - Send event
  2. ["OK", <event_id>, <accepted>, <message>] - Command result
  3. ["EOSE", <subscription_id>] - End of stored events
  4. ["CLOSED", <subscription_id>, <message>] - Forced close
  5. ["NOTICE", <message>] - Human-readable notice

Filters

Filter object fields (all optional):

A filter matches if ALL conditions are met. Within arrays, conditions are ORed.

Basic Event Kinds

NIP-02: Contact List and Petnames

Status: Widely implemented

Defines event kind 3 for user contact lists (following lists).

Format:

{
  "kind": 3,
  "tags": [
    ["p", "<pubkey>", "<relay-url>", "<petname>"]
  ],
  "content": "<relay-list-json>"
}

Characteristics:

Usage:

NIP-03: OpenTimestamps Attestations

Status: Optional

Allows embedding OpenTimestamps proofs in events.

Format:

{
  "tags": [
    ["ots", "<base64-ots-proof>"]
  ]
}

Used to prove an event existed at a specific time via Bitcoin blockchain timestamps.

NIP-04: Encrypted Direct Messages

Status: Deprecated (use NIP-44)

Event kind 4 for encrypted private messages.

Encryption:

Format:

{
  "kind": 4,
  "tags": [
    ["p", "<recipient-pubkey>"]
  ],
  "content": "<encrypted-content>"
}

Security Issues:

NIP-05: Mapping Nostr Keys to DNS-based Internet Identifiers

Status: Widely implemented

Allows verification of identity via domain names (like email addresses).

Format: name@domain.com

Implementation:

  1. User adds "nip05": "alice@example.com" to metadata (kind 0)
  2. Domain serves /.well-known/nostr.json:
{
  "names": {
    "alice": "<hex-pubkey>"
  },
  "relays": {
    "<hex-pubkey>": ["wss://relay1.com", "wss://relay2.com"]
  }
}
  1. Clients verify by fetching and checking pubkey match

Benefits:

NIP-06: Basic Key Derivation from Mnemonic Seed Phrase

Status: Optional

Derives Nostr keys from BIP39 mnemonic phrases.

Derivation Path: m/44'/1237'/0'/0/0

Benefits:

NIP-07: window.nostr Capability for Web Browsers

Status: Browser extension standard

Defines browser API for Nostr key management.

API Methods:

window.nostr.getPublicKey(): Promise<pubkey>
window.nostr.signEvent(event): Promise<signedEvent>
window.nostr.getRelays(): Promise<{[url]: {read: boolean, write: boolean}}>
window.nostr.nip04.encrypt(pubkey, plaintext): Promise<ciphertext>
window.nostr.nip04.decrypt(pubkey, ciphertext): Promise<plaintext>

Usage:

NIP-08: Handling Mentions

Status: Core convention

Defines how to mention users and events in notes.

Format:

{
  "kind": 1,
  "tags": [
    ["p", "<pubkey>", "<relay>"],
    ["e", "<event-id>", "<relay>"]
  ],
  "content": "Hello #[0], check out #[1]"
}

Clients replace #[0], #[1] with user-friendly displays.

NIP-09: Event Deletion

Status: Widely implemented

Event kind 5 requests deletion of events.

Format:

{
  "kind": 5,
  "tags": [
    ["e", "<event-id-to-delete>"],
    ["e", "<another-event-id>"]
  ],
  "content": "Reason for deletion (optional)"
}

Behavior:

NIP-10: Text Note References (Reply, Threads)

Status: Core threading standard

Conventions for e and p tags in threaded conversations.

Markers:

Format:

{
  "kind": 1,
  "tags": [
    ["e", "<root-event-id>", "<relay>", "root"],
    ["e", "<parent-event-id>", "<relay>", "reply"],
    ["e", "<mentioned-event-id>", "<relay>", "mention"],
    ["p", "<author1-pubkey>"],
    ["p", "<author2-pubkey>"]
  ]
}

Best Practices:

NIP-11: Relay Information Document

Status: Standard

HTTP endpoint for relay metadata.

Implementation:

Response Example:

{
  "name": "Example Relay",
  "description": "A Nostr relay",
  "pubkey": "<admin-pubkey>",
  "contact": "admin@example.com",
  "supported_nips": [1, 2, 9, 11, 12, 15, 16, 20, 22],
  "software": "git+https://github.com/...",
  "version": "1.0.0",
  "limitation": {
    "max_message_length": 16384,
    "max_subscriptions": 20,
    "max_filters": 100,
    "max_limit": 5000,
    "max_subid_length": 100,
    "min_prefix": 4,
    "max_event_tags": 100,
    "max_content_length": 8196,
    "min_pow_difficulty": 30,
    "auth_required": false,
    "payment_required": false
  },
  "relay_countries": ["US", "CA"],
  "language_tags": ["en", "es"],
  "tags": ["adult-content", "no-spam"],
  "posting_policy": "https://example.com/policy",
  "payments_url": "https://example.com/pay",
  "fees": {
    "admission": [{"amount": 5000000, "unit": "msats"}],
    "subscription": [{"amount": 1000000, "unit": "msats", "period": 2592000}],
    "publication": []
  },
  "icon": "https://example.com/icon.png"
}

Usage:

NIP-12: Generic Tag Queries

Status: Core functionality

Extends filtering to support any single-letter tag.

Syntax: #<letter>: [<value>, ...]

Examples:

{
  "#t": ["bitcoin", "nostr"],
  "#p": ["pubkey1", "pubkey2"],
  "#e": ["eventid1"]
}

Matches events with specified tag values.

NIP-13: Proof of Work

Status: Spam prevention

Requires computational work for event publication.

Implementation:

Example:

{
  "tags": [
    ["nonce", "12345", "20"]
  ],
  "id": "00000abcd..." // 20+ leading zero bits
}

Difficulty Levels:

Relays can require minimum PoW for acceptance.

NIP-14: Subject Tag

Status: Convenience

Adds subject tag for event titles/subjects.

Format:

{
  "tags": [
    ["subject", "My Post Title"]
  ]
}

Used for long-form content, discussions, emails-style messages.

NIP-15: End of Stored Events (EOSE)

Status: Core protocol

Relay sends EOSE after sending all stored events matching a subscription.

Format: ["EOSE", <subscription_id>]

Usage:

NIP-16: Event Treatment

Status: Event lifecycle

Defines three event categories:

  1. Regular Events (1000-9999):

- Immutable - All versions kept - Examples: notes, reactions

  1. Replaceable Events (10000-19999):

- Only latest kept - Same author + kind → replace - Examples: metadata, contacts

  1. Ephemeral Events (20000-29999):

- Not stored - Forwarded once - Examples: typing indicators, presence

  1. Parameterized Replaceable Events (30000-39999):

- Replaced based on d tag - Same author + kind + d-tag → replace - Examples: long-form posts, product listings

NIP-18: Reposts

Status: Social feature

Event kind 6 for reposting/sharing events.

Format:

{
  "kind": 6,
  "tags": [
    ["e", "<reposted-event-id>", "<relay>"],
    ["p", "<original-author-pubkey>"]
  ],
  "content": "" // or reposted event JSON
}

Generic Repost (kind 16):

NIP-19: bech32-encoded Entities

Status: Widely implemented

Human-readable encodings for Nostr entities.

Formats:

  1. npub: Public key

- npub1xyz... - Safer to share than hex

  1. nsec: Private key (SENSITIVE!)

- nsec1xyz... - Never share publicly

  1. note: Event ID

- note1xyz... - Links to specific events

  1. nprofile: Profile with hints

- Includes pubkey + relay URLs - Better discovery

  1. nevent: Event with hints

- Includes event ID + relay URLs + author - Reliable event fetching

  1. naddr: Replaceable event coordinate

- Includes kind + pubkey + d-tag + relays - For parameterized replaceable events

Usage:

NIP-20: Command Results

Status: Core protocol

Defines OK message format from relays.

Format: ["OK", <event_id>, <accepted>, <message>]

Examples:

["OK", "abc123...", true, ""]
["OK", "def456...", false, "invalid: signature verification failed"]
["OK", "ghi789...", false, "pow: difficulty too low"]
["OK", "jkl012...", false, "rate-limited: slow down"]

Common Rejection Prefixes:

NIP-21: nostr: URI Scheme

Status: Standard linking

Defines nostr: URI scheme for deep linking.

Format:

Usage:

NIP-22: Event created_at Limits

Status: Relay policy

Relays may reject events with timestamps too far in past/future.

Recommendations:

NIP-23: Long-form Content

Status: Blog/article support

Event kind 30023 for long-form content (articles, blogs).

Format:

{
  "kind": 30023,
  "tags": [
    ["d", "<unique-identifier>"],
    ["title", "Article Title"],
    ["summary", "Brief description"],
    ["published_at", "<unix-timestamp>"],
    ["t", "tag1"], ["t", "tag2"],
    ["image", "https://..."]
  ],
  "content": "Markdown content..."
}

Characteristics:

NIP-25: Reactions

Status: Widely implemented

Event kind 7 for reactions to events (likes, emoji reactions).

Format:

{
  "kind": 7,
  "tags": [
    ["e", "<reacted-event-id>"],
    ["p", "<event-author-pubkey>"],
    ["k", "<reacted-event-kind>"]
  ],
  "content": "+" // or emoji
}

Content Values:

Client Display:

NIP-26: Delegated Event Signing

Status: Advanced delegation

Allows delegating event signing to another key.

Use Cases:

Implementation:

NIP-27: Text Note References

Status: Convenience

Shortcuts for mentioning entities inline.

Format:

Clients render as clickable links.

NIP-28: Public Chat (Channels)

Status: Channel support

Event kinds for public chat channels.

Event Kinds:

Channel Creation (kind 40):

{
  "kind": 40,
  "content": "{\"name\": \"Bitcoin\", \"about\": \"Discussion\", \"picture\": \"url\"}"
}

Channel Message (kind 42):

{
  "kind": 42,
  "tags": [
    ["e", "<channel-id>", "<relay>", "root"]
  ],
  "content": "Hello channel!"
}

NIP-33: Parameterized Replaceable Events

Status: Core feature

Event kinds 30000-39999 are replaceable by d tag.

Format:

{
  "kind": 30000,
  "tags": [
    ["d", "<identifier>"]
  ]
}

Replacement Rule:

Coordinate Reference: <kind>:<pubkey>:<d-value>

Use Cases:

NIP-36: Sensitive Content Warning

Status: Content moderation

Tags for marking sensitive/NSFW content.

Format:

{
  "tags": [
    ["content-warning", "nudity"],
    ["content-warning", "violence"]
  ]
}

Clients can hide/blur until user confirms.

NIP-39: External Identities

Status: Identity verification

Links Nostr identity to external platforms.

Format (in kind 0 metadata):

{
  "kind": 0,
  "content": "{\"identities\": [{\"platform\": \"github\", \"username\": \"alice\", \"proof\": \"url\"}]}"
}

Supported Platforms:

NIP-40: Expiration Timestamp

Status: Ephemeral content

Tag for auto-expiring events.

Format:

{
  "tags": [
    ["expiration", "<unix-timestamp>"]
  ]
}

Relays should delete event after expiration time.

NIP-42: Authentication of Clients to Relays

Status: Access control

Relays can require client authentication.

Flow:

  1. Relay sends: ["AUTH", "<challenge>"]
  2. Client creates kind 22242 event:
{
  "kind": 22242,
  "tags": [
    ["relay", "<relay-url>"],
    ["challenge", "<challenge-string>"]
  ],
  "created_at": <now>
}
  1. Client sends: ["AUTH", <signed-event>]
  2. Relay verifies signature and challenge

Benefits:

NIP-44: Encrypted Payloads (Versioned)

Status: Modern encryption

Improved encryption replacing NIP-04.

Algorithm:

Security Improvements:

Format:

<version-byte><encrypted-payload>

Base64 encode for content field.

NIP-45: Event Counts

Status: Statistics

Request for event counts matching filters.

Client Request:

["COUNT", <subscription_id>, <filters>]

Relay Response:

["COUNT", <subscription_id>, {"count": 123, "approximate": false}]

Usage:

NIP-46: Nostr Connect (Remote Signing)

Status: Remote signer protocol

Protocol for remote key management and signing.

Architecture:

Use Cases:

NIP-47: Wallet Connect

Status: Lightning integration

Protocol for connecting Lightning wallets to Nostr apps.

Commands:

Enables in-app Lightning payments.

NIP-50: Search Capability

Status: Optional

Full-text search in filter queries.

Format:

{
  "search": "bitcoin nostr"
}

Implementation:

NIP-51: Lists

Status: Curation

Event kinds for various list types.

List Kinds:

Format:

{
  "kind": 30000,
  "tags": [
    ["d", "my-list"],
    ["p", "<pubkey>", "<relay>", "<petname>"],
    ["t", "<category>"]
  ]
}

NIP-56: Reporting

Status: Moderation

Event kind 1984 for reporting content.

Format:

{
  "kind": 1984,
  "tags": [
    ["e", "<event-id>", "<relay>"],
    ["p", "<pubkey>"],
    ["report", "spam"] // or "nudity", "profanity", "illegal", "impersonation"
  ],
  "content": "Additional details"
}

Used by relays and clients for moderation.

NIP-57: Lightning Zaps

Status: Widely implemented

Protocol for Lightning tips with proof.

Flow:

  1. Get user's Lightning address (from metadata)
  2. Fetch LNURL data
  3. Create zap request (kind 9734)
  4. Pay invoice
  5. Relay publishes zap receipt (kind 9735)

Zap Request (kind 9734):

{
  "kind": 9734,
  "tags": [
    ["p", "<recipient-pubkey>"],
    ["amount", "<millisats>"],
    ["relays", "relay1", "relay2"],
    ["e", "<event-id>"] // if zapping event
  ]
}

Zap Receipt (kind 9735): Published by LNURL provider, proves payment.

NIP-58: Badges

Status: Reputation system

Award and display badges (achievements, credentials).

Event Kinds:

Badge Definition:

{
  "kind": 30008,
  "tags": [
    ["d", "badge-id"],
    ["name", "Badge Name"],
    ["description", "What this means"],
    ["image", "url"],
    ["thumb", "thumbnail-url"]
  ]
}

NIP-65: Relay List Metadata

Status: Critical for routing

Event kind 10002 for user's relay preferences.

Format:

{
  "kind": 10002,
  "tags": [
    ["r", "wss://relay1.com"],
    ["r", "wss://relay2.com", "write"],
    ["r", "wss://relay3.com", "read"]
  ]
}

Usage:

Best Practice:

NIP-78: App-Specific Data

Status: Application storage

Event kind 30078 for arbitrary app data.

Format:

{
  "kind": 30078,
  "tags": [
    ["d", "<app-name>:<data-key>"]
  ],
  "content": "<encrypted-or-public-data>"
}

Use Cases:

NIP-84: Highlights

Status: Annotation

Event kind 9802 for highlighting content.

Format:

{
  "kind": 9802,
  "tags": [
    ["e", "<event-id>"],
    ["context", "surrounding text..."],
    ["a", "<article-coordinate>"]
  ],
  "content": "highlighted portion"
}

Like a highlighter pen for web content.

NIP-89: Application Handlers

Status: App discovery

Advertise and discover apps that handle specific event kinds.

Format (kind 31989):

{
  "kind": 31989,
  "tags": [
    ["k", "1"], // handles kind 1
    ["web", "https://app.com/<bech32>"],
    ["ios", "app-scheme://<bech32>"],
    ["android", "app-package://<bech32>"]
  ]
}

Kind 31990: User's preferred handlers

NIP-94: File Metadata

Status: File sharing

Event kind 1063 for file metadata.

Format:

{
  "kind": 1063,
  "tags": [
    ["url", "https://..."],
    ["m", "image/jpeg"], // MIME type
    ["x", "<sha256-hash>"],
    ["size", "123456"],
    ["dim", "1920x1080"],
    ["magnet", "magnet:..."],
    ["blurhash", "..."]
  ],
  "content": "Description"
}

Use Cases:

NIP-96: HTTP File Storage Integration

Status: File hosting

HTTP API for file uploads/downloads.

Endpoints:

Upload Response: Returns kind 1063 event data for the file.

NIP-98: HTTP Auth

Status: API authentication

Use Nostr events for HTTP API auth.

Flow:

  1. Create kind 27235 event with:

- u tag: API URL - method tag: HTTP method

  1. Add Authorization: Nostr <base64-event> header
  2. Server verifies signature

Benefits:

Summary of Key NIPs by Category

Essential (All implementations)

Social Features

Identity & Discovery

Security & Privacy

Lightning Integration

Content & Moderation

Advanced Features