NWC

The main class for interacting with NWC-compatible wallets.

Import

import { NWC } from 'nostr-core'

Constructor

new NWC(connectionString: string)

Parses an NWC connection string and creates a client instance.

Parameters:

Parameter	Type	Description
connectionString	string	NWC URI (nostr+walletconnect://... or nostrwalletconnect://...)

Throws: NWCError with code 'INVALID_CONNECTION_STRING' if the URI can't be parsed.

The connection string format is:

nostr+walletconnect://<walletPubkey>?relay=<relayUrl>&secret=<hexOrNsec>

Static Methods

parseConnectionString

NWC.parseConnectionString(connectionString: string): NWCConnectionOptions

Parses a connection string without creating a client.

Returns: NWCConnectionOptions

const { walletPubkey, relayUrl, secret } = NWC.parseConnectionString('nostr+walletconnect://...')

Properties

replyTimeout

nwc.replyTimeout: number // default: 60000

Milliseconds to wait for a wallet reply. Set before calling wallet methods.

publishTimeout

nwc.publishTimeout: number // default: 5000

Milliseconds to wait for relay acknowledgement when publishing events.

connected

nwc.connected: boolean // getter

Whether the underlying relay connection is active.

Connection

connect

await nwc.connect(): Promise<void>

Connects to the relay and auto-detects encryption (NIP-04 or NIP-44).

• Connects to the relay with a 5-second timeout
• Queries the wallet's service info event (kind 13194) to detect encryption
• Starts notification subscription if event handlers are registered

Throws: NWCConnectionError on failure.

close

nwc.close(): void

Closes the notification subscription, relay connection, and clears all event handlers.

Wallet Methods

getInfo

await nwc.getInfo(): Promise<GetInfoResponse>

Returns wallet metadata. Uses a 10-second reply timeout.

Returns: GetInfoResponse

getBalance

await nwc.getBalance(): Promise<GetBalanceResponse>

Returns the wallet balance in millisatoshis. Uses a 10-second reply timeout.

Returns: GetBalanceResponse

getBudget

await nwc.getBudget(): Promise<GetBudgetResponse>

Returns the NWC spending budget info. Uses a 10-second reply timeout.

Returns: GetBudgetResponse

payInvoice

await nwc.payInvoice(invoice: string, amount?: number): Promise<PayResponse>

Pays a BOLT-11 Lightning invoice.

Parameter	Type	Description
invoice	string	BOLT-11 invoice
amount	number?	Amount in msats (for zero-amount invoices)

Returns: PayResponse

payKeysend

await nwc.payKeysend(params: PayKeysendRequest): Promise<PayResponse>

Sends a keysend payment to a node pubkey.

Parameters: PayKeysendRequest

Returns: PayResponse

makeInvoice

await nwc.makeInvoice(params: MakeInvoiceRequest): Promise<Transaction>

Creates a Lightning invoice.

Parameters: MakeInvoiceRequest

Returns: Transaction

lookupInvoice

await nwc.lookupInvoice(params: LookupInvoiceRequest): Promise<Transaction>

Looks up an invoice by payment hash or invoice string.

Parameters: LookupInvoiceRequest

Returns: Transaction

listTransactions

await nwc.listTransactions(params?: ListTransactionsRequest): Promise<ListTransactionsResponse>

Lists transactions with optional filtering. Uses a 10-second reply timeout.

Parameters: ListTransactionsRequest

Returns: ListTransactionsResponse

signMessage

await nwc.signMessage(message: string): Promise<SignMessageResponse>

Signs a message with the wallet's key.

Parameter	Type	Description
message	string	Message to sign

Returns: SignMessageResponse

Notifications

subscribeNotifications

await nwc.subscribeNotifications(
  onNotification: (notification: Nip47Notification) => void,
  notificationTypes?: Nip47NotificationType[]
): Promise<() => void>

Subscribes to NIP-47 wallet notifications (kind 23196 for NIP-04, kind 23197 for NIP-44). Returns an unsubscribe function.

• Automatically selects the correct notification event kind based on encryption type
• Filters notifications by type if notificationTypes is provided
• Auto-reconnects with a 1-second delay if the relay connection closes

Parameters:

Parameter	Type	Description
onNotification	Function	Callback invoked with each notification
notificationTypes	Nip47NotificationType[]?	Optional filter for notification types

Returns: Promise<() => void> - call the returned function to unsubscribe.

Throws: NWCConnectionError if not connected.

const unsub = await nwc.subscribeNotifications((notification) => {
  console.log(notification.notification_type, notification.notification)
}, ['payment_received', 'hold_invoice_accepted'])

// Later, stop listening:
unsub()

on (Event Emitter)

nwc.on(event: Nip47NotificationType, handler: (notification: Nip47Notification) => void): void

Registers a handler for payment notifications using an event emitter pattern. If already connected, starts the notification subscription automatically.

Event	Description
'payment_received'	Incoming payment received
'payment_sent'	Outgoing payment completed
'hold_invoice_accepted'	Hold invoice accepted by payer

nwc.on('payment_received', (notification) => {
  const tx = notification.notification // Transaction object
  console.log(`Received ${tx.amount} msats`)
})

nwc.on('hold_invoice_accepted', (notification) => {
  const tx = notification.notification
  console.log(`Hold invoice ${tx.payment_hash} accepted`)
})

off

nwc.off(event: Nip47NotificationType, handler: Function): void

Removes a previously registered event handler.