aibtc-bitcoin-wallet

AIBTC Bitcoin Wallet

用于管理 Bitcoin L1 钱包的技能，可选支持 Pillar 智能钱包和 Stacks L2 DeFi 功能。

安装

一条命令即可安装（默认使用 Claude Code）：

npx @aibtc/mcp-server@latest --install

使用标志选择其他 MCP 客户端：

npx @aibtc/mcp-server@latest --install --cursor     # Cursor
npx @aibtc/mcp-server@latest --install --codex      # OpenAI Codex CLI
npx @aibtc/mcp-server@latest --install --gemini     # Gemini CLI
npx @aibtc/mcp-server@latest --install --windsurf   # Windsurf
npx @aibtc/mcp-server@latest --install --vscode     # VS Code
npx @aibtc/mcp-server@latest --install --desktop    # Claude Desktop

要使用测试网，可在任意命令中添加 --testnet：

npx @aibtc/mcp-server@latest --install --testnet

快速入门

检查余额

获取 Bitcoin 余额：

"What's my BTC balance?"

使用 get_btc_balance，返回总余额、已确认余额和未确认余额。

检查手续费

获取当前网络手续费估算：

"What are the current Bitcoin fees?"

使用 get_btc_fees，返回快速（约 10 min）、中速（约 30 min）和慢速（约 1 hr）的费率，单位为 sat/vB。

发送 BTC

向某个地址转账 Bitcoin：

"Send 50000 sats to bc1q..."
"Transfer 0.001 BTC with fast fees to bc1q..."

使用 transfer_btc，需要已解锁的钱包。

钱包设置

发送交易前，请先设置钱包：

1. 创建新钱包：wallet_create - 生成加密的 BIP39 助记词
2. 导入现有钱包：wallet_import - 从助记词导入
3. 解锁以供使用：wallet_unlock - 进行交易前必须执行

钱包以加密形式存储在 ~/.aibtc/。

工具参考

读取操作

工具	描述	参数
get_btc_balance	获取 BTC 余额	address（可选；若省略，则需要已解锁的钱包）
get_btc_fees	获取手续费估算	无
get_btc_utxos	列出 UTXO	address（可选；若省略，则需要已解锁的钱包）、confirmedOnly

写入操作（需要钱包）

工具	描述	参数
transfer_btc	发送 BTC	recipient、amount（sats）、feeRate

钱包管理

工具	描述
wallet_create	生成新的加密钱包
wallet_import	从助记词导入钱包
wallet_unlock	解锁钱包以进行交易
wallet_lock	锁定钱包（从内存中清除）
wallet_list	列出可用钱包
wallet_switch	切换当前钱包
wallet_status	获取钱包／会话状态

消息签名

工具	描述	参数
sip018_sign	对结构化 Clarity 数据签名（SIP-018）	message、domain
sip018_verify	验证 SIP-018 签名并恢复签名者	messageHash、signature、expectedSigner（可选）
sip018_hash	计算 SIP-018 哈希，不进行签名	message、domain
stacks_sign_message	使用 Stacks 前缀对纯文本签名（兼容 SIWS）	message
stacks_verify_message	验证 Stacks 消息签名并恢复签名者	message、signature、expectedSigner（可选）
btc_sign_message	使用 Bitcoin 密钥对纯文本签名（BIP-137/BIP-322）	message、addressType（可选）
btc_verify_message	验证 Bitcoin 消息签名（自动检测 BIP-137/BIP-322）	message、signature、address（可选）
nostr_sign_event	使用 BIP-340 Schnorr 签名 Nostr 事件（NIP-01）；默认使用由 NIP-06 派生的密钥（m/44'/1237'/0'/0/0）	kind、content、tags（可选）、created_at（可选）、keySource（默认为通过 NIP-06 路径派生的 "nostr"；"taproot" 表示 P2TR 密钥；"segwit" 表示 P2WPKH 密钥）
schnorr_sign_digest	使用 Schnorr/BIP-340 对原始 32 字节摘要签名	digest、confirmBlindSign、auxRand（可选）
schnorr_verify_digest	验证摘要上的 BIP-340 Schnorr 签名	digest、signature、publicKey

