Nostr WoT

Documentation

Everything you need to integrate Web of Trust into your application.

Extension API

The WoT Extension injects window.nostr.wot into every page for client-side trust queries.

Prerequisite: Users must have the WoT Extension installed and configured.

Setup

Always check for extension availability before using the API:

javascript
// Feature detection
function hasWoT() {
  return typeof window !== "undefined" &&
         window.nostr?.wot !== undefined;
}

// Wait for extension to load
async function waitForWoT(timeout = 3000) {
  const start = Date.now();
  while (!hasWoT() && Date.now() - start < timeout) {
    await new Promise(r => setTimeout(r, 100));
  }
  return hasWoT();
}

Core Methods

getDistance(targetPubkey)

Returns the number of hops from your pubkey to the target.

Parameters

NameTypeDescription
targetPubkeystringHex or npub format pubkey

Returns

Promise<number | null>

Example

javascript
const distance = await window.nostr.wot.getDistance(
  "3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d"
);

switch (distance) {
  case null: console.log("Not connected"); break;
  case 0: console.log("This is you"); break;
  case 1: console.log("Direct follow"); break;
  default: console.log(`${distance} hops away`);
}

isInMyWoT(targetPubkey, maxHops?)

Boolean check if a pubkey is within your web of trust threshold.

Parameters

NameTypeDefaultDescription
targetPubkeystring-Hex or npub format pubkey
maxHopsnumber3Maximum hops to consider "trusted"

Returns

Promise<boolean>

Example

javascript
// Check with default threshold (3 hops)
const trusted = await window.nostr.wot.isInMyWoT(pubkey);

// Stricter check (2 hops)
const veryTrusted = await window.nostr.wot.isInMyWoT(pubkey, 2);

getDistanceBetween(fromPubkey, toPubkey)

Get the distance between any two pubkeys (not just from you).

Parameters

NameTypeDescription
fromPubkeystringSource pubkey
toPubkeystringTarget pubkey

Returns

Promise<number | null>

Example

javascript
const distance = await window.nostr.wot.getDistanceBetween(
  alicePubkey,
  bobPubkey
);

if (distance === 1) {
  console.log("Alice follows Bob directly");
}

getTrustScore(targetPubkey)

Get a normalized trust score (0-1) based on distance and path count.

Parameters

NameTypeDescription
targetPubkeystringHex or npub format pubkey

Returns

Promise<number | null>

score = distanceWeight + pathBonus

Distance Weights

  • 1 hop: 1.0
  • 2 hops: 0.5
  • 3 hops: 0.25
  • 4+ hops: 0.1

Path Bonuses

  • 2 hops: +0.05 per path
  • 3 hops: +0.02 per path
  • 4+ hops: +0.01 per path
  • Max bonus: 0.25

Example

javascript
const score = await window.nostr.wot.getTrustScore(pubkey);

if (score === null) {
  console.log("Not connected");
} else if (score >= 0.7) {
  console.log("Highly trusted");
} else if (score >= 0.3) {
  console.log("Somewhat trusted");
} else {
  console.log("Low trust score");
}

getDetails(targetPubkey)

Get comprehensive trust information including distance, score, paths, and bridging nodes.

Parameters

NameTypeDescription
targetPubkeystringHex or npub format pubkey

Returns

Promise<TrustDetails | null>

Example

javascript
const details = await window.nostr.wot.getDetails(pubkey);

if (details) {
  console.log(`Distance: ${details.distance} hops`);
  console.log(`Trust score: ${details.score}`);
  console.log(`Connection paths: ${details.paths}`);
  console.log(`Mutual follow: ${details.mutual}`);
  console.log(`Bridging nodes: ${details.bridgingNodes.join(", ")}`);
}

getConfig()

Get the current extension configuration.

Returns

Promise<WoTConfig>

Example

javascript
const config = await window.nostr.wot.getConfig();

console.log(`Mode: ${config.mode}`); // "remote", "local", or "hybrid"
console.log(`Max hops: ${config.maxHops}`);
console.log(`Timeout: ${config.timeout}ms`);

