event-kinds.md raw

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

- Replaceable - Content: JSON with profile fields

Text Content

- Regular event (not replaceable) - Most common event type

Relay Recommendations

Contact Lists

- Replaceable - Tags: p tags for each followed user

Encrypted Messages

- Regular event - Use NIP-44 instead for better security

Content Management

- Tags: e tags for events to delete - Only works for own events

Sharing

- Tags: e for reposted event, p for original author - May include original event in content

Reactions

- Content: "+" or emoji - Tags: e for reacted event, p for author

Channel Events (40-49)

Regular Events (1000-9999)

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

- Tags: url, MIME type, hash, size, dimensions

Replaceable Events (10000-19999)

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

- Critical for routing - Tags: r with relay URLs and read/write markers

Ephemeral Events (20000-29999)

Not stored by relays, only forwarded once.

Parameterized Replaceable Events (30000-39999)

Replaced based on d tag value.

Lists (30000-30009)

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

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

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

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

Long-form Content (30023)

- d tag: article identifier (slug) - Tags: title, summary, published_at, image - Content: Markdown

Application Data (30078)

- d tag: app-name:data-key - Content: app-specific data (may be encrypted)

Other Parameterized Replaceables

- Declares app can handle certain event kinds

- User's preferred apps for event kinds

Special Event Kinds

Authentication & Signing

Lightning & Payments

- Not published to regular relays - Sent to LNURL provider

- Published by LNURL provider - Proves zap was paid

Content & Annotations

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

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

Badges & Reputation

- Tags: a for badge definition, p for recipient

Generic Events

- More flexible than kind 6

- Tags: URL, method

Event Kind Ranges Summary

RangeTypeBehaviorExamples
0-999CoreVariesMetadata, notes, reactions
1000-9999RegularImmutable, all keptFile metadata
10000-19999ReplaceableOnly latest keptMute list, relay list
20000-29999EphemeralNot storedTyping, presence
30000-39999Parameterized ReplaceableReplaced by d tagArticles, 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:

Event Kind Selection Guide

Choose based on lifecycle needs:

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

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

- Typing indicators - Online presence - Temporary notifications

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

References