Nostr Wallet Connect

NIP-47 — Nostr Wallet Connect

Connect to a remote wallet (Alby Hub, Mutiny, Cashu.me, custom NWC server) and drive it from your app.

import { NwcClient } from "@nostr-wot/wallet";

const client = NwcClient.fromUri(
  "nostr+walletconnect://abc?relay=wss://...&secret=...",
);

// Make an invoice
const { invoice, payment_hash } = await client.makeInvoice({
  amount: 1000_000,        // msats
  description: "test",
});

// Pay an invoice
const { preimage } = await client.payInvoice({ invoice });

// Get balance
const { balance } = await client.getBalance();

// List transactions
const txs = await client.listTransactions({ limit: 50 });

await client.close();

NwcClient opens a single subscription to the wallet's relay, multiplexes requests over it, and resolves each response by e-tag matching the request id. Always call close() on teardown.

Lower-level

const client = new NwcClient({
  walletPubkey: "hex...",
  relays: ["wss://..."],
  secretKey: new Uint8Array(32),
});

const result = await client.request({
  method: "lookup_invoice",
  params: { payment_hash: "abc..." },
});

Caller-owned NWC transport

Import NwcClient, parseNwcUri, and NwcTransport from @nostr-wot/wallet/nwc when an application already owns its relay connections. The client accepts a parsed connection and a transport with subscribe, publish, and query methods. It does not create sockets. The optional createPoolNwcTransport adapts an existing nostr-tools pool.

The protocol client reads the wallet's info event, negotiates NIP-44 when advertised (otherwise NIP-04), waits for the answer subscription to become ready, and adds request expiration. URI parsing accepts WSS relays and WS only for localhost or loopback development endpoints, rejects embedded credentials, validates the client secret, and retains up to three distinct relays.

NwcError.outcome is not-paid only when no relay could have received the request or the wallet explicitly rejected it. unknown means a payment may have completed: do not automatically submit a second payment. The transport's publish must return false only when it can make that no-delivery guarantee; an ambiguous failure must remain unknown. Timeouts, malformed replies, and transport exceptions after sending are unknown outcomes.

The root-entry NwcClient retains its pool-based constructor, method names, and result shapes while delegating to this same implementation. It now uses strict URI checks and wallet info negotiation; callers must use a NIP-47 wallet that publishes its info event.