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:

Set up an NWC-compatible wallet (Alby, Mutiny, Coinos, etc.)
Generate an NWC connection string from the wallet's settings -- look for "Nostr Wallet Connect" or "NWC"
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)	--

nostrwalletconnect

Installation