aibtc-bitcoin-wallet

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AIBTC Bitcoin Wallet

AIBTC Bitcoin钱包

A skill for managing Bitcoin L1 wallets with optional Pillar smart wallet and Stacks L2 DeFi capabilities.

一款用于管理比特币L1钱包的技能，可选支持Pillar智能钱包及Stacks L2去中心化金融功能。

Install

安装

One-command installation:

bash

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

For testnet:

bash

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

一键安装：

bash

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

测试网安装：

bash

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

Quick Start

快速开始

Check Balance

查询余额

Get your Bitcoin balance:

"What's my BTC balance?"

Uses

get_btc_balance

- returns total, confirmed, and unconfirmed balances.

查询你的比特币余额：

"我的BTC余额是多少？"

使用

get_btc_balance

工具——返回总余额、已确认余额和未确认余额。

Check Fees

查询手续费

Get current network fee estimates:

"What are the current Bitcoin fees?"

Uses

get_btc_fees

- returns fast (~10 min), medium (~30 min), and slow (~1 hr) rates in sat/vB.

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

"当前比特币手续费是多少？"

使用

get_btc_fees

工具——返回快速（约10分钟）、中等（约30分钟）、慢速（约1小时）三个档位的费率，单位为sat/vB。

Send BTC

发送BTC

Transfer Bitcoin to an address:

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

Uses

transfer_btc

- requires an unlocked wallet.

向指定地址转账比特币：

"向bc1q...发送50000聪"
"以快速手续费向bc1q...转账0.001 BTC"

使用

transfer_btc

工具——需要钱包处于解锁状态。

Wallet Setup

钱包设置

Before sending transactions, set up a wallet:

Create new wallet:
```
wallet_create
```
- generates encrypted BIP39 mnemonic
Import existing:
```
wallet_import
```
- import from mnemonic phrase
Unlock for use:
```
wallet_unlock
```
- required before transactions

Wallets are stored encrypted at

~/.aibtc/

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

创建新钱包：
```
wallet_create
```
——生成加密的BIP39助记词
导入现有钱包：
```
wallet_import
```
——通过助记词导入钱包
解锁钱包：
```
wallet_unlock
```
——交易前必须执行此操作

钱包将加密存储在

~/.aibtc/

目录下。

Tool Reference

工具参考

Read Operations

只读操作

Tool	Description	Parameters
`get_btc_balance`	Get BTC balance	`address` (optional; requires unlocked wallet if omitted)
`get_btc_fees`	Get fee estimates	None
`get_btc_utxos`	List UTXOs	`address` (optional; requires unlocked wallet if omitted), `confirmedOnly`

工具	描述	参数
`get_btc_balance`	查询BTC余额	`address` （可选；若省略则需要钱包处于解锁状态）
`get_btc_fees`	获取手续费预估	无
`get_btc_utxos`	列出UTXO	`address` （可选；若省略则需要钱包处于解锁状态）， `confirmedOnly`

Write Operations (Wallet Required)

写入操作（需钱包）

Tool	Description	Parameters
`transfer_btc`	Send BTC	`recipient` , `amount` (sats), `feeRate`

工具	描述	参数
`transfer_btc`	发送BTC	`recipient` , `amount` （单位：聪）, `feeRate`

Wallet Management

钱包管理

Tool	Description
`wallet_create`	Generate new encrypted wallet
`wallet_import`	Import wallet from mnemonic
`wallet_unlock`	Unlock wallet for transactions
`wallet_lock`	Lock wallet (clear from memory)
`wallet_list`	List available wallets
`wallet_switch`	Switch active wallet
`wallet_status`	Get wallet/session status

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

Units and Addresses

单位与地址

Amounts: Always in satoshis (1 BTC = 100,000,000 satoshis)

Addresses:

Mainnet:
```
bc1...
```
(native SegWit)
Testnet:
```
tb1...
```

Fee Rates:

"fast"

"medium"

"slow"

, or custom sat/vB number

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

