Nostr4j

A Java library for Nostr apps on desktop, mobile and the web.

  • Linux
  • Windows
  • Mac
  • Android
  • iOS
  • Browser
NGEPlatform.set(new JVMAsyncPlatform());

NostrKeyPair keys = new NostrKeyPair();
NostrPool pool = new NostrPool();
NostrSubscription subscription = null;
try {
    pool.ensureRelay("wss://relay.ngengine.org").await();

    NostrFilter filter = new NostrFilter();
    filter.withKind(1);
    filter.withAuthor(keys.getPublicKey());

    subscription = pool.subscribe(filter);
    subscription.addEventListener((sub, event, stored) -> {
        System.out.println("Received: " + event.getContent());
    });
    AsyncTask.awaitAll(subscription.open());

    UnsignedNostrEvent draft = new UnsignedNostrEvent();
    draft.withKind(1);
    draft.withContent("Hello from Nostr4j!");

    NostrKeyPairSigner signer = new NostrKeyPairSigner(keys);
    SignedNostrEvent note = signer.sign(draft).await();
    pool.publish(note).await();
    System.out.println("Published: " + note.getId());

    // Keep this standalone program alive briefly to receive the note.
    Thread.sleep(5_000);
} finally {
    if (subscription != null) subscription.close();
    pool.close();
    keys.close();
}

Managed lifecycle

Connect to several relays through one pool. If a connection drops, the pool reconnects and reopens your subscriptions.

Explore relay APIs →

Efficient and secure by design

Built from the ground up for efficient memory and resource use, with safeguards against common pitfalls and security vulnerabilities.

Explore overview →

Asynchronous

Network APIs use AsyncTask, with execution tailored to each platform and virtual threads on the JVM. A stream adapter is also available for blocking Java I/O.

Explore async operations →

Everything you need

Work with events, profiles and media, sign locally or through browser and remote signers, and connect Lightning wallets with NWC or WebLN.

Browse protocol support →

p2p encrypted connections

Nostr4j implements an encrypted RTC protocol using Nostr for peer discovery and signaling. Automatic fallback through peer routes and optional TURN helps keep apps connected as network conditions change.

Explore RTC over Nostr →

Multi-Hop Routing

Nostr4j handles multi-hop routing automatically, finding paths through connected peers and forwarding encrypted messages. Send to the recipient; no routing logic is needed in your app.

See multi-hop routing →

Start with a working example, then follow the guides for your app.

Browse documentation →

Add it to a project

See platform setup for dependencies and initialization details.

Linux, Windows and macOS use the same Java 21+ dependencies.

repositories {
    mavenCentral()
    maven { url = uri('https://central.sonatype.com/repository/maven-snapshots') }
}

dependencies {
    implementation 'org.ngengine:nostr4j:0.4.1'
    implementation 'org.ngengine:nge-platform-jvm:0.3.0-SNAPSHOT'
}

import org.ngengine.platform.NGEPlatform;
import org.ngengine.platform.jvm.JVMAsyncPlatform;

NGEPlatform.set(new JVMAsyncPlatform());