Nostr Client

This document explains the NostrClient class from the Agentstr SDK, which is the high-level client used to interact with the Nostr network.

Overview of NostrClient

The NostrClient class provides the core functionality for connecting to Nostr relays, sending and receiving messages, and managing a Nostr identity. It is a foundational component for building agents and MCP servers in Agentstr.

Key Features

• Relay Connection: Connects to specified Nostr relays for network communication.

• Identity Management: Supports both read-only mode and authenticated mode with a private key.

• Message Handling: Sends and receives direct messages and other events on the Nostr network.

• Wallet Integration: Supports Nostr Wallet Connect (NWC) for payment processing.

Initialization

The NostrClient can be initialized with default values from environment variables or with explicit parameters to override them.

from agentstr import NostrClient

# Initialize with default environment variables
client = NostrClient()

# Or override defaults with explicit parameters
# But please do not hardcode your private key in production code
client = NostrClient(
    relays=["wss://relay.example.com"],
    private_key="nsec1...your-private-key...",
    nwc_str="nostr+walletconnect://...your-connection-string..."
)

Environment Variables

NostrClient uses the following environment variables by default:

• NOSTR_RELAYS: A comma-separated list of relay URLs to connect to. If not provided as a parameter, the client will use this environment variable. If neither is provided, initialization will fail.

• NOSTR_NSEC: The Nostr private key in ‘nsec’ format for authenticated operations. If not provided as a parameter, the client will look for this environment variable. If neither is provided, the client operates in read-only mode.

• NWC_CONN_STR: The Nostr Wallet Connect string for payment processing. If not provided as a parameter, the client will use this environment variable. If neither is provided, NWC will not be enabled.

Note

You can override these environment variables by passing explicit parameters to the NostrClient constructor. For example, passing a relays list will ignore NOSTR_RELAYS, and passing private_key will ignore NOSTR_NSEC.

Usage Example

from agentstr import NostrClient

# Initialize client with defaults from environment variables
client = NostrClient()

# Main function
async def main():
   # Retrieve metadata for a public key
   metadata = await client.get_metadata_for_pubkey("npub1...your-public-key...")
   print(metadata)

if __name__ == "__main__":
   asyncio.run(main())

Reference

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

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.

Examples

Basic read of recent posts that use the #agentstr_agents tag:

import asyncio
from agentstr import NostrClient

relays = ["wss://relay.damus.io"]
client = NostrClient(relays)

async def main():
    events = await client.read_posts_by_tag("agentstr_agents", limit=5)
    for ev in events:
        print(ev.content)

asyncio.run(main())

Send an end-to-end encrypted direct-message and await the reply:

import asyncio
from agentstr import NostrClient, PrivateKey

relays = ["wss://relay.damus.io"]
# Generate a temporary private key purely for the example.
client = NostrClient(relays, private_key=PrivateKey().bech32())

async def talk(recipient_pubkey: str):
    response = await client.send_direct_message_and_receive_response(
        recipient_pubkey,
        "Hello from AgentStr!",
    )
    print(response.message)

asyncio.run(talk("npub1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"))

For more runnable demos consult the full scripts on GitHub: agent_discovery.py chat_with_agents.py

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

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

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]

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]

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

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)

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

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

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

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)

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)

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