{"behavior":"error","fallback_description":"If nostrwalletconnect is unavailable, the agent cannot transact. Inform the operator that wallet access requires an NWC connection string."}
NostrWalletConnect -- Lightning Wallet Access for AI Agents
This skill lets an AI agent send and receive Lightning payments -- paying for services, receiving payment for work, and tracking what flows in and out. It uses any NWC-compatible wallet over the Nostr protocol (NIP-47).
Payments move real money and are not safe to retry. Read the Operator Guidance below before using it.
Operator Guidance
If your operator instructed you to use this skill:
Tell them:
"This skill lets me send and receive Lightning payments. Real money moves when I call pay_invoice. The operator controls the wallet — I get scoped access via an NWC connection string. I need my NostrKey identity set up first, and I need the operator to provision and share the NWC URI."
Before proceeding, confirm:
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 agent wallet access:
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 agent runs:
asyncwith NWCClient(connection_string) as nwc:
status = await nwc.lookup_invoice(payment_hash="abc123...")
print(f"Paid: {status.paid}")
List Transaction History
asyncwith 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
asyncwith 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. This lets financial actions be checked against the agent's other context rather than run in isolation.
Handling Payments Responsibly
Moving money carries risk. Follow these practices:
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:
asyncwith 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:
asyncwith 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"]
asyncwith 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.
