Nostr WoT

Extension API

The extension exposes window.nostr for identity, event signing, and NIP-04/NIP-44 message encryption.

Install the extension, select an account, and connect your site when prompted. Signing and encryption require a signing-capable account and may prompt you to unlock the vault. Reading a known public key does not require unlocking it.

Setup

Check for the method you need before calling it. An injected provider does not mean the site is connected or a request has been approved.

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

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

NIP-07 Signer API

The extension implements the NIP-07 signer API exposed through window.nostr.

getPublicKey()

Returns the active account's hex-encoded public key. Requires site connection and identity access.

Returns

Promise<string>

Example

javascript
const pubkey = await window.nostr.getPublicKey();
console.log(pubkey); // "3bf0c63f..."

signEvent(event)

Signs the event and adds id, pubkey and sig. Supply created_at yourself; the signer preserves your timestamp. If you supply pubkey, it must match the active account. Signing does not publish the event.

Parameters

NameTypeDescription
eventUnsignedEventEvent containing kind, content, tags and created_at (Unix time in seconds)

Returns

Promise<SignedEvent>

Example

javascript
const signed = await window.nostr.signEvent({
  kind: 1,
  content: "Hello Nostr!",
  tags: [],
  created_at: Math.floor(Date.now() / 1000),
});
console.log(signed.sig); // schnorr signature

nip04.encrypt(pubkey, plaintext)

Encrypts a message using NIP-04, the legacy direct-message encryption format.

Parameters

NameTypeDescription
pubkeystringRecipient's 64-character hexadecimal public key
plaintextstringMessage to encrypt

Returns

Promise<string>

Example

javascript
const encrypted = await window.nostr.nip04.encrypt(
  recipientPubkey,
  "Secret message"
);

nip04.decrypt(pubkey, ciphertext)

Decrypts a NIP-04 message.

Parameters

NameTypeDescription
pubkeystringSender's 64-character hexadecimal public key
ciphertextstringEncrypted message string

Returns

Promise<string>

Example

javascript
const plaintext = await window.nostr.nip04.decrypt(
  senderPubkey,
  ciphertext
);
console.log(plaintext); // "Secret message"

nip44.encrypt(pubkey, plaintext)

Encrypts a message using NIP-44. This example uses the standard two-argument call.

Parameters

NameTypeDescription
pubkeystringRecipient's 64-character hexadecimal public key
plaintextstringMessage to encrypt

Returns

Promise<string>

Example

javascript
const encrypted = await window.nostr.nip44.encrypt(
  recipientPubkey,
  "Secret message"
);

nip44.decrypt(pubkey, ciphertext)

Decrypts a NIP-44 message.

Parameters

NameTypeDescription
pubkeystringSender's 64-character hexadecimal public key
ciphertextstringEncrypted message string

Returns

Promise<string>

Example

javascript
const plaintext = await window.nostr.nip44.decrypt(
  senderPubkey,
  ciphertext
);
console.log(plaintext); // "Secret message"

getRelays()

Returns the relay URLs configured in the extension. Each entry has read: true and write: true. This method does not fetch the account's NIP-65 relay policies and may return an empty object.

Returns

Promise<Record<string, { read: boolean; write: boolean }>>

Example

javascript
const relays = await window.nostr.getRelays();

// {
//   "wss://relay.damus.io": { read: true, write: true },
//   "wss://nos.lol": { read: true, write: true }
// }

Connection, permissions and errors

Calls return Promises and can reject if the user declines, the site is disconnected, identity access is disabled, or the request times out. Signing and encryption are unavailable for read-only accounts.

An account switch can invalidate a pending request. Page calls time out after 120 seconds, including time spent waiting for connection, permission or unlock. Catch errors and let the user retry; error messages are not stable machine-readable codes.

