Badges

1 Overview

A badge is a small honor that one user gives to another. An issuer may award badges in recognition, in gratitude, for participation, or in appreciation of a goal, task, or cause. An awardee may decorate their profile with badges from issuers they deem reputable, for fame, notoriety, recognition, or support.

This NIP defines four special event kinds. A Badge Definition (kind 30009) describes a badge. A Badge Award (kind 8) gives that badge to one or more pubkeys. A Profile Badges event (kind 10008) lists the badges a user accepts and the order to display them. A Badge Set (kind 30008) groups accepted badges under a label.

Awards are one-way. An awarded badge is immutable and non-transferable. Only the awardee decides whether it appears on their profile.

2 Badge Definition (kind 30009)

A Badge Definition is an addressable event (NIP-01) with kind 30009, published by the badge issuer. Its d tag value uniquely identifies the badge, for example bravery. The issuer can update the definition later: relays keep only the latest event per issuer and d value.

One tag is required. The rest are optional:

{
  "pubkey": <issuer pubkey, "alice">,
  "kind": 30009,
  "tags": [
    ["d", "bravery"],
    ["name", "Medal of Bravery"],
    ["description", "Awarded to users demonstrating bravery"],
    ["image", "https://nostr.academy/awards/bravery.png", "1024x1024"],
    ["thumb", "https://nostr.academy/awards/bravery_256x256.png", "256x256"]
  ]
  // other fields...
}

3 Badge Award (kind 8)

A Badge Award is a regular event with kind 8, published by the issuer. It hands the badge to one or more pubkeys. Awarded badges are immutable and non-transferable.

{
  "id": <badge award event id>,
  "kind": 8,
  "pubkey": <issuer pubkey, "alice">,
  "tags": [
    ["a", "30009:alice:bravery"],
    ["p", "bob", "wss://relay"],
    ["p", "charlie", "wss://relay"]
  ]
  // other fields...
}

4 Profile Badges (kind 10008)

The number of badges a pubkey can be awarded is unbounded. The Profile Badges event lets a user accept or reject awarded badges. It also sets the display order of badges on the profile.

A Profile Badges event is a replaceable event with kind 10008, defined as a NIP-51 standard list. All tags are optional:

• Zero or more ordered, consecutive pairs of a and e tags. Each pair references a kind 30009 Badge Definition and a kind 8 Badge Award, in that order.
• Clients SHOULD ignore an a tag without a matching e tag, and an e tag without a matching a tag.
• The Badge Award referenced by each e tag should contain the same a tag as its pair.
• The event may also contain a tags that reference Badge Set events (see §5).

5 Badge Sets (kind 30008)

A Badge Set is an addressable event with kind 30008, defined as a NIP-51 set. Badge Sets let a user categorize accepted badges into labeled groups. Like the Profile Badges event, a Badge Set contains ordered pairs of a and e tags. Each pair references a Badge Definition and a Badge Award for one badge in the set. A Profile Badges event may reference Badge Sets with a tags.

6 Recommendations

Clients MAY whitelist badge issuer pubkeys. This keeps badges valuable and special for their users.

The recommended badge image aspect ratio is 1:1, with a high-resolution size of 1024x1024 pixels. Recommended thumbnail dimensions are:

Rendering rules for clients:

• Clients MAY render fewer badges than the user lists in the Profile Badges event.
• Clients MAY replace the badge image and thumbnails with ones that fit the client's theme.
• Clients SHOULD pick the most appropriate thumbnail for the number of badges shown and the space available.
• Clients SHOULD render the high-resolution image on user action: click, tap, or hover.

7 Worked Example

Alice issues the bravery badge and awards it to Bob and Charlie. Bob accepts it, next to an earlier honor badge, and files both into a set. Orange lines go to the relay. Blue lines come from the relay.

-- Alice (issuer) publishes the definition, then the award --
→ ["EVENT", {"kind":30009,"pubkey":"a11ce…","tags":[["d","bravery"],
     ["name","Medal of Bravery"],["description","Awarded to users demonstrating bravery"],
     ["image","https://nostr.academy/awards/bravery.png","1024x1024"],
     ["thumb","https://nostr.academy/awards/bravery_256x256.png","256x256"]], …}]
← ["OK", "c0ffee11…", true, ""]
→ ["EVENT", {"kind":8,"pubkey":"a11ce…","tags":[["a","30009:a11ce…:bravery"],
     ["p","b0b…","wss://relay"],["p","c4a121e…","wss://relay"]], …}]
← ["OK", "aa4a5d01…", true, ""]

-- Bob's client looks for awards to Bob --
→ ["REQ", "hon", {"kinds":[8], "#p":["b0b…"]}]
← ["EVENT", "hon", {"kind":8, "id":"aa4a5d01…", "tags":[["a","30009:a11ce…:bravery"], …], …}]
← ["EOSE", "hon"]

-- Bob accepts: Profile Badges, ordered a/e pairs --
→ ["EVENT", {"kind":10008,"pubkey":"b0b…","tags":[
     ["a","30009:a11ce…:bravery"],["e","aa4a5d01…","wss://nostr.academy"],
     ["a","30009:a11ce…:honor"],["e","77e1de40…","wss://nostr.academy"]], …}]
← ["OK", "b1adge55…", true, ""]

-- Bob also groups them into a Badge Set --
→ ["EVENT", {"kind":30008,"pubkey":"b0b…","tags":[["d","virtues"],
     ["a","30009:a11ce…:bravery"],["e","aa4a5d01…","wss://nostr.academy"],
     ["a","30009:a11ce…:honor"],["e","77e1de40…","wss://nostr.academy"]], …}]
← ["OK", "5e7c0de1…", true, ""]

A viewer's client now fetches Bob's kind 10008 event, resolves each a/e pair, checks that the award's a tag matches, and renders the thumb that fits the layout.

8 Version History

NIP-58 arrived in early 2023 and kept its shape for three years. The one big change moved Profile Badges to a new kind. Notable changes, newest first:

• 20262026-04Profile Badges moved from kind 30008 (d = profile_badges) to replaceable kind 10008. Kind 30008 was redefined as the Badge Set event for categorizing badges.
• 20242024-08Terminology updated: "parameterized replaceable event" became "addressable event", following the NIP-01 rename.
• 20232023-12Removed the section on proof-of-work (NIP-13) as an anti-spam signal for badges.
• 20232023-11Author lists removed from all NIPs, this one included.
• 2023+2023-2026Typo fixes, JSON formatting, and example cleanups.
• Origin2023-02Ricardo Arturo Cabral Mejía added the badge events and profile badges spec in PR #229.

9 See Also

• NIP-01 — the base protocol: events, tags, replaceable and addressable storage classes.
• NIP-51 — lists and sets; Profile Badges is a standard list, Badge Set is a set.
• NIP-13 — proof of work; an earlier draft suggested it as a badge anti-spam signal.
• NIP-19 — bech32 encodings for sharing badge event pointers.
• NIP-25 — reactions; a lighter-weight way to show appreciation than a badge.