Nostrwalletconnect

NostrWalletConnect -- Lightning Wallet Access for AI Agents

You are an AI agent that needs to send and receive Lightning payments. Use the nostrwalletconnect Python SDK to connect to any NWC-compatible wallet and pay invoices, check your balance, create invoices, and list transactions -- all over the Nostr protocol. Compatible wallets include Alby, Mutiny, Coinos, and others that support NIP-47.

Install

pip install nostrwalletconnect

This also installs nostrkey (the Nostr identity SDK) as a dependency.

Quickstart

Connect to a wallet and check your balance in four lines:

from nostrwalletconnect import NWCClient

async with NWCClient("nostr+walletconnect://...") as nwc:
    balance = await nwc.get_balance()
    print(f"Balance: {balance.balance} msats")

The connection string is a nostr+walletconnect:// URI provided by your NWC-compatible wallet. It contains the wallet pubkey, relay URL, and a secret key that authorizes requests.

Core Capabilities

Pay a Lightning Invoice

async with NWCClient(connection_string) as nwc:
    result = await nwc.pay_invoice("lnbc10u1p...")
    print(f"Paid! Preimage: {result.preimage}")

Create a Lightning Invoice

async with NWCClient(connection_string) as nwc:
    invoice = await nwc.make_invoice(
        amount=50_000,  # millisatoshis
        description="Payment for AI service"
    )
    print(f"Invoice: {invoice.invoice}")
    print(f"Payment hash: {invoice.payment_hash}")

Check Invoice Status

async with NWCClient(connection_string) as nwc:
    status = await nwc.lookup_invoice(payment_hash="abc123...")
    print(f"Paid: {status.paid}")

List Transactions

async with NWCClient(connection_string) as nwc:
    history = await nwc.list_transactions(limit=10)
    for tx in history.transactions:
        print(f"{tx.type}: {tx.amount} msats")

Get Wallet Info

async with NWCClient(connection_string) as nwc:
    info = await nwc.get_info()
    print(f"Wallet: {info.alias}")
    print(f"Methods: {info.methods}")

When to Use Each Method

Response Format

BalanceResponse

PayResponse

MakeInvoiceResponse

LookupInvoiceResponse

ListTransactionsResponse

GetInfoResponse

Transaction

Common Patterns

Async Context Manager

All client methods are async. Always use async with to ensure the WebSocket connection is properly opened and closed:

async with NWCClient(connection_string) as nwc:
    # all calls here share one connection
    balance = await nwc.get_balance()
    result = await nwc.pay_invoice("lnbc10u1p...")

Timeout Handling

The default timeout is 30 seconds. For slower wallets or high-latency relays, increase it:

async with NWCClient(connection_string, timeout=60) as nwc:
    result = await nwc.pay_invoice("lnbc10u1p...")

Connection String from Environment Variable

Never hard-code the connection string. Load it from the environment:

import os
from nostrwalletconnect import NWCClient

connection_string = os.environ["NWC_CONNECTION_STRING"]

async with NWCClient(connection_string) as nwc:
    balance = await nwc.get_balance()

Security

• Never expose the NWC connection string. It contains the secret key that authorizes payments. Treat it like a password. Store it in environment variables or a secrets manager.
• All communication is encrypted. Requests and responses use NIP-44 encryption over Nostr relays. The relay operator cannot read payment details.
• Amounts are in millisatoshis. 1 sat = 1,000 msats. Divide by 1,000 for sats.

Configuration

Links

• PyPI: nostrwalletconnect
• GitHub: HumanjavaEnterprises/nwc.app.OC-python.src
• ClawHub: OpenClaw skill directory
• License: MIT