nostr-java

nostr-java is a Java SDK for the Nostr protocol. It provides utilities for creating, signing and publishing Nostr events to relays.

Requirements

• Maven
• Java 21+

See docs/GETTING_STARTED.md for installation and usage instructions.

Documentation

• Docs index: docs/README.md — quick entry point to all guides and references.
• Getting started: docs/GETTING_STARTED.md — install via Maven/Gradle and build from source.
• API how‑to: docs/howto/use-nostr-java-api.md — create, sign, and publish basic events.
• Streaming subscriptions: docs/howto/streaming-subscriptions.md — open and manage long‑lived, non‑blocking subscriptions.
• Custom events how‑to: docs/howto/custom-events.md — define, sign, and send custom event types.
• API reference: docs/reference/nostr-java-api.md — classes, key methods, and short examples.
• Extending events: docs/explanation/extending-events.md — guidance for extending the event model.
• Codebase overview and contributing: docs/CODEBASE_OVERVIEW.md — layout, testing, and contribution workflow.

Examples

Examples are located in the nostr-java-examples module. See the API Examples Guide for detailed walkthroughs.

Key Examples

• NostrApiExamples – Comprehensive examples covering 13+ use cases including text notes, encrypted DMs, reactions, channels, and more. See the guide for details.

• SpringSubscriptionExample – Shows how to open a non-blocking NostrSpringWebSocketClient subscription and close it after a fixed duration.

Supported NIPs

The API currently implements the following NIPs:

• NIP-1 - Basic protocol flow description
• NIP-2 - Follow List
• NIP-3 - OpenTimestamps Attestations for Events
• NIP-4 - Encrypted Direct Message
• NIP-5 - Mapping Nostr keys to DNS-based internet identifiers
• NIP-8 - Handling Mentions
• NIP-9 - Event Deletion Request
• NIP-12 - Generic Tag Queries
• NIP-14 - Subject tag in Text events
• NIP-15 - Nostr Marketplace
• NIP-20 - Command Results
• NIP-23 - Long-form Content
• NIP-25 - Reactions
• NIP-28 - Public Chat
• NIP-30 - Custom Emoji
• NIP-32 - Labeling
• NIP-40 - Expiration Timestamp
• NIP-42 - Authentication of clients to relays
• NIP-44 - Encrypted Payloads (Versioned)
• NIP-46 - Nostr Remote Signing
• NIP-57 - Lightning Zaps
• NIP-60 - Cashu Wallets
• NIP-61 - Nutzaps
• NIP-99 - Classified Listings