Batch Operations

getDistanceBatch(targets)

Get distances for multiple pubkeys in a single call.

Parameters

NameTypeDescription
targetsstring[]Array of hex pubkeys

Returns

Promise<Record<string, number | null>>

Example

javascript
const distances = await window.nostr.wot.getDistanceBatch([
  "pubkey1...",
  "pubkey2...",
  "pubkey3..."
]);

// { "pubkey1...": 1, "pubkey2...": 2, "pubkey3...": null }

getTrustScoreBatch(targets)

Get trust scores for multiple pubkeys in a single call.

Parameters

NameTypeDescription
targetsstring[]Array of hex pubkeys

Returns

Promise<Record<string, number | null>>

Example

javascript
const scores = await window.nostr.wot.getTrustScoreBatch([
  "pubkey1...",
  "pubkey2...",
  "pubkey3..."
]);

// { "pubkey1...": 0.95, "pubkey2...": 0.45, "pubkey3...": null }

filterByWoT(pubkeys, maxHops?)

Filter a list of pubkeys to only those within the Web of Trust.

Parameters

NameTypeDefaultDescription
pubkeysstring[]-Array of hex pubkeys
maxHopsnumber3Override default max hops

Returns

Promise<string[]>

Example

javascript
const allPubkeys = ["pk1...", "pk2...", "pk3...", "pk4..."];

// Filter to only trusted pubkeys (within 3 hops)
const trusted = await window.nostr.wot.filterByWoT(allPubkeys);

// Stricter filtering (2 hops)
const veryTrusted = await window.nostr.wot.filterByWoT(allPubkeys, 2);

User Info

getMyPubkey()

Returns the configured user's pubkey.

Returns

Promise<string | null>

Example

javascript
const myPubkey = await window.nostr.wot.getMyPubkey();

if (myPubkey) {
  console.log(`Configured as: ${myPubkey}`);
} else {
  console.log("Extension not configured");
}

isConfigured()

Check if the extension is configured and ready.

Returns

Promise<ConfigStatus>

Example

javascript
const status = await window.nostr.wot.isConfigured();

if (status.configured) {
  console.log(`Mode: ${status.mode}`);
  console.log(`Has local graph: ${status.hasLocalGraph}`);
} else {
  console.log("Please configure the extension");
}

Graph Queries

getFollows(pubkey?)

Get the follow list for a pubkey.

Parameters

NameTypeDefaultDescription
pubkeystringuser's pubkeyHex pubkey (defaults to user's pubkey)

Returns

Promise<string[]>

Example

javascript
// Get your own follows
const myFollows = await window.nostr.wot.getFollows();

// Get someone else's follows
const theirFollows = await window.nostr.wot.getFollows("pubkey...");

console.log(`Following ${myFollows.length} accounts`);

getCommonFollows(pubkey)

Get accounts that both you and the target follow.

Parameters

NameTypeDescription
pubkeystringHex pubkey to compare with

Returns

Promise<string[]>

Example

javascript
const common = await window.nostr.wot.getCommonFollows(pubkey);
console.log(`You both follow ${common.length} accounts`);

getStats()

Get statistics about the local graph cache.

Returns

Promise<GraphStats>

Example

javascript
const stats = await window.nostr.wot.getStats();

console.log(`Total users: ${stats.totalUsers}`);
console.log(`Total follows: ${stats.totalFollows}`);
console.log(`Last updated: ${stats.lastUpdated}`);

getPath(targetPubkey)

Get the shortest path from you to the target pubkey.

Parameters

NameTypeDescription
targetPubkeystringHex pubkey to find path to

Returns

Promise<string[] | null>

Example

javascript
const path = await window.nostr.wot.getPath(targetPubkey);

if (path) {
  console.log("Connection path:");
  path.forEach((pk, i) => {
    console.log(`  ${i + 1}. ${pk}`);
  });
} else {
  console.log("No path found");
}
Getting StartedSDK Reference