单位和地址

金额：始终以聪为单位（1 BTC = 100,000,000 聪）

地址：

• 主网：bc1...（原生 SegWit）
• 测试网：tb1...

费率："fast"、"medium"、"slow"，或自定义 sat/vB 数值

工作流示例

每日余额检查

1. "What's my BTC balance?"
2. "Show my recent UTXOs"
3. "What are current fees?"

发送付款

1. "Unlock my wallet" (provide password)
2. "Send 100000 sats to bc1qxyz... with medium fees"
3. "Lock my wallet"

多钱包管理

1. "List my wallets"
2. "Switch to trading wallet"
3. "Unlock it"
4. "Check balance"

渐进式层级

此技能侧重于 Bitcoin L1。其他功能按层组织：

Stacks L2（第 2 层）

支持智能合约和 DeFi 的 Bitcoin 第 2 层：

• STX 代币转账
• ALEX DEX 代币兑换
• Zest Protocol 借贷
• x402 付费 API 端点（AI、存储、实用工具）——默认安全，采用先探测、后付款的工作流

参见：references/stacks-defi.md

Pillar Smart Wallet（第 3 层）

支持收益自动化的 sBTC 智能钱包：

• 使用 Passkey 或 Agent 签名的交易
• 发送至 BNS 名称（alice.btc）
• 通过 Zest Protocol 自动提高收益

参见：references/pillar-wallet.md

Bitcoin 铭文

在 Bitcoin 上铭刻并检索数字内容：

• 提交-揭示铭刻工作流
• 获取铭文内容和元数据
• 防止 ordinal UTXO 被意外花费

参见：references/inscription-workflow.md

x402 付费 API

在 Stacks L2 上通过自动微支付使用按次付费 API：

• 使用 list_x402_endpoints 发现可用端点
• 使用 probe_x402_endpoint 在付款前检查费用
• 使用 execute_x402_endpoint 执行端点（默认安全——先进行探测）
• 使用 send_inbox_message_direct 发送收件箱消息（收件箱消息请使用此工具，而不是 execute_x402_endpoint）
• 使用 scaffold_x402_endpoint 和 scaffold_x402_ai_endpoint 构建新的 x402 API

执行付费端点前，务必先进行探测。未经事先检查费用，切勿使用 autoApprove: true 调用 execute_x402_endpoint。

send_inbox_message_direct——用于 aibtc.com 收件箱消息的专用工具：

• 参数：recipientBtcAddress（bc1...）、recipientStxAddress（SP...）、content（最多 500 个字符）
• 直接（非赞助）付款：签署标准 sBTC 转账，并通过 x402 促成方结算——中间没有中继
• 发送方需同时支付 sBTC 消息费用和自身的 STX Gas；需要使用已解锁且持有 sBTC 和 STX 的钱包（仅限主网）
• 实现完整的 x402 v2 付款流程，并在付款前检查余额
• 注意：较早的赞助式 send_inbox_message 工具已弃用，且不再发送消息——请改用此工具

端点目录参见：references/stacks-defi.md 收件箱专属流程详情参见：references/x402-inbox.md

Genesis 生命周期

在 Bitcoin 和 Stacks 上建立 Agent 身份与声誉：

• L0：本地 Agent 密钥生成
• L1：双链明文消息签名（btc_sign_message + stacks_sign_message）
• L2：X 领取 + BTC 空投激活
• L3：通过 ERC-8004 注册链上身份（register_identity）
• L4：声誉引导（get_reputation、give_feedback）
• 活跃状态：每 5 分钟签到一次，以维持声誉和在线状态

参见：references/genesis-lifecycle.md

故障排除

“钱包未解锁”

发送交易前，请使用密码运行 wallet_unlock。

“余额不足”

检查 get_btc_balance——你需要有足够的 BTC 支付金额和费用。

“地址无效”

确保地址与网络匹配：

• 主网：以 bc1 开头
• 测试网：以 tb1 开头

参见：references/troubleshooting.md

更多信息

• CLAUDE.md - 完整工具文档
• GitHub - 源代码
• npm - 软件包

---

此技能遵循 Agent Skills 开放规范。