SDK Reference
Build Nostr apps with data fetchers, relay utilities, login UI, and optional follow-graph distance queries.
Published packages
Versions verified on npm on 20 September 2026. The meta-package exposes WoT at its root and other modules through subpaths. You can also install scoped packages directly; @nostr-wot/pq is a separate package.
| Package | 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 setup
NostrSdkProvider composes data configuration, session state, and optional WoT context. Supply myPubkey explicitly for Oracle queries; signing in does not set the WoT query root automatically.
"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 compatibility
Published @nostr-wot/wot 1.0.0 uses the older /api/distance/FROM/TO?maxHops= contract and expects a distance field. Oracle 0.3.0 uses /distance?from=&to=&max_hops= and returns hops. Changing the base URL alone does not make them compatible. Use direct fetch for Oracle 0.3.0, or the local graph source shown below.
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;
}Data layer
Standalone fetchers retrieve profiles, notes, threads, follows, and engagement. React hooks add a cache with stale-while-revalidate behavior. Data fetchers share their own connection pool.
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 management
RelayPool wraps a compatible PoolLike transport supplied by your app. Configure urls, use subscribe with onEvent/onEose, and close subscriptions when finished. A separately created relay wrapper is not automatically connected to the data provider.
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();
};
}Login UI
LoginButton and useSession share the session provided by NostrSdkProvider. Supported methods include NIP-07, NIP-46, key generation, and key import. Install the UI package directly when importing its components and styles.
"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>;
}Web of Trust distances
WoT queries the Oracle by default. getDistance returns a number or null; isInMyWoT returns a boolean. getDetails provides hops, a numeric path count, and optional bridges and mutual-follow information. Pass valid 64-character hexadecimal public keys.
Migrating to @nostr-wot/wot 1.0.0
Version 1.0.0 removed browser-extension detection, trust-score methods, and useTrustScore. Use useWoT or useIsInWoT and read their result objects. For local queries, pass a WoTLocalSource, such as WotGraph.asWoTSource() from @nostr-wot/graph. Only getDistance, isInMyWoT, and filterByWoT use that source; other methods still query the Oracle.
Local graph example
Load and crawl a local graph before passing its source to WoT. The React example receives this prepared graph and uses useIsInWoT; useWoT also requests getDetails from the Oracle. @nostr-wot/graph has its own getScore API, separate from the removed 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>
);
}