next.orly.dev/.claude/skills/nostr/references/event-kinds.md

Nostr Event Kinds - Complete Reference

This document provides a comprehensive list of all standard and commonly-used Nostr event kinds.

Standard Event Kinds

Core Events (0-999)

Metadata and Profile

• 0: Metadata - User profile information (name, about, picture, etc.)
  • Replaceable
  • Content: JSON with profile fields

Text Content

• 1: Text Note - Short-form post (like a tweet)
  • Regular event (not replaceable)
  • Most common event type

Relay Recommendations

• 2: Recommend Relay - Deprecated, use NIP-65 instead

Contact Lists

• 3: Contacts - Following list with optional relay hints
  • Replaceable
  • Tags: p tags for each followed user

Encrypted Messages

• 4: Encrypted Direct Message - Private message (NIP-04, deprecated)
  • Regular event
  • Use NIP-44 instead for better security

Content Management

• 5: Event Deletion - Request to delete events
  • Tags: e tags for events to delete
  • Only works for own events

Sharing

• 6: Repost - Share another event
  • Tags: e for reposted event, p for original author
  • May include original event in content

Reactions

• 7: Reaction - Like, emoji reaction to event
  • Content: "+" or emoji
  • Tags: e for reacted event, p for author

Channel Events (40-49)

• 40: Channel Creation - Create a public chat channel
• 41: Channel Metadata - Set channel name, about, picture
• 42: Channel Message - Post message in channel
• 43: Channel Hide Message - Hide a message in channel
• 44: Channel Mute User - Mute a user in channel

Regular Events (1000-9999)

Regular events are never deleted or replaced. All versions are kept.

• 1000: Example regular event
• 1063: File Metadata (NIP-94) - Metadata for shared files
  • Tags: url, MIME type, hash, size, dimensions

Replaceable Events (10000-19999)

Only the latest event of each kind is kept per pubkey.

• 10000: Mute List - List of muted users/content
• 10001: Pin List - Pinned events
• 10002: Relay List Metadata (NIP-65) - User's preferred relays
  • Critical for routing
  • Tags: r with relay URLs and read/write markers

Ephemeral Events (20000-29999)

Not stored by relays, only forwarded once.

• 20000: Example ephemeral event
• 21000: Typing Indicator - User is typing
• 22242: Client Authentication (NIP-42) - Auth response to relay

Parameterized Replaceable Events (30000-39999)

Replaced based on d tag value.

Lists (30000-30009)

• 30000: Categorized People List - Custom people lists

  • d tag: list identifier
  • p tags: people in list

• 30001: Categorized Bookmark List - Bookmark collections

  • d tag: list identifier
  • e or a tags: bookmarked items

• 30008: Badge Definition (NIP-58) - Define a badge/achievement

  • d tag: badge ID
  • Tags: name, description, image

• 30009: Profile Badges (NIP-58) - Badges displayed on profile

  • d tag: badge ID
  • e or a tags: badge awards

Long-form Content (30023)

• 30023: Long-form Article (NIP-23) - Blog post, article
  • d tag: article identifier (slug)
  • Tags: title, summary, published_at, image
  • Content: Markdown

Application Data (30078)

• 30078: Application-specific Data (NIP-78)
  • d tag: app-name:data-key
  • Content: app-specific data (may be encrypted)

Other Parameterized Replaceables

• 31989: Application Handler Information (NIP-89)

  • Declares app can handle certain event kinds

• 31990: Handler Recommendation (NIP-89)

  • User's preferred apps for event kinds

Special Event Kinds

Authentication & Signing

• 22242: Client Authentication - Prove key ownership to relay
• 24133: Nostr Connect - Remote signer protocol (NIP-46)

Lightning & Payments

• 9734: Zap Request (NIP-57) - Request Lightning payment

  • Not published to regular relays
  • Sent to LNURL provider

• 9735: Zap Receipt (NIP-57) - Proof of Lightning payment

  • Published by LNURL provider
  • Proves zap was paid

• 23194: Wallet Request (NIP-47) - Request wallet operation

• 23195: Wallet Response (NIP-47) - Response to wallet request

Content & Annotations

• 1984: Reporting (NIP-56) - Report content/users

  • Tags: reason (spam, illegal, etc.)

• 9802: Highlights (NIP-84) - Highlight text

  • Content: highlighted text
  • Tags: context, source event

Badges & Reputation

• 8: Badge Award (NIP-58) - Award a badge to someone
  • Tags: a for badge definition, p for recipient

Generic Events