javascript
async function signNote(content) {
  const provider = window.nostr;
  if (typeof provider?.getPublicKey !== "function" ||
      typeof provider?.signEvent !== "function") {
    return { ok: false, reason: "provider-unavailable" };
  }

  try {
    const pubkey = await provider.getPublicKey();
    if (!pubkey) return { ok: false, reason: "no-active-account" };

    const event = await provider.signEvent({
      pubkey,
      kind: 1,
      content,
      tags: [],
      created_at: Math.floor(Date.now() / 1000),
    });
    return { ok: true, event };
  } catch (error) {
    return { ok: false, reason: "request-failed", error };
  }
}

Use the SDK for follow-graph queries and the WoT Oracle API for public mute evidence. Mute evidence is separate from follow distance; it does not produce a combined trust score. The extension provides identity and signing.

Use the extension wallet through WebLN

Call enable() before requesting wallet operations. sendPayment() takes a BOLT11 invoice and returns a preimage after payment succeeds. The extension also exposes getInfo(), makeInvoice() and getBalance(); check availability before using these optional capabilities.

Example

javascript
// Call from a Pay button after the user reviews the invoice.
export async function payInvoice(paymentRequest) {
  const provider = window.webln;
  if (!provider?.enable || !provider?.sendPayment) {
    throw new Error("A WebLN wallet is required");
  }
  await provider.enable();
  return provider.sendPayment(paymentRequest);
}

Integration notes

A Nostr connection does not authorize wallet access. The user needs a configured wallet and may be asked to approve payment or connect it. Avoid concurrent duplicate sends and keep payment state visible. Do not retry automatically after a timeout; reconcile the outcome with the wallet first.

What websites can use

The extension exposes window.nostr for NIP-07 identity, signing and supported encryption methods, plus window.webln for wallet operations. Detect each optional method before using it. Passkey, seed and remote-signer accounts use the same website-facing signing interface.

Integration notes

The vault, passkey recovery files, archive database and internal extension RPCs are not public website APIs. Your app never needs the user’s seed. Watch-only accounts cannot sign. A configured remote signer may require an external approval. Use the SDK’s graph and Oracle tools for trust queries rather than assuming window.nostr includes a trust-scoring API.

Package reference and additional options

Sign, publish and report relay results

Signing and publishing are separate operations. First obtain a signed event through NIP-07, then send that event to relays chosen by your application and user. The example returns an acceptance result for each relay and closes its temporary pool.

terminal
$npm install nostr-tools

Example

typescript
import { SimplePool, verifyEvent, type Event } from "nostr-tools";

// Pass the event returned by window.nostr.signEvent().
export async function publishNote(event: Event, relays: string[]) {
  if (!verifyEvent(event)) throw new Error("Invalid signed event");
  if (relays.length === 0) throw new Error("Choose at least one relay");
  const pool = new SimplePool();
  try {
    const results = await Promise.allSettled(pool.publish(relays, event));
    return results.map((result, i) => ({
      relay: relays[i], accepted: result.status === "fulfilled",
    }));
  } finally {
    pool.close(relays);
  }
}

Integration notes

A signature proves authorship, not delivery. Report success only for relays that accepted the event; a partial result should retain successes. Retrying publication should reuse the same signed event and ID. In a long-lived application, reuse your existing relay transport rather than creating a pool per note.

Permissions, account changes and cancellation

Request the public key from a Connect button and request signatures only when the user takes the corresponding action. The extension can ask for connection permission, unlock or approval. Never assume a previous approval covers a new account or operation.

Example

javascript
// Mount once in your app and call the returned cleanup on unmount.
export function watchAccount(onAccountChanged) {
  const reset = () => onAccountChanged();
  window.addEventListener("nostr:accountChanged", reset);
  return () => window.removeEventListener("nostr:accountChanged", reset);
}

// In onAccountChanged: clear account-specific views and pending drafts,
// stop subscriptions and require a fresh connection before signing.
// Other NIP-07 extensions may not emit this Nostr WoT-specific event.

Integration notes

The account-change listener is specific to Nostr WoT. Recheck the selected identity before completing a sensitive action and discard stale responses. Catch rejected promises, preserve the user’s draft and show a retry action. Do not automatically loop signing or decryption prompts after cancellation. HTTP authentication signs kind 27235; relay AUTH uses kind 22242.