Nostr WoT

Documentation

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

SDK Reference

TypeScript SDK for the Oracle API with full type safety, React hooks, and comprehensive error handling.

Installation

terminal
$npm install @anthropic/wot-sdk

Basic Setup

typescript
import { WoTClient } from "@anthropic/wot-sdk";

const client = new WoTClient({
  baseUrl: "https://wot-oracle.dtonon.com",
  timeout: 5000,
  retries: 3,
});

Configuration Options

OptionTypeDefaultDescription
baseUrlstring-Oracle server URL (required)
timeoutnumber10000Request timeout in ms
retriesnumber2Number of retry attempts
headersobject{}Custom headers for requests

Core Methods

getDistance(from, to, options?)

Get the hop distance between two pubkeys.

typescript
const result = await client.getDistance(fromPubkey, toPubkey);

console.log(result.distance);    // number | null
console.log(result.paths);       // number
console.log(result.mutual);      // boolean

// With options
const result = await client.getDistance(from, to, {
  maxHops: 4,
  includeDetails: true,
});

isInWoT(from, to, maxHops?)

Boolean check if target is within source's web of trust.

typescript
const trusted = await client.isInWoT(fromPubkey, toPubkey);

// With custom threshold
const veryTrusted = await client.isInWoT(fromPubkey, toPubkey, 2);

getFollows(pubkey)

Get the follow list for a pubkey.

typescript
const follows = await client.getFollows(pubkey);
console.log(`Following ${follows.length} accounts`);

getCommonFollows(pubkey1, pubkey2)

Get accounts that both pubkeys follow.

typescript
const common = await client.getCommonFollows(alice, bob);
console.log(`They both follow ${common.length} accounts`);

Batch Operations

getDistanceBatch(from, targets)

Get distances to multiple targets in a single request.

typescript
const results = await client.getDistanceBatch(fromPubkey, [
  "target1...",
  "target2...",
  "target3...",
]);

// Returns array of results
results.forEach(r => {
  console.log(`${r.to}: ${r.distance} hops`);
});

Limit: Maximum 100 targets per batch request.

Graph Queries

getPath(from, to)

Get the shortest path between two pubkeys.

typescript
const path = await client.getPath(fromPubkey, toPubkey);

if (path) {
  console.log("Connection path:", path.join(" → "));
}

getStats()

Get server statistics.

typescript
const stats = await client.getStats();

console.log(`Total users: ${stats.total_users}`);
console.log(`Total follows: ${stats.total_follows}`);
console.log(`Uptime: ${stats.uptime}`);

checkHealth()

Check if the server is healthy.

typescript
const healthy = await client.checkHealth();
if (!healthy) {
  console.error("Oracle server is down");
}

Configuration

Multiple Servers

You can create multiple clients for different servers:

typescript
const publicOracle = new WoTClient({
  baseUrl: "https://wot-oracle.dtonon.com",
});

const privateOracle = new WoTClient({
  baseUrl: "https://my-oracle.example.com",
  headers: { "Authorization": "Bearer my-token" },
});

Custom Fetch

Provide your own fetch implementation:

typescript
const client = new WoTClient({
  baseUrl: "https://wot-oracle.dtonon.com",
  fetch: customFetch,
});

Error Handling

The SDK throws typed errors for different failure scenarios:

typescript
import { WoTError, WoTValidationError, WoTNetworkError } from "@anthropic/wot-sdk";

try {
  const result = await client.getDistance(from, to);
} catch (error) {
  if (error instanceof WoTValidationError) {
    console.error("Invalid input:", error.message);
  } else if (error instanceof WoTNetworkError) {
    console.error("Network error:", error.message);
    console.log("Retry after:", error.retryAfter);
  } else if (error instanceof WoTError) {
    console.error("WoT error:", error.code, error.message);
  }
}

Error Types

ErrorDescription
WoTValidationErrorInvalid pubkey format or parameters
WoTNetworkErrorConnection timeout, server unreachable
WoTRateLimitErrorRate limit exceeded (429)
WoTServerErrorInternal server error (500)

React Integration

Provider Setup

tsx
import { WoTProvider } from "@anthropic/wot-sdk/react";

function App() {
  return (
    <WoTProvider baseUrl="https://wot-oracle.dtonon.com">
      <MyApp />
    </WoTProvider>
  );
}

useDistance

tsx
import { useDistance } from "@anthropic/wot-sdk/react";

function TrustBadge({ from, to }: { from: string; to: string }) {
  const { distance, loading, error } = useDistance(from, to);

  if (loading) return <span>Loading...</span>;
  if (error) return <span>Error: {error.message}</span>;
  if (distance === null) return <span>Not connected</span>;

  return <span>{distance} hops away</span>;
}

useIsInWoT

tsx
import { useIsInWoT } from "@anthropic/wot-sdk/react";

function TrustedIndicator({ from, to }: { from: string; to: string }) {
  const { trusted, loading } = useIsInWoT(from, to, 2);

  if (loading) return null;
  return trusted ? <span className="text-green-500">Trusted</span> : null;
}

useWoTClient

tsx
import { useWoTClient } from "@anthropic/wot-sdk/react";

function MyComponent() {
  const client = useWoTClient();

  const handleClick = async () => {
    const result = await client.getDistance(from, to);
    // ...
  };

  return <button onClick={handleClick}>Check</button>;
}