地址：

主网：
```
bc1...
```
（原生隔离见证）
测试网：
```
tb1...
```

费率：可选择

"fast"

、

"medium"

、

"slow"

，或自定义sat/vB数值

Example Workflows

示例工作流

Daily Balance Check

每日余额查询

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

1. "我的BTC余额是多少？"
2. "显示我最近的UTXO"
3. "当前手续费是多少？"

Send Payment

发送付款

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

1. "解锁我的钱包"（输入密码）
2. "向bc1qxyz...发送100000聪，使用中等手续费"
3. "锁定我的钱包"

Multi-Wallet Management

多钱包管理

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

1. "列出我的钱包"
2. "切换到交易钱包"
3. "解锁它"
4. "查询余额"

Progressive Layers

渐进式扩展层

This skill focuses on Bitcoin L1. Additional capabilities are organized by layer:

本技能聚焦于比特币L1。额外功能按层级划分：

Stacks L2 (Layer 2)

Stacks L2（第二层）

Bitcoin L2 with smart contracts and DeFi:

STX token transfers
ALEX DEX token swaps
Zest Protocol lending/borrowing
x402 paid API endpoints (AI, storage, utilities) — safe-by-default with probe-before-pay workflow

See: references/stacks-defi.md

支持智能合约与去中心化金融的比特币L2：

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

详见：references/stacks-defi.md

Pillar Smart Wallet (Layer 3)

Pillar智能钱包（第三层）

sBTC smart wallet with yield automation:

Passkey or agent-signed transactions
Send to BNS names (alice.btc)
Auto-boost yield via Zest Protocol

See: references/pillar-wallet.md

具备收益自动化功能的sBTC智能钱包：

密钥或Agent签名交易
支持发送至BNS名称（如alice.btc）
通过Zest Protocol自动提升收益

详见：references/pillar-wallet.md

Bitcoin Inscriptions

比特币铭文

Inscribe and retrieve digital artifacts on Bitcoin:

Commit-reveal inscription workflow
Get inscription content and metadata
Protect ordinal UTXOs from accidental spending

See: references/inscription-workflow.md

在比特币上铭刻与检索数字资产：

提交-揭示铭文流程
获取铭文内容与元数据
保护序数UTXO避免意外花费

详见：references/inscription-workflow.md

x402 Paid APIs

x402付费API

Pay-per-use APIs with automatic micropayments on Stacks L2:

Discover available endpoints with
```
list_x402_endpoints
```
Check cost before paying with
```
probe_x402_endpoint
```
Execute endpoints with
```
execute_x402_endpoint
```
(safe-by-default — probes first)
Send inbox messages with
```
send_inbox_message
```
(use this instead of execute_x402_endpoint for inbox)

Build new x402 APIs with

scaffold_x402_endpoint

and

scaffold_x402_ai_endpoint

Always probe before executing paid endpoints. Never call

execute_x402_endpoint

with

autoApprove: true

without checking cost first.

send_inbox_message — dedicated tool for aibtc.com inbox messages:

Parameters:

recipientBtcAddress

(bc1...),

recipientStxAddress

(SP...),

content

(max 500 chars),

paymentTxid

(optional)

Uses sponsored transactions: sender pays only the sBTC message cost, relay covers STX gas
Avoids sBTC settlement timeout issues that affect the generic execute_x402_endpoint tool
Implements the full 5-step x402 v2 payment flow with balance pre-check
paymentTxid (optional): provide a confirmed on-chain sBTC transfer txid to skip the x402 flow and deliver the message using that txid as payment proof — use for manual recovery when a settlement timeout left the sBTC payment confirmed on-chain but the message undelivered
Automatic recovery: if retries are exhausted, the tool checks whether any submitted payment txid confirmed on-chain and, if so, resubmits the message automatically — no agent action required

See: references/stacks-defi.md for endpoint catalog See: references/x402-inbox.md for inbox-specific flow details

在Stacks L2上自动完成微支付的按次付费API：

