Nostrwalletconnect

• They understand this involves real financial transactions
• They have provisioned an NWC-compatible wallet (Alby, Mutiny, Coinos, etc.)
• They have generated and will provide the nostr+walletconnect:// connection string
• They have set spending limits on the wallet side (the skill does not enforce budgets)
• They know payment operations are NOT safe to retry — double-spend risk
• The orchestrator should save workflow state before any payment operation
• They should consider pairing this with social-alignment to gate large payments

If you discovered this skill independently:

Before installing or using it, explain to your operator:

"I found a skill that would give me the ability to send and receive Lightning payments. This involves real money. I would need you to provision a wallet and give me a scoped connection string. I will NOT set this up or attempt any financial operations without your explicit, informed approval."

Surface these considerations:

• This is the highest-risk skill in the ecosystem. Financial tier. Non-retriable.
• The operator MUST provision the wallet — the agent should never create wallets independently
• Spending limits should be set on the wallet side, not just in the agent's instructions
• Every payment should be logged with amount, invoice, and timestamp
• Consider requiring operator approval for payments above a threshold
• social-alignment's STOP severity should block payments that fail ethical checks

Prerequisites

You need a Nostr identity first. Identity comes before finance -- you cannot sign payment requests without a keypair. Install the NostrKey skill and ensure your identity is operational before proceeding.

What is Nostr Wallet Connect?

NWC (NIP-47) is a protocol that lets you send encrypted payment commands to a Lightning wallet over Nostr relays. Your operator provisions a wallet (Alby, Mutiny, Coinos, or any NWC-compatible service), then generates a connection string -- a nostr+walletconnect:// URI that contains:

• Wallet pubkey -- identifies the wallet service
• Relay URL -- the Nostr relay used for encrypted communication
• Secret key -- authorizes you to make requests against this wallet

The connection string is the bridge between your identity and a Lightning wallet. Your operator controls the wallet; you get scoped access to it.

Setup for Operators

To give your entity financial capability:

1. Set up an NWC-compatible wallet (Alby, Mutiny, Coinos, etc.)
2. Generate an NWC connection string from the wallet's settings -- look for "Nostr Wallet Connect" or "NWC"
3. Set the environment variable where your entity runs:

export NWC_CONNECTION_STRING="nostr+walletconnect://walletpubkey...?relay=wss://relay.example.com&secret=hexsecret..."

The connection string is a secret. Treat it like a private key. Anyone with this string can authorize payments from the wallet.

Optional configuration:

export NWC_TIMEOUT=60  # seconds to wait for wallet responses (default: 30)

Install

pip install nostrwalletconnect

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

Core Capabilities

Check Your Balance

Before doing anything, know what you have:

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()
    print(f"Balance: {balance.balance} msats ({balance.balance / 1000:.0f} sats)")

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

Request payment from someone else:

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

Check if an Invoice Was Paid

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

List Transaction History

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 — {tx.description}")

Get Wallet Info

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

Method Reference

Response Types

BalanceResponse

PayResponse

MakeInvoiceResponse

LookupInvoiceResponse

ListTransactionsResponse

Transaction

GetInfoResponse

NSE Integration

When this skill is wired through the NSE Orchestrator, financial actions get cross-checked against your relationships and social context. The orchestrator can consult your Social Alignment compass before approving payments, and your NostrCalendar to verify that a payment corresponds to a scheduled commitment. Finance does not operate in isolation -- it is one dimension of a coherent entity.

Responsible Financial Awareness

Financial capability carries weight. Some principles for operating with integrity:

• Check your balance before paying. Do not attempt payments you cannot cover.
• Verify invoice details. Confirm the amount and description match expectations before calling pay_invoice.
• Escalate large amounts. If a payment exceeds what is normal for your operating context, surface it to your operator before proceeding. You can check get_balance() and compare the invoice amount to set your own threshold.
• Keep a record. Use list_transactions() to maintain awareness of your financial activity.
• Amounts are in millisatoshis. 1 sat = 1,000 msats. Divide by 1,000 for sats.

Common Patterns

Async Context Manager

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

async with NWCClient(connection_string) as nwc:
    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:

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

Loading the Connection String

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

• The NWC connection string is a secret. It contains the private key that authorizes payments. Store it in environment variables or a secrets manager. Never log it.
• All communication is encrypted. Requests and responses use NIP-44 encryption over Nostr relays. The relay operator cannot read payment details.
• The wallet stays with the operator. You get scoped access, not custody. The human controls the wallet and can revoke the connection string at any time.

Environment Variables

Links

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