Nostr Agent Onboarding · start here · index · 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 §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:

# 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 <KIND> -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 <KIND> -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. 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:

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

For anything not on this list: do Step 2.