使用
```
list_x402_endpoints
```
发现可用端点
使用
```
probe_x402_endpoint
```
在支付前查询成本
使用
```
execute_x402_endpoint
```
执行端点（默认安全——先探测）
使用
```
send_inbox_message
```
发送收件箱消息（替代execute_x402_endpoint用于收件箱场景）

使用

scaffold_x402_endpoint

和

scaffold_x402_ai_endpoint

构建新的x402 API

执行付费端点前务必先探测。未查询成本前，切勿使用

autoApprove: true

调用

execute_x402_endpoint

。

send_inbox_message —— 专为aibtc.com收件箱消息设计的工具：

参数：
```
recipientBtcAddress
```
（格式：bc1...）,
```
recipientStxAddress
```
（格式：SP...）,
```
content
```
（最大500字符）,
```
paymentTxid
```
（可选）
使用赞助交易：发送方仅需支付sBTC消息费用，中继方承担STX Gas费
避免了通用execute_x402_endpoint工具存在的sBTC结算超时问题
实现完整的5步x402 v2支付流程，并包含余额预检查
paymentTxid（可选）：提供已确认的链上sBTC转账交易ID，可跳过x402流程，直接使用该交易ID作为支付凭证交付消息——用于结算超时导致sBTC支付已上链但消息未送达时的手动恢复
自动恢复：若重试次数耗尽，工具会检查是否有已提交的支付交易ID已上链确认，若是则自动重新提交消息——无需Agent干预

详见：references/stacks-defi.md获取端点目录详见：references/x402-inbox.md获取收件箱专属流程细节

Genesis Lifecycle

Genesis生命周期

Agent identity and reputation on Bitcoin and Stacks:

L0: Local agent key generation
L1: Dual-chain plain-message signatures (btc_sign_message + stacks_sign_message)
L2: X claim + BTC airdrop activation
L3: On-chain identity registration via ERC-8004 (register_identity)
L4: Reputation bootstrapping (get_reputation, give_feedback)
Active: 5-minute check-ins to maintain reputation and liveness

See: references/genesis-lifecycle.md

比特币与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

Troubleshooting

故障排除

"Wallet not unlocked"

"钱包未解锁"

Run

wallet_unlock

with your password before sending transactions.

发送交易前，请执行

wallet_unlock

并输入密码。

"Insufficient balance"

"余额不足"

Check

get_btc_balance

- you need enough BTC for amount + fees.

调用

get_btc_balance

查询——你需要足够的BTC来覆盖金额+手续费。

"Invalid address"

"无效地址"

Ensure address matches network:

Mainnet: starts with
```
bc1
```
Testnet: starts with
```
tb1
```

See: references/troubleshooting.md

确保地址与网络匹配：

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

详见：references/troubleshooting.md

aibtc-bitcoin-wallet

Original

Translation

AIBTC Bitcoin Wallet

AIBTC Bitcoin钱包

Install

安装

Quick Start

快速开始

Check Balance

查询余额

Check Fees

查询手续费

Send BTC

发送BTC

Wallet Setup

钱包设置

Tool Reference

工具参考

Read Operations

只读操作

Write Operations (Wallet Required)

写入操作（需钱包）

Wallet Management

钱包管理

Units and Addresses

单位与地址

Example Workflows

示例工作流

Daily Balance Check

每日余额查询

Send Payment

发送付款

Multi-Wallet Management

多钱包管理

Progressive Layers

渐进式扩展层

Stacks L2 (Layer 2)

Stacks L2（第二层）

Pillar Smart Wallet (Layer 3)

Pillar智能钱包（第三层）

Bitcoin Inscriptions

比特币铭文

x402 Paid APIs

x402付费API

Genesis Lifecycle

Genesis生命周期

Troubleshooting

故障排除

"Wallet not unlocked"

"钱包未解锁"

"Insufficient balance"

"余额不足"

"Invalid address"

"无效地址"

More Information

更多信息