SDK-Referenz
Erstelle Nostr-Apps mit Datenabfragen, Relay-Werkzeugen, einer Anmeldeoberfläche und optionalen Distanzabfragen im Follow-Graphen.
Veröffentlichte Pakete
Versionen am 20. September 2026 auf npm geprüft. Das Metapaket exportiert WoT über seinen Haupteinstieg und andere Module über Unterpfade. Pakete mit Namensraum lassen sich auch direkt installieren; @nostr-wot/pq ist ein separates Paket.
| Paket | Version |
|---|---|
nostr-wot-sdk | 1.0.1 |
@nostr-wot/data | 0.5.1 |
@nostr-wot/relay | 0.1.1 |
@nostr-wot/signers | 1.2.0 |
@nostr-wot/blossom | 0.1.7 |
@nostr-wot/dm | 0.6.2 |
@nostr-wot/wallet | 0.3.4 |
@nostr-wot/wot | 1.0.0 |
@nostr-wot/graph | 0.2.0 |
@nostr-wot/ui | 0.7.1 |
@nostr-wot/auth | 3.0.0 |
@nostr-wot/pq | 0.2.2 |
Installation
Provider einrichten
NostrSdkProvider kombiniert Datenkonfiguration, Sitzungsstatus und optionalen WoT-Kontext. Gib myPubkey für Oracle-Abfragen ausdrücklich an; die Anmeldung setzt den Ausgangspunkt für WoT-Abfragen nicht automatisch.
"use client";
import type { ReactNode } from "react";
import { NostrSdkProvider } from "nostr-wot-sdk/react";
export function Providers({ children }: { children: ReactNode }) {
return (
<NostrSdkProvider
relays={["wss://relay.damus.io", "wss://nos.lol"]}
profileAggregators={["wss://purplepag.es"]}
>
{children}
</NostrSdkProvider>
);
}Oracle-Kompatibilität
Die veröffentlichte Version @nostr-wot/wot 1.0.0 nutzt den älteren Vertrag /api/distance/FROM/TO?maxHops= und erwartet das Feld distance. Oracle 0.3.0 nutzt /distance?from=&to=&max_hops= und liefert hops. Eine andere Basis-URL allein macht die Versionen nicht kompatibel. Nutze fetch direkt für Oracle 0.3.0 oder die unten gezeigte lokale Graphquelle.
async function oracleDistance(from: string, to: string) {
const query = new URLSearchParams({ from, to, max_hops: "2" });
const response = await fetch(
"https://wot-oracle.mappingbitcoin.com/distance?" + query,
);
if (!response.ok) throw new Error("Oracle HTTP " + response.status);
const result = await response.json();
return result.hops as number | null;
}Datenschicht
Eigenständige Funktionen laden Profile, Notizen, Threads, Follows und Interaktionen. React-Hooks ergänzen einen Cache, der gespeicherte Daten während der Aktualisierung zurückgibt. Die Datenfunktionen teilen einen eigenen Verbindungspool.
import {
fetchProfile, fetchNotesByAuthor, fetchEngagement, setDefaultRelays,
} from "@nostr-wot/data";
setDefaultRelays(["wss://relay.damus.io", "wss://nos.lol"]);
async function loadAuthor(pubkey: string) {
const profile = await fetchProfile(pubkey);
const notes = await fetchNotesByAuthor(pubkey, { limit: 50 });
const engagement = await fetchEngagement(notes.map(note => note.id));
return { profile, notes, engagement };
}"use client";
import { useProfile } from "@nostr-wot/data/react";
function ProfileCard({ pubkey }: { pubkey: string }) {
const profile = useProfile(pubkey);
if (!profile) return null;
return <h1>{profile.displayName ?? profile.name ?? pubkey}</h1>;
}Relay-Verwaltung
RelayPool umschließt einen kompatiblen PoolLike-Transport deiner App. Konfiguriere urls, verwende subscribe mit onEvent/onEose und schließe Abonnements nach Gebrauch. Ein separat erstellter Relay-Wrapper wird nicht automatisch mit dem Datenprovider verbunden.
import { RelayPool, type PoolLike, type NostrEvent } from "@nostr-wot/relay";
function watchNotes(transport: PoolLike, onEvent: (event: NostrEvent) => void) {
const pool = new RelayPool({
urls: ["wss://relay.damus.io", "wss://nos.lol"],
pool: transport,
});
const sub = pool.subscribe({ kinds: [1], limit: 50 }, { onEvent });
return () => {
sub.close();
pool.destroy();
};
}Anmeldeoberfläche
LoginButton und useSession teilen die Sitzung von NostrSdkProvider. Unterstützt werden NIP-07, NIP-46 sowie das Erstellen und Importieren von Schlüsseln. Installiere das UI-Paket direkt, wenn du seine Komponenten und Stile importierst.
"use client";
import { LoginButton, useSession } from "@nostr-wot/ui";
import { NostrSdkProvider } from "nostr-wot-sdk/react";
import "@nostr-wot/ui/styles.css";
function Account() {
const { pubkey } = useSession();
return <><LoginButton /><output>{pubkey}</output></>;
}
function App() {
return <NostrSdkProvider><Account /></NostrSdkProvider>;
}Distanzen im Vertrauensnetzwerk
WoT fragt standardmäßig das Oracle ab. getDistance liefert eine Zahl oder null; isInMyWoT liefert einen booleschen Wert. getDetails liefert die Hop-Anzahl, eine numerische Pfadanzahl und optionale Angaben zu Zwischenverbindungen und gegenseitigen Follows. Verwende gültige öffentliche Schlüssel mit 64 Hexadezimalzeichen.
Migration auf @nostr-wot/wot 1.0.0
Version 1.0.0 entfernte die Erweiterungserkennung, Methoden für Vertrauenswerte und useTrustScore. Verwende useWoT oder useIsInWoT und lies deren Ergebnisobjekte aus. Für lokale Abfragen übergib eine WoTLocalSource, etwa WotGraph.asWoTSource() aus @nostr-wot/graph. Nur getDistance, isInMyWoT und filterByWoT nutzen diese Quelle; andere Methoden fragen weiterhin das Oracle ab.
Beispiel mit lokalem Graphen
Lade und erfasse einen lokalen Graphen, bevor du seine Quelle an WoT übergibst. Das React-Beispiel erhält diesen vorbereiteten Graphen und nutzt useIsInWoT; useWoT fragt zusätzlich getDetails beim Oracle ab. @nostr-wot/graph hat eine eigene getScore-API, getrennt von der entfernten WoT-Score-API.
import { WotGraph } from "@nostr-wot/graph";
import { WoT } from "@nostr-wot/wot";
async function prepareGraph(myPubkey: string, targetPubkey: string) {
const graph = new WotGraph({
namespace: "my-app",
relays: ["wss://relay.damus.io", "wss://nos.lol"],
});
await graph.load();
await graph.crawl(myPubkey, { maxDepth: 2 });
const wot = new WoT({ source: graph.asWoTSource(), maxHops: 2 });
const distance = await wot.getDistance(targetPubkey);
const inWoT = await wot.isInMyWoT(targetPubkey);
return { graph, distance, inWoT };
}"use client";
import type { WotGraph } from "@nostr-wot/graph";
import { NostrSdkProvider, useIsInWoT } from "nostr-wot-sdk/react";
function FollowBadge({ pubkey }: { pubkey: string }) {
const { inWoT, loading, error } = useIsInWoT(pubkey, { maxHops: 2 });
if (loading || error || !inWoT) return null;
return <span>{pubkey}</span>;
}
function LocalTrust({ graph, pubkey }: { graph: WotGraph; pubkey: string }) {
return (
<NostrSdkProvider wot={{ enabled: true, options: { source: graph.asWoTSource() } }}>
<FollowBadge pubkey={pubkey} />
</NostrSdkProvider>
);
}