• 16: Generic Repost (NIP-18) - Repost any event kind

  • More flexible than kind 6

• 27235: HTTP Auth (NIP-98) - Authenticate HTTP requests

  • Tags: URL, method

Event Kind Ranges Summary

Range	Type	Behavior	Examples
0-999	Core	Varies	Metadata, notes, reactions
1000-9999	Regular	Immutable, all kept	File metadata
10000-19999	Replaceable	Only latest kept	Mute list, relay list
20000-29999	Ephemeral	Not stored	Typing, presence
30000-39999	Parameterized Replaceable	Replaced by d tag	Articles, lists, badges

Event Lifecycle

Regular Events (1000-9999)

Event A published → Stored
Event A' published → Both A and A' stored

Replaceable Events (10000-19999)

Event A published → Stored
Event A' published (same kind, same pubkey) → A deleted, A' stored

Parameterized Replaceable Events (30000-39999)

Event A (d="foo") published → Stored
Event B (d="bar") published → Both stored (different d)
Event A' (d="foo") published → A deleted, A' stored (same d)

Ephemeral Events (20000-29999)

Event A published → Forwarded to subscribers, NOT stored

Common Patterns

Metadata (Kind 0)

{
  "kind": 0,
  "content": "{\"name\":\"Alice\",\"about\":\"Nostr user\",\"picture\":\"https://...\",\"nip05\":\"alice@example.com\"}",
  "tags": []
}

Text Note (Kind 1)

{
  "kind": 1,
  "content": "Hello Nostr!",
  "tags": [
    ["t", "nostr"],
    ["t", "hello"]
  ]
}

Reply (Kind 1 with thread tags)

{
  "kind": 1,
  "content": "Great post!",
  "tags": [
    ["e", "<root-event-id>", "<relay>", "root"],
    ["e", "<parent-event-id>", "<relay>", "reply"],
    ["p", "<author-pubkey>"]
  ]
}

Reaction (Kind 7)

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

Long-form Article (Kind 30023)

{
  "kind": 30023,
  "content": "# My Article\n\nContent here...",
  "tags": [
    ["d", "my-article-slug"],
    ["title", "My Article"],
    ["summary", "This is about..."],
    ["published_at", "1234567890"],
    ["t", "nostr"],
    ["image", "https://..."]
  ]
}

Relay List (Kind 10002)

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

Zap Request (Kind 9734)

{
  "kind": 9734,
  "content": "",
  "tags": [
    ["relays", "wss://relay1.com", "wss://relay2.com"],
    ["amount", "21000"],
    ["lnurl", "lnurl..."],
    ["p", "<recipient-pubkey>"],
    ["e", "<event-id>"]
  ]
}

File Metadata (Kind 1063)

{
  "kind": 1063,
  "content": "My photo from the trip",
  "tags": [
    ["url", "https://cdn.example.com/image.jpg"],
    ["m", "image/jpeg"],
    ["x", "abc123..."],
    ["size", "524288"],
    ["dim", "1920x1080"],
    ["blurhash", "LEHV6n..."]
  ]
}

Report (Kind 1984)

{
  "kind": 1984,
  "content": "This is spam",
  "tags": [
    ["e", "<reported-event-id>", "<relay>"],
    ["p", "<reported-pubkey>"],
    ["report", "spam"]
  ]
}

Future Event Kinds

The event kind space is open-ended. New NIPs may define new event kinds.

Guidelines for new event kinds:

1. Use appropriate range for desired behavior
2. Document in a NIP
3. Implement in at least 2 clients and 1 relay
4. Ensure backwards compatibility
5. Don't overlap with existing kinds

Custom event kinds:

• Applications can use undefined event kinds
• Document behavior for interoperability
• Consider proposing as a NIP if useful broadly

Event Kind Selection Guide

Choose based on lifecycle needs:

• Regular (1000-9999): When you need history

  • User posts, comments, reactions
  • Payment records, receipts
  • Immutable records

• Replaceable (10000-19999): When you need latest state

  • User settings, preferences
  • Mute/block lists
  • Current status

• Ephemeral (20000-29999): When you need real-time only

  • Typing indicators
  • Online presence
  • Temporary notifications

• Parameterized Replaceable (30000-39999): When you need multiple latest states

  • Articles (one per slug)
  • Product listings (one per product ID)
  • Configuration sets (one per setting name)

References

• NIPs Repository: https://github.com/nostr-protocol/nips
• NIP-16: Event Treatment
• NIP-01: Event structure
• Various feature NIPs for specific kinds