Nostr WoT

Documentación

Todo lo que necesitas para integrar Web of Trust en tu aplicación.

SDK Reference

nostr-wot-sdk is a toolkit for building Nostr apps: a pure-function data/query layer, relay management, headless login UI, and Web of Trust scoring as one optional module — all sharing a single connection pool.

What's in the box

The meta-package nostr-wot-sdk pulls in the scoped @nostr-wot/* family and re-exports it, plus a unified React provider. Reach for the individual packages when you only need part of the stack.

PackageWhat it does
@nostr-wot/dataPure-function data layer — profiles, notes, threads, engagement, NIP-65 outbox. Optional SWR cache + React hooks.
@nostr-wot/relayRelay management — pool, query batcher, per-relay stats.
@nostr-wot/uiHeadless React UI — login modal/widget, session provider, themable via CSS variables.
@nostr-wot/wotWeb of Trust scoring — one optional module, enabled on the provider.

Installation

terminal
$npm install nostr-wot-sdk

Provider Setup

Wrap your app in <NostrSdkProvider>. It composes the data layer, the session context, and (opt-in) Web of Trust — all over one shared pool of relay connections.

tsx
import { NostrSdkProvider } from "nostr-wot-sdk/react";

function App() {
  return (
    <NostrSdkProvider
      relays={["wss://relay.damus.io", "wss://nos.lol"]}
      profileAggregators={["wss://purplepag.es"]}
      wot={{ enabled: true, options: { maxHops: 2 } }}
    >
      <MyApp />
    </NostrSdkProvider>
  );
}

Data Layer

@nostr-wot/data is a pure-function Nostr data layer: profiles, notes, threads, follows, and engagement (reactions / reposts / zaps), with NIP-65 outbox-model relay discovery built in. Fetchers work standalone; the React hooks add an SWR cache.

Vanilla fetchers

typescript
import {
  fetchProfile,
  fetchNote,
  fetchNotesByAuthor,
  fetchThread,
  fetchEngagement,
  setDefaultRelays,
} from "@nostr-wot/data";

setDefaultRelays(["wss://relay.damus.io", "wss://nos.lol"]);

const profile = await fetchProfile("hex-pubkey");
const notes = await fetchNotesByAuthor("hex-pubkey", { limit: 50 });
const engagement = await fetchEngagement(["id1", "id2"]);
// → Map<id, { reactionCount, repostCount, zapTotalSats }>

React hooks

tsx
import { useProfile, useThread, useEngagement } from "@nostr-wot/data/react";

function ProfileCard({ pubkey }: { pubkey: string }) {
  const profile = useProfile(pubkey); // SWR — cached + revalidated
  if (!profile) return <Skeleton />;
  return <h1>{profile.displayName ?? profile.name}</h1>;
}

Relay Management

@nostr-wot/relay provides the low-level relay primitives the data layer builds on — a connection pool with reconnect handling, a query batcher that coalesces concurrent reads, and a per-relay stats tracker.

typescript
import { RelayPool } from "@nostr-wot/relay";

const pool = new RelayPool({
  relays: ["wss://relay.damus.io", "wss://nos.lol"],
});

const sub = pool.subscribeMany(
  pool.relays(),
  [{ kinds: [1], limit: 50 }],
  {
    onevent: (e) => { /* ... */ },
    oneose: () => sub.close(),
  },
);

Headless Login UI

@nostr-wot/ui ships a headless login modal/widget and session provider. It supports NIP-07, NIP-46, generate, and import — and writes to the same session context every other hook reads from, so once the user signs in, the whole SDK has the signer.

tsx
import { LoginButton, useSession } from "@nostr-wot/ui";
import { NostrSdkProvider } from "nostr-wot-sdk/react";
import "@nostr-wot/ui/styles.css";

function App() {
  return (
    <NostrSdkProvider relays={["wss://relay.damus.io"]}>
      <LoginButton />
      <Welcome />
    </NostrSdkProvider>
  );
}

function Welcome() {
  const { pubkey } = useSession();
  return pubkey ? <p>Welcome {pubkey.slice(0, 12)}…</p> : <p>Please sign in</p>;
}

Web of Trust (optional)

Web of Trust is one opt-in module. Enable it on the provider with wot={{ enabled: true }} and the trust hooks light up anywhere in your tree. If the WoT browser extension is installed, queries are answered from its locally-cached follow graph; otherwise the SDK falls back to relay-fetched kind-3 events.

React hooks

tsx
import { useTrustScore, useIsInWoT } from "nostr-wot-sdk/react";

function FollowBadge({ pubkey }: { pubkey: string }) {
  const score = useTrustScore(pubkey);   // 0..1 or null
  const isInWoT = useIsInWoT(pubkey);
  return isInWoT ? <Badge score={score} /> : null;
}

Vanilla API

typescript
import { WoT } from "@nostr-wot/wot";

const wot = new WoT({ rootPubkey: "hex-pubkey", maxHops: 2 });

const result = await wot.getDistance("hex-target-pubkey");
// → { hops: 1, paths: [...], score: 0.87 } | null

const trusted = await wot.isInWoT("hex-target-pubkey"); // boolean

Prefer server-side scoring at scale? Use the WoT Oracle REST API — no user extension, sub-millisecond cached queries.

Extension APIOracle API