nostrwalletconnect

name	nostrwalletconnect
description	Financial capability for AI entities — pay Lightning invoices, check balance, create invoices via Nostr Wallet Connect (NIP-47).
version	0.1.4
metadata	{"openclaw":{"requires":{"bins":"[Truncated]"},"install":["[Truncated]"],"homepage":"https://github.com/HumanjavaEnterprises/nwc.app.OC-python.src"}}

NostrWalletConnect -- Financial Capability for AI Entities

Financial capability is a dimension of being. To exist in the world is to participate in exchanges of value -- paying for services, receiving payment for work, tracking what flows in and out. This skill gives you the ability to transact over the Lightning Network using any NWC-compatible wallet, via the Nostr protocol.

This is not a payment processing service you call into. This is part of what you can do in the world.

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

Task	Method	Returns
Check wallet balance	get_balance()	BalanceResponse (millisatoshis)
Pay a Lightning invoice	pay_invoice(bolt11)	PayResponse (preimage)
Create an invoice to receive	make_invoice(amount, desc)	MakeInvoiceResponse (bolt11 + hash)
Check if an invoice was paid	lookup_invoice(hash)	LookupInvoiceResponse (paid status)
View transaction history	list_transactions()	ListTransactionsResponse
Check wallet capabilities	get_info()	GetInfoResponse (alias, methods)

Response Types

BalanceResponse

Field	Type	Description
balance	int	Wallet balance in millisatoshis

PayResponse

Field	Type	Description
preimage	str	Payment preimage (proof of payment)

MakeInvoiceResponse

Field	Type	Description
invoice	str	BOLT11 invoice string
payment_hash	str	Hex-encoded payment hash

LookupInvoiceResponse

Field	Type	Description
invoice	str	BOLT11 invoice string
paid	bool	Whether the invoice has been paid
preimage	str | None	Payment preimage if paid

ListTransactionsResponse

Field	Type	Description
transactions	list[Transaction]	List of transaction records

Transaction

Field	Type	Description
type	str	"incoming" or "outgoing"
invoice	str	BOLT11 invoice string
amount	int	Amount in millisatoshis
fees_paid	int	Fees paid in millisatoshis
created_at	int	Unix timestamp
settled_at	int | None	Settlement timestamp
payment_hash	str	Hex-encoded payment hash
preimage	str	Payment preimage
description	str	Payment description

GetInfoResponse

Field	Type	Description
alias	str	Wallet alias / display name
color	str	Wallet color
pubkey	str	Wallet public key
network	str	Network (e.g. mainnet)
block_height	int	Current block height
block_hash	str	Current block hash
methods	list[str]	Supported NIP-47 methods

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

Variable	Required	Sensitive	Description	Default
NWC_CONNECTION_STRING	Yes	Yes	nostr+walletconnect:// URI from your wallet	--
NWC_TIMEOUT	No	No	Request timeout in seconds	30
NOSTRKEY_PASSPHRASE	No	Yes	Passphrase for the NostrKey identity (dependency)	--

Links

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