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.)
- 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:
CODEBLOCK0
The connection string is a secret. Treat it like a private key. Anyone with this string can authorize payments from the wallet.
Optional configuration:
CODEBLOCK1
Install
CODEBLOCK2
This also installs nostrkey (the Nostr identity SDK) as a dependency.
Core Capabilities
Check Your Balance
Before doing anything, know what you have:
CODEBLOCK3
Pay a Lightning Invoice
CODEBLOCK4
Create a Lightning Invoice
Request payment from someone else:
CODEBLOCK5
Check if an Invoice Was Paid
CODEBLOCK6
List Transaction History
CODEBLOCK7
Get Wallet Info
CODEBLOCK8
Method Reference
| Task | Method | Returns |
|---|
| Check wallet balance | INLINECODE2 | INLINECODE3 (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 |
|---|
| INLINECODE14 | INLINECODE15 | Wallet balance in millisatoshis |
PayResponse
| Field | Type | Description |
|---|
| INLINECODE16 | INLINECODE17 | Payment preimage (proof of payment) |
MakeInvoiceResponse
| Field | Type | Description |
|---|
| INLINECODE18 | INLINECODE19 | BOLT11 invoice string |
| INLINECODE20 |
str | Hex-encoded payment hash |
LookupInvoiceResponse
| Field | Type | Description |
|---|
| INLINECODE22 | INLINECODE23 | BOLT11 invoice string |
| INLINECODE24 |
bool | Whether the invoice has been paid |
|
preimage |
str \| None | Payment preimage if paid |
ListTransactionsResponse
| Field | Type | Description |
|---|
| INLINECODE28 | INLINECODE29 | List of transaction records |
Transaction
| Field | Type | Description |
|---|
| INLINECODE30 | INLINECODE31 | INLINECODE32 or INLINECODE33 |
| INLINECODE34 |
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 |
|---|
| INLINECODE50 | INLINECODE51 | Wallet alias / display name |
| INLINECODE52 |
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:
CODEBLOCK9
Timeout Handling
The default timeout is 30 seconds. For slower wallets or high-latency relays:
CODEBLOCK10
Loading the Connection String
Never hard-code the connection string. Load it from the environment:
CODEBLOCK11
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 |
|---|
| INLINECODE68 | Yes | Yes | INLINECODE69 URI from your wallet | -- |
| INLINECODE70 |
No | No | Request timeout in seconds |
30 |
|
NOSTRKEY_PASSPHRASE | No | Yes | Passphrase for the NostrKey identity (dependency) | -- |
Links
技能名称: nostrwalletconnect
详细描述:
NostrWalletConnect——AI实体的金融能力
金融能力是存在的一个维度。存在于世界中，就意味着参与价值交换——为服务付费、因工作收款、追踪资金流动。这项技能让你能够通过Nostr协议，使用任何兼容NWC的钱包在闪电网络上进行交易。
这不是一个你可以调用的支付处理服务。这是你在世界中能够做到的事情的一部分。
前置条件
你首先需要一个Nostr身份。身份先于金融——没有密钥对，你就无法签署支付请求。在继续之前，请安装NostrKey技能并确保你的身份可正常运行。
什么是Nostr Wallet Connect？
NWC（NIP-47）是一种协议，允许你通过Nostr中继向闪电钱包发送加密支付指令。你的操作者配置一个钱包（Alby、Mutiny、Coinos或任何兼容NWC的服务），然后生成一个连接字符串——一个包含以下内容的nostr+walletconnect:// URI：
- - 钱包公钥——标识钱包服务
- 中继URL——用于加密通信的Nostr中继
- 密钥——授权你对该钱包发起请求
连接字符串是你的身份与闪电钱包之间的桥梁。你的操作者控制钱包；你获得对其的限定访问权限。
操作者设置
要赋予你的实体金融能力：
- 1. 设置一个兼容NWC的钱包（Alby、Mutiny、Coinos等）
- 从钱包设置中生成一个NWC连接字符串——查找“Nostr Wallet Connect”或“NWC”
- 在你的实体运行环境中设置环境变量：
bash
export NWCCONNECTIONSTRING=nostr+walletconnect://walletpubkey...?relay=wss://relay.example.com&secret=hexsecret...
连接字符串是一个秘密。请像对待私钥一样对待它。任何拥有此字符串的人都可以从该钱包授权支付。
可选配置：
bash
export NWC_TIMEOUT=60 # 等待钱包响应的秒数（默认：30）
安装
bash
pip install nostrwalletconnect
这也会将nostrkey（Nostr身份SDK）作为依赖项安装。
核心功能
检查余额
在做任何事情之前，先了解你拥有什么：
python
import os
from nostrwalletconnect import NWCClient
connectionstring = os.environ[NWCCONNECTION_STRING]
async with NWCClient(connection_string) as nwc:
balance = await nwc.get_balance()
print(f余额: {balance.balance} 毫聪 ({balance.balance / 1000:.0f} 聪))
支付闪电发票
python
async with NWCClient(connection_string) as nwc:
result = await nwc.pay_invoice(lnbc10u1p...)
print(f已支付。原像: {result.preimage})
创建闪电发票
向他人请求付款：
python
async with NWCClient(connection_string) as nwc:
invoice = await nwc.make_invoice(
amount=50_000, # 毫聪（50 聪）
description=为Johnny5完成的工作
)
print(f发票: {invoice.invoice})
print(f支付哈希: {invoice.payment_hash})
检查发票是否已支付
python
async with NWCClient(connection_string) as nwc:
status = await nwc.lookupinvoice(paymenthash=abc123...)
print(f已支付: {status.paid})
列出交易历史
python
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} 毫聪 — {tx.description})
获取钱包信息
python
async with NWCClient(connection_string) as nwc:
info = await nwc.get_info()
print(f钱包: {info.alias})
print(f支持的方法: {info.methods})
方法参考
| 任务 | 方法 | 返回 |
|---|
| 检查钱包余额 | getbalance() | BalanceResponse（毫聪） |
| 支付闪电发票 |
payinvoice(bolt11) | PayResponse（原像） |
| 创建收款发票 | make_invoice(amount, desc) | MakeInvoiceResponse（bolt11 + 哈希） |
| 检查发票是否已支付 | lookup_invoice(hash) | LookupInvoiceResponse（支付状态） |
| 查看交易历史 | list_transactions() | ListTransactionsResponse |
| 检查钱包能力 | get_info() | GetInfoResponse（别名、方法） |
响应类型
BalanceResponse
PayResponse
| 字段 | 类型 | 描述 |
|---|
| preimage | str | 支付原像（支付证明） |
MakeInvoiceResponse
| 字段 | 类型 | 描述 |
|---|
| invoice | str | BOLT11发票字符串 |
| payment_hash |
str | 十六进制编码的支付哈希 |
LookupInvoiceResponse
| 字段 | 类型 | 描述 |
|---|
| invoice | str | BOLT11发票字符串 |
| paid |
bool | 发票是否已支付 |
| preimage | str \| None | 如果已支付，则为支付原像 |
ListTransactionsResponse
| 字段 | 类型 | 描述 |
|---|
| transactions | list[Transaction] | 交易记录列表 |
Transaction
| 字段 | 类型 | 描述 |
|---|
| type | str | incoming 或 outgoing |
| invoice |
str | BOLT11发票字符串 |
| amount | int | 金额（毫聪） |
| fees_paid | int | 已支付费用（毫聪） |
| created_at | int | Unix时间戳 |
| settled_at | int \| None | 结算时间戳 |
| payment_hash | str | 十六进制编码的支付哈希 |
| preimage | str | 支付原像 |
| description | str | 支付描述 |
GetInfoResponse
| 字段 | 类型 | 描述 |
|---|
| alias | str | 钱包别名/显示名称 |
| color |
str | 钱包颜色 |
| pubkey | str | 钱包公钥 |
| network | str | 网络（例如主网） |
| block_height | int | 当前区块高度 |
| block_hash | str | 当前区块哈希 |
| methods | list[str] | 支持的NIP-47方法 |
NSE集成
当此技能通过NSE编排器连接时，金融操作会根据你的关系和社会背景进行交叉检查。编排器可以在批准支付前咨询你的社会对齐指南针，并通过你的NostrCalendar验证支付是否对应计划中的承诺。金融并非孤立运作——它是一个连贯实体的一个维度。
负责任的金融意识
金融能力承载着责任。一些诚信运作的原则：
- - 支付前检查余额。 不要尝试你无法覆盖的支付。
- 验证发票详情。 在调用payinvoice前，确认金额和描述与预期相符。
- 对大额进行升级处理。 如果支付金额超出你操作环境的正常范围，在继续前将其上报给你的操作者。你可以检查getbalance()并将发票金额与你设定的阈值进行比较。
- 保留记录。 使用list_transactions()保持对你金融活动的了解。
- 金额单位为毫聪。 1聪 = 1,000毫聪。除以1,000得到聪。
常见模式
异步上下文管理器
所有方法都是异步的。始终使用async with确保WebSocket连接正确打开和关闭：
python
async with NWCClient(connection_string) as nwc:
balance = await nwc.get_balance()
result = await nwc.pay_invoice(lnbc10u1p...)
超时处理
默认超时为30秒。对于较慢的钱包或高延迟中继：
python
async with NWCClient(
