Creating a badge on Nostr means minting a piece of verifiable recognition that lives across the protocol. Whether you're celebrating contributors to your project, endorsing creators you admire, or building reputation systems for your community, badges give you a decentralized way to say someone matters.
This guide walks you through the concept and mechanics of Nostr badge creation. We don't host a wallet or badge editor on this page, but we'll show you exactly what goes into making badges that work across clients and carry real meaning.
Define Your Badge's Purpose
Start with intent. What behavior, achievement, or identity does this badge recognize? The best badges have clear criteria. A "Top Contributor 2024" badge for your open source project tells a story. A "Verified Artist" badge signals authenticity. A "Conference Attendee" badge becomes a digital memento.
Think about scarcity and value. Will you award this badge to three people or three hundred? Badges gain meaning from context. A badge awarded sparingly carries different weight than one distributed widely, and both have their place.
Choose a Name and Identifier
Every badge needs a human-readable name and a unique identifier. The name is what people see: keep it clear and memorable. The identifier is a technical string that distinguishes your badge from every other badge on Nostr, typically formatted as a reverse domain notation or unique code.
Your identifier might look like com.yourproject.contributor or event-badge-2024-abc. Once you publish a badge definition with an identifier, that combination of your public key and identifier becomes the canonical reference. Choose carefully, because changing it later means creating an entirely new badge.
Design Badge Artwork and Description
Badges are visual. Your artwork shows up in profiles, feeds, and badge collections across Nostr clients. Most badges use a square image, often with transparency, optimized for display at small sizes. Simple, bold designs work best.
Host your image somewhere reliable and reference it by URL in your badge definition. The description field gives you space to explain what the badge represents, why it matters, and what someone did to earn it. Write for both the recipient showing it off and the viewer seeing it for the first time.
Publish the Badge Definition
A badge definition is a specific Nostr event type that announces your badge to the network. It contains your badge identifier, name, description, image URL, and optional metadata like colors or categories. You publish this event once, signed with your private key, and it propagates across relays.
The definition establishes you as the badge issuer. Only events signed by your key can award this specific badge. That's how Nostr badges maintain integrity: anyone can verify that an award came from the legitimate issuer, not an impersonator.
Publishing happens through a Nostr client that supports badge creation, or through direct API interaction with relays if you're building custom tooling. Once your definition event is broadcast and picked up by relays, your badge exists and is discoverable.
Issue Awards to Recipients
Awarding a badge means publishing another Nostr event that references both your badge definition and the recipient's public key. This award event is your signed attestation that this person earned this badge. You can include a custom note explaining why they received it or acknowledging a specific contribution.
Awards are public by default. When you award a badge, you're making a statement to the network. That transparency is the point: badges are social proof, verifiable endorsements that anyone can inspect.
The technical flow looks like this:
- You create an award event containing the badge identifier and recipient's pubkey
- You sign it with your private key, proving you're the authorized issuer
- You broadcast it to relays where it becomes part of the permanent record
- Nostr clients can query for all awards of your badge, or all badges awarded to a specific person
Recipient Acceptance
Here's a crucial detail: recipients control what appears in their profile. Just because you award someone a badge doesn't mean it automatically shows up on their profile. The recipient publishes their own event listing which badges they choose to display. This preserves agency. Someone might earn fifty badges but showcase only the five that matter most to them, or decline to display badges entirely.
When you award a badge, you're offering recognition. Acceptance and display is the recipient's choice. Most Nostr clients provide UI for managing badge visibility, letting users curate how they present themselves.
Privacy and Signing Security
Your private key is your badge authority. Anyone with access to it can issue awards as you, which means they can dilute or misuse your badges. Protect your key with the same care you'd protect any signing credential. Consider using key management tools or hardware signers, especially if you're issuing badges at scale.
Badge data itself is public: definitions, awards, and recipient acceptance all live on open relays. Don't put sensitive information in badge descriptions or award notes. The system is built for transparency and verification, not confidentiality.
Some issuers rotate keys or use dedicated keypairs for badge programs, keeping their primary identity separate. Others issue badges from well-known project accounts to maximize trust and recognition. Your security model depends on your use case and risk tolerance.
Remember that Nostr events are designed to be permanent and widely replicated. Once you publish a badge definition or award, consider it part of the public record. There's no central authority to petition for deletion. That immutability is a feature for building lasting reputation systems, but it requires thoughtful issuance.