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)
```json
{
  "kind": 0,
  "content": "{\"name\":\"Alice\",\"about\":\"Nostr user\",\"picture\":\"https://...\",\"nip05\":\"alice@example.com\"}",
  "tags": []
}
```

### Text Note (Kind 1)
```json
{
  "kind": 1,
  "content": "Hello Nostr!",
  "tags": [
    ["t", "nostr"],
    ["t", "hello"]
  ]
}
```

### Reply (Kind 1 with thread tags)
```json
{
  "kind": 1,
  "content": "Great post!",
  "tags": [
    ["e", "<root-event-id>", "<relay>", "root"],
    ["e", "<parent-event-id>", "<relay>", "reply"],
    ["p", "<author-pubkey>"]
  ]
}
```

### Reaction (Kind 7)
```json
{
  "kind": 7,
  "content": "+",
  "tags": [
    ["e", "<reacted-event-id>"],
    ["p", "<event-author-pubkey>"],
    ["k", "1"]
  ]
}
```

### Long-form Article (Kind 30023)
```json
{
  "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)
```json
{
  "kind": 10002,
  "content": "",
  "tags": [
    ["r", "wss://relay1.com"],
    ["r", "wss://relay2.com", "write"],
    ["r", "wss://relay3.com", "read"]
  ]
}
```

### Zap Request (Kind 9734)
```json
{
  "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)
```json
{
  "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)
```json
{
  "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