> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `nostr-dev/docs/kind-cheatsheet.md` · snapshot 2026-10-10 > > Paths such as `~/Documents/…`, `~/Production Environment/…`, `repos/…` and services on `localhost` refer to the author's workstation and are **not available to you** — read them as worked examples of a setup you can recreate. # Picking a Nostr event kind — 30-second cheatsheet > Companion to [`docs/design-synthesis.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/design-synthesis.md) §3–4. When you need to ship. ## Step 0 — Default Use **regular** (kind in `1–2`, `4–44`, `1000–9999`, or `40000+`) unless you have a written reason not to. ## Step 1 — Class ``` one-current-value-per-user? / \ yes no | | keyed by a d-tag? ephemeral signal? / \ / \ yes no yes no | | | | ADDRESSABLE REPLACEABLE EPHEMERAL REGULAR ← default 30000-39999 10000-19999 20000-29999 1-9999, 40000+ ``` ## Step 2 — Existing kind? Use it. Before allocating, do all four checks: ```bash # 1. Search the canonical registry. $EDITOR ~/Documents/nostr-dev/docs/sources/nips-readme-kinds.md # or upstream: https://github.com/nostr-protocol/nips/blob/master/README.md # 2. Ask NAK what NIPs it knows. nak nip # list nak nip 34 # show one nak nip open 34 # open in browser # 3. Probe the live network for events of that kind. # Even undocumented kinds may be in use by clients. # Real-world example: kind 37195 is FIPS overlay-discovery adverts (the # digits spell "FIPS" — 7=F, 1=I, 9=P, 5=S). Not in the canonical # NIPs registry, but live on relay.damus.io and nos.lol. Anyone who # allocated 37195 without probing would have collided with FIPS. nak req -k -l 3 wss://relay.damus.io wss://nos.lol wss://relay.primal.net # 4. Probe with a tag filter to see realistic schemas. nak req -k -l 5 wss://relay.primal.net | jq -c '{kind,tags}' ``` If anyone is using it, your options are: (a) match their schema, (b) pick a different number, (c) propose a NIP that consolidates. ## Step 3 — If you must invent - Pick a number in a *gap* of the appropriate class. The README registry has many. - Document it in your repo with: kind, class (regular/replaceable/ephemeral/ addressable), tag schema, content shape, *why* you chose this class. - For anything you want other clients to interoperate with, open a PR against [`nostr-protocol/nips`](https://github.com/nostr-protocol/nips). The community process is informal but real. ## Step 4 — Tag conventions matter as much as kinds The kind says "what shape." The tags say "what data." Reuse before you invent: | Tag | Meaning | |---|---| | `e` | reference to another event id | | `p` | reference to a pubkey | | `a` | reference to an addressable event (`::`) | | `d` | identifier for an addressable event | | `t` | hashtag / topic | | `r` | URL or relay reference | | `k` | kind (used in NIP-22 comments to point at parent kind) | | `client` | client name + version | | `alt` | accessibility / fallback rendering | | `expiration` | unix timestamp after which the event should be considered expired | | `subject` | thread title (NIP-14) | If your data is "a reference to a thing + an annotation," it's almost always **existing tag + new content**, not new kind. ## Common smells (recap from the synthesis) - A "settings" event that's *regular* and accumulates → should be **replaceable**. - A "current location" event that's *regular* → should probably be **ephemeral**. - A "blog post" that's *regular* and edited → should be **addressable**. - A "comment" that's *addressable* so it can be edited → almost certainly wrong; comments are accountable, use **regular** and tombstone with NIP-09. - A "draft" that's *regular* → should be **addressable** (one current draft per user-defined identifier). ## Quick reference — well-known kinds you'll meet | Kind | What | Class | NIP | |---|---|---|---| | 0 | User metadata (profile) | replaceable | 1 | | 1 | Short text note | regular | 1 | | 3 | Follow list (contact list) | replaceable | 2 | | 4 | Encrypted DM (legacy, deprecated for NIP-17) | regular | 4 | | 5 | Event deletion request | regular | 9 | | 6 | Repost | regular | 18 | | 7 | Reaction | regular | 25 | | 9 | Chat message | regular | 28 | | 16 | Generic repost (non-kind-1) | regular | 18 | | 1059 | Gift wrap (privacy envelope) | regular | 59 | | 1063 | File metadata | regular | 94 | | 5128 | **nsite manifest snapshot** | regular | 5A | | 1311 | Live chat message | regular | 53 | | 1617 | Patch (git) | regular | 34 | | 1621 | Issue (git) | regular | 34 | | 1622 | Reply (git issue / PR) | regular | 34 | | 1630–1633 | Status (git, open/closed/merged/draft) | regular | 34 | | 9734/9735 | Zap request / receipt | regular | 57 | | 10000 | Mute list | replaceable | 51 | | 10002 | **Relay list (outbox/inbox)** | replaceable | 65 | | 10006 | Pinned events | replaceable | 51 | | 10019 | **Nutzap mint list** | replaceable | 61 | | 10063 | **Blossom server list** (user's media servers) | replaceable | BUD-03 | | 15128 | **Root nsite manifest** (static site; MUST NOT carry `d`) | replaceable | 5A | | 17375 | Cashu wallet | replaceable | 60 | | 22242 | Auth (NIP-42 client auth challenge) | ephemeral | 42 | | 24133 | NIP-46 connect (Nostr Connect / bunker) | ephemeral | 46 | | 27235 | HTTP auth (NIP-98) | ephemeral | 98 | | 30000 | Follow set | addressable | 51 | | 30002 | Relay set | addressable | 51 | | 30008 | Profile badge | addressable | 58 | | 30009 | Badge definition | addressable | 58 | | 30023 | Long-form article | addressable | 23 | | 30024 | Long-form draft | addressable | 23 | | 30311 | Live event | addressable | 53 | | 30402 | Classified listing | addressable | 99 | | 30617 | **Git repository announcement** | addressable | 34 | | 30618 | Git repository state | addressable | 34 | | 31922 | Date-based calendar event | addressable | 52 | | 34128 | ~~Legacy nsite per-path event~~ — **deprecated, relays refuse it** | addressable | 5A | | 35128 | **Named nsite manifest** (`d` = `^[a-z0-9-]{1,13}$`) | addressable | 5A | | 31923 | Time-based calendar event | addressable | 52 | | 32267 | **Software application** (Zapstore app metadata, `d` = package id) | addressable | 82 (PR) | | 30063 | **Software release set** (Zapstore, `d` = `@`) | addressable | 82 (PR) | | 3063 | **Software asset** (Zapstore per-binary file metadata; *not* NIP-94's 1063) | regular | 82 (PR) | | 30509 | **Cryptographic identity link** (NIP-C1, `d` = cert SHA-256) — binds an APK signing key to a Nostr identity | addressable | C1 | | 39000–39009 | Group metadata (NIP-29) | addressable | 29 | For anything not on this list: do Step 2.