Nostr Client

This module provides a client implementation for interacting with the Nostr network. It handles connection management, event publishing, subscription handling, and message processing for agent communication and MCP over the Nostr protocol.

class agentstr.nostr_client.NostrClient(relays: list[str], private_key: str | None = None, nwc_str: str | None = None)[source]

Bases: object

A client for interacting with the Nostr protocol, handling events, direct messages, and metadata.

This class provides methods to connect to Nostr relays, send and receive direct messages, manage metadata, and read posts by tags. It integrates with Nostr Wallet Connect (NWC) for payment processing if provided.

__init__(relays: list[str], private_key: str | None = None, nwc_str: str | None = None)[source]

Initialize the NostrClient.

Parameters:

  • relays – List of Nostr relay URLs to connect to.

  • private_key – Nostr private key in ‘nsec’ format.

  • nwc_str – Nostr Wallet Connect string for payment processing (optional).

Note

If no private key is provided, the client will operate in read-only mode.

property relay_manager: RelayManager
property nwc_relay: NWCRelay | None

NWCRelay instance if NWC is configured.

sign(event: Event) → Event[source]

Sign an event with the client’s private key.

Parameters:

event – The Nostr event to sign.

Returns:

The signed event.

async read_posts_by_tag(tag: str | None = None, tags: list[str] | None = None, limit: int = 10) → list[Event][source]

Read posts containing a specific tag from Nostr relays.

Parameters:

  • tag – The tag to filter posts by.

  • limit – Maximum number of posts to retrieve.

Returns:

List of Events.

async read_posts_by_author(pubkey: str | PrivateKey, limit: int = 10) → list[Event][source]

Read posts by a specific author from Nostr relays.

Parameters:

  • pubkey – The author’s public key in hex or bech32 format.

  • limit – Maximum number of posts to retrieve.

Returns:

List of Events.

async get_metadata_for_pubkey(public_key: str | PrivateKey = None) → Metadata | None[source]

Fetch metadata for a public key (or self if none provided).

async update_metadata(name: str | None = None, about: str | None = None, nip05: str | None = None, picture: str | None = None, banner: str | None = None, lud16: str | None = None, lud06: str | None = None, username: str | None = None, display_name: str | None = None, website: str | None = None)[source]

Update the client’s metadata on Nostr relays.

Parameters:

  • name – Nostr name.

  • about – Description or bio.

  • nip05 – NIP-05 identifier.

  • picture – Profile picture URL.

  • banner – Banner image URL.

  • lud16 – Lightning address.

  • lud06 – LNURL.

  • username – Username.

  • display_name – Display name.

  • website – Website URL.

async send_direct_message(recipient_pubkey: str, message: str, event_ref: str | None = None) → Event[source]

Send an encrypted direct message to a recipient.

Parameters:

  • recipient_pubkey – The recipient’s public key in hex or bech32 format.

  • message – The message content to send.

  • event_ref – Optional event ID to reference in the message.

Returns:

The sent event.

async receive_direct_message(recipient_pubkey: str, timestamp: int | None = None, timeout: int = 60) → DecryptedMessage | None[source]

Wait for and return the next direct message from a recipient.

async send_direct_message_and_receive_response(recipient_pubkey: str, message: str, timeout: int = 60, event_ref: str | None = None) → DecryptedMessage[source]

Send an encrypted direct message to a recipient and wait for a response.

Parameters:

  • recipient_pubkey – The recipient’s public key.

  • message – The message content (string or dict, which will be JSON-encoded).

async note_listener(callback: Callable[[Event], Any], pubkeys: list[str] | None = None, tags: list[str] | None = None, following_only: bool = False, timestamp: int | None = None)[source]

Listen for public notes matching the given filters.

Parameters:

  • callback – Function to handle received notes (takes Event as argument).

  • pubkeys – List of pubkeys to filter notes from (hex or bech32 format).

  • tags – List of tags to filter notes by.

  • following_only – If True, only show notes from users the agent is following (optional).

  • timestamp – Filter messages since this timestamp (optional).

async direct_message_listener(callback: Callable[[Event, str], Any], recipient_pubkey: str | None = None, timestamp: int | None = None)[source]

Listen for incoming encrypted direct messages.

Parameters:

  • callback – Function to handle received messages (takes Event and message content as args).

  • recipient_pubkey – Filter messages from a specific public key (optional).

  • timestamp – Filter messages since this timestamp (optional).