NWC (Nostr Wallet Connect) Relay

This module implements a relay service for Nostr Wallet Connect (NWC) functionality. It facilitates secure communication between Nostr clients and wallet applications, handling authentication, message relaying, and payment processing within the Nostr ecosystem.

agentstr.nwc_relay.encrypt(privkey: str, pubkey: str, plaintext: str) → str

Encrypt plaintext using ECDH shared secret.

Parameters:

• privkey – Sender’s private key.

• pubkey – Recipient’s public key.

• plaintext – The message to encrypt.

Returns:

The encrypted message as a string.

agentstr.nwc_relay.decrypt(privkey: str, pubkey: str, ciphertext: str) → str

Decrypt ciphertext using ECDH shared secret.

Parameters:

• privkey – Recipient’s private key.

• pubkey – Sender’s public key.

• ciphertext – The encrypted message to decrypt.

Returns:

The decrypted plaintext message.

agentstr.nwc_relay.process_nwc_string(string: str) → dict

Parse Nostr Wallet Connect connection string into its components.

Parameters:

string – The NWC connection string to parse.

Returns:

Dictionary containing connection parameters.

Raises:

ValueError – If the connection string is invalid.

agentstr.nwc_relay.get_signed_event(event: dict, private_key: str)

Create and sign a Nostr event with the given private key.

Parameters:

• event – The event data as a dictionary.

• private_key – The private key to sign the event with.

Returns:

A signed Nostr event.

class agentstr.nwc_relay.NWCRelay(nwc_connection_string: str, relay: str | None = None)

Bases: object

Client for interacting with Nostr Wallet Connect (NWC) relays.

Handles encrypted communication with wallet services over the Nostr network.

__init__(nwc_connection_string: str, relay: str | None = None)

Initialize NWC client with connection string and optional relay URL.

Parameters:

• nwc_connection_string – NWC connection string (starts with ‘nostr+walletconnect://’)

• relay – Optional relay URL override

async get_response(event_id: str) → Event | None

Get response for a specific event ID.

async make_invoice(amount: int, description: str) → Event | None

Generate a new payment request.

Returns:

Dictionary containing invoice details

async check_invoice(invoice: str | None = None, payment_hash: str | None = None) → dict | None

Check the status of an invoice by its payment hash or invoice string.

async did_payment_succeed(invoice: str) → bool

Check if a payment was successful.

Returns:

True if payment was successful, False otherwise

async try_pay_invoice(invoice: str, amount: int | None = None) → dict | None

Attempt to pay a BOLT11 invoice. :returns: Dictionary with payment status and details

async get_info() → dict

Get wallet service information and capabilities.

async list_transactions(params: dict | None = None) → list[dict]

List recent transactions matching the given parameters.

async get_balance() → int | None

Get current wallet balance.

async on_payment_success(invoice: str, callback=None, unsuccess_callback=None, timeout: int = 300, interval: int = 2)

Listen for payment success for a given invoice.

This method continuously checks for payment success until either the payment is confirmed or the timeout is reached.

Parameters:

• invoice (str) – The BOLT11 invoice string to listen for.

• callback (callable, optional) – A function to call when payment succeeds.

• unsuccess_callback (callable, optional) – A function to call if payment fails.

• timeout (int, optional) – Maximum time to wait in seconds (default: 300).

• interval (int, optional) – Time between checks in seconds (default: 2).

Raises:

Exception – If the callback function raises an exception.