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.

For a quick API walkthrough, see docs/howto/use-nostr-java-api.md.

See docs/CODEBASE_OVERVIEW.md for details about running tests and contributing.

Examples

Examples are located in the nostr-java-examples module.

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

Streaming subscriptions

The client and API layers expose a non-blocking streaming API for long-lived subscriptions. Use NostrSpringWebSocketClient.subscribe to open a REQ subscription and receive relay messages via a callback:

Filters filters = new Filters(new KindFilter<>(Kind.TEXT_NOTE));
AutoCloseable subscription =
    client.subscribe(
        filters,
        "example-subscription",
        message -> {
          // handle EVENT/NOTICE payloads on your own executor to avoid blocking the socket thread
        },
        error -> log.warn("Subscription error", error));

// ... keep the subscription open while processing events ...

subscription.close(); // sends CLOSE to the relay and releases the underlying WebSocket

Subscriptions must be closed by the caller to ensure a CLOSE frame is sent to the relay and to free the dedicated WebSocket connection created for the REQ. Callbacks run on the WebSocket thread; for high-throughput feeds, hand off work to a queue or executor to provide backpressure and keep the socket responsive.

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