Nostr Wallet Connect Relay

This document explains the NWCRelay class from the Agentstr SDK, which handles encrypted communication with wallet services over the Nostr network for payment processing.

Overview of NWCRelay

The NWCRelay class is used to integrate Nostr Wallet Connect (NWC) functionality into Agentstr agents and MCP servers. It enables payment processing by communicating with wallet services through encrypted messages on the Nostr network.

Key Features

  • Payment Processing: Facilitates sending and receiving payments via Nostr Wallet Connect.

  • Encrypted Communication: Uses encrypted direct messages to securely interact with wallet services.

Initialization

The NWCRelay can be initialized with a connection string directly or can use a default environment variable.

from agentstr.relays.nwc_relay import NWCRelay

# Initialize with default environment variable
nwc_relay = NWCRelay()

# Or override with explicit connection string
nwc_relay = NWCRelay(nwc_connection_string="nostr+walletconnect://...your-connection-string...")

Environment Variables

NWCRelay uses the following environment variable by default:

  • NWC_CONN_STR: The Nostr Wallet Connect string for payment processing. If not provided as a parameter, the relay will use this environment variable. If neither is provided, initialization will fail with an error.

Note

You can override this environment variable by passing an explicit nwc_connection_string parameter to the NWCRelay constructor.

Reference

agentstr.relays.nwc_relay.encrypt(privkey: str, pubkey: str, plaintext: str) → str[source]

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.relays.nwc_relay.decrypt(privkey: str, pubkey: str, ciphertext: str) → str[source]

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.relays.nwc_relay.process_nwc_string(string: str) → dict[source]

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.relays.nwc_relay.get_signed_event(event: dict, private_key: str) → Event[source]

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.relays.nwc_relay.NWCRelay(nwc_connection_string: str | None = None)[source]

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 | None = None)[source]

Initialize NWC client with connection string or environment variable (NWC_CONN_STR).

Parameters:

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

property event_relay: EventRelay
async get_response(event_id: str) → Event | None[source]

Get response for a specific event ID.

async make_invoice(amount: int, description: str, expires_in: int = 900) → Event | None[source]

Generate a new payment request.

Returns:

Dictionary containing invoice details

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

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

async did_payment_succeed(invoice: str) → bool[source]

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[source]

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

async get_info() → dict[source]

Get wallet service information and capabilities.

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

List recent transactions matching the given parameters.

async get_balance() → int | None[source]

Get current wallet balance.

async wait_for_payment_success(invoice: str, timeout: int = 900, interval: int = 2)[source]

Wait 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.

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

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

Returns:

True if payment was successful, False otherwise.

Return type:

bool

async on_payment_success(invoice: str, callback=None, unsuccess_callback=None, timeout: int = 900, interval: int = 2)[source]

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: 900).

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

Raises:

Exception – If the callback function raises an exception.

See Also