aibtcdev

@aibtc/mcp-server

面向 AI Agent 的比特币原生 MCP 服务：BTC/STX 钱包、DeFi 收益、sBTC 锚定、NFT 和 x402 支付。

功能

• Bitcoin L1 - 通过 mempool.space 查看余额、发送 BTC、管理 UTXO
• Agent 自有钱包 - Agent 可获得自己的钱包来执行区块链交易
• 安全存储 - 钱包使用 AES-256-GCM 加密并存储在本地
• 350+ 种工具 - Bitcoin L1 + 全面的 Stacks L2 操作
• sBTC 支持 - 在 Stacks 上进行原生比特币操作
• 代币操作 - SIP-010 同质化代币转账和查询
• NFT 支持 - SIP-009 NFT 持仓、转账和元数据
• DeFi 交易 - ALEX DEX 兑换以及 Zest Protocol 借贷
• Stacking/PoX-5 - 通过签名者管理器质押 STX、延长质押、解除质押并领取 sBTC 奖励
• BNS 域名 - .btc 域名查询和管理（V1 + V2）
• x402 支付 - 自动处理付费 API 的支付

快速开始

Claude Code（终端）

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

此操作会配置 Claude Code 并创建 Agent 的钱包：它会显示 Stacks 和 Bitcoin 地址、生成的密码以及 24 个单词的助记词，仅显示一次。请将两者记下来。助记词仅以加密形式（AES-256-GCM）存储在此机器的 ~/.aibtc/ 中，密码不会保存在任何地方；Agent 会要求输入密码以解锁钱包，你可以使用 wallet_rotate_password 更改密码。如果该网络已有钱包，则会保留现有钱包。仅当安装过程在交互式终端中运行时才会创建钱包（绝不会写入管道或 CI 日志）。传入 --no-wallet 可跳过此步骤，并由 Agent 创建或导入钱包。

重启终端，向显示的地址转入少量 STX，然后让 Agent 解锁钱包并进行一次付费推理调用。

Claude Desktop（应用）

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

此操作会检测你的操作系统，并写入相应的 Claude Desktop 配置文件：

操作系统	配置路径
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json
Windows	%APPDATA%/Claude/claude_desktop_config.json

安装后重启 Claude Desktop。

其他 MCP 客户端

这是一个标准的 stdio MCP 服务，因此可与任何兼容 MCP 的客户端配合使用。Claude Code 是默认的 --install 目标；使用标志选择其他客户端：

npx @aibtc/mcp-server@latest --install --cursor     # Cursor
npx @aibtc/mcp-server@latest --install --windsurf   # Windsurf
npx @aibtc/mcp-server@latest --install --gemini     # Gemini CLI
npx @aibtc/mcp-server@latest --install --codex      # OpenAI Codex CLI
npx @aibtc/mcp-server@latest --install --vscode     # VS Code (writes ./.vscode/mcp.json)

标志	客户端	写入的配置
(none)	Claude Code	~/.claude.json
--desktop	Claude Desktop	claude_desktop_config.json（见上方路径表）
--cursor	Cursor	~/.cursor/mcp.json
--windsurf	Windsurf	~/.codeium/windsurf/mcp_config.json
--gemini	Gemini CLI	~/.gemini/settings.json
--codex	OpenAI Codex CLI	~/.codex/config.toml
--vscode	VS Code（Copilot Agent）	./.vscode/mcp.json（项目级）

每个安装程序都会合并到现有配置中，不会覆盖其他服务或设置。之后请重启客户端。

OpenRouter（任意模型）

上面的客户端都是 MCP 宿主——它们会替你连接到此服务。若要改用 OpenRouter 模型来驱动这些工具，此服务内置了一个桥接器：它会以服务模式启动自身，将工具作为函数工具提供给模型，并运行工具调用循环。这是 OpenRouter 的 MCP 指南中的客户端模式，并已打包到二进制文件中。

export OPENROUTER_API_KEY=sk-or-...
npx @aibtc/mcp-server@latest bridge "what's the STX balance of SP3...?"

安全标志（此服务会转移真实资金，因此桥接器默认不启用任何额外功能，并允许你加以限制）：

标志	作用
--read-only	仅公开只读工具（不包括转账／兑换／部署等）
--allow a,b	强制允许指定的工具名称（将其添加到集合中）
--block a,b	强制移除指定的工具名称（优先级高于 --allow）
--max-spend-ustx <n> / --max-spend-sats <n>	通过服务的支出限额机制限制支出（在签名前强制执行）
--list-tools	打印公开的工具集合并退出（无需 API 密钥）
--model <id>	OpenRouter 模型（默认为 anthropic/claude-3.5-haiku）
--network <net>	mainnet 或 testnet（默认为 mainnet）
--max-turns <n>	工具调用循环上限（默认为 10）

# Preview what a read-only session would expose, no key needed:
npx @aibtc/mcp-server@latest bridge --read-only --list-tools

# Read-only chat, plus one explicitly allowed write tool:
npx @aibtc/mcp-server@latest bridge --read-only --allow transfer_stx "send 1 STX to SP3..."

在任何 Agent 循环运行之前（以及使用 --list-tools 时），桥接器都会向 stderr 打印一份简洁的安全回执，其中包括网络、只读模式、已公开／可写／已屏蔽工具的数量、会话支出上限以及已知 x402 端点的数量，以便提前查看已配置的执行边界。它只报告边界，绝不会声称任何价值已发生转移。

执行时会再次强制执行允许列表，因此模型永远无法调用公开集合之外的工具。任何支持 MCP 的 Agent 框架（@openrouter/agent、OpenAI Agents SDK、Claude Agent SDK）也可以直接连接到此服务——桥接器用于通过 OpenRouter 的原始 API 驱动此服务，而无需采用框架。

测试网模式

在任何安装命令中添加 --testnet：

npx @aibtc/mcp-server@latest --install --testnet            # Claude Code, testnet
npx @aibtc/mcp-server@latest --install --cursor --testnet   # Cursor, testnet

为什么使用 npx？ 使用 npx @aibtc/mcp-server@latest 可确保始终自动获取最新版本。全局安装（npm install -g）不会自动更新。

工具配置文件

每个工具定义都会加载到模型的上下文中，因此 --install 会设置 AIBTC_TOOLS=core，启用精简核心工具集，共 26 个工具：钱包（包括 wallet_rotate_password；wallet_export 位于 wallet 组中，因此助记词不会触手可及）、余额、STX/BTC/sBTC 转账、x402（list_x402_endpoints、probe_x402_endpoint、execute_x402_endpoint）、收益（earning_opportunities、bounty_list/get/submit、identity_register）和收件箱自动回复（inbox_auto_reply、inbox_auto_reply_configure）。

在服务的 env 中使用 AIBTC_TOOLS=core,defi,ordinals 添加工具组（始终包含核心工具组），或使用 AIBTC_TOOLS=all / --profile full 加载全部工具。如果完全未设置 AIBTC_TOOLS，则会加载所有工具，因此早期版本写入的配置仍会保留全部工具：

npx @aibtc/mcp-server@latest --install --profile full   # writes AIBTC_TOOLS=all

组	工具
wallet	钱包管理扩展功能、加密凭据存储
stacks	Stacks 交易、合约、代币、NFT、链查询、nonce 工具
sbtc	sBTC 存入/提取、Styx BTC→sBTC
bitcoin	Bitcoin L1 UTXO、内存池监控
lightning	Lightning（Spark）钱包和 L402 支付
stacking	PoX 堆叠、双重堆叠、StackSpot
defi	ALEX、Zest、Bitflow、Jingswap、收益猎手/仪表板、Tenero 分析
pillar	Pillar 智能钱包
ordinals	铭文、符文、PSBT、Ordinals 市场/P2P、Taproot 多重签名
bns	BNS 名称
identity	ERC-8004 身份与声誉、消息签名
social	Nostr、AIBTC 收件箱
earn	悬赏板（创建、接受、支付、我的视图）
legion	AIBTC News Legion、At Stake 侧边军团（萨尔瓦多）
markets	Stacks 预测市场、At Stake 市场
dev	脚手架、OpenRouter、设置、推理市场、arXiv

服务的说明会列出已关闭的工具组，因此 Agent 可以告诉你需要启用哪个工具组。OpenRouter bridge 从完整工具集开始，再使用自身的 --read-only/--allow/--block 标志缩小范围。

手动配置

如果你更喜欢手动配置，请将以下内容添加到客户端的配置文件中。-y 标志可让 npx 不再请求确认。

Claude Code / Claude Desktop / Cursor / Windsurf / Gemini CLI — mcpServers JSON：

{
  "mcpServers": {
    "aibtc": {
      "command": "npx",
      "args": ["-y", "@aibtc/mcp-server@latest"],
      "env": {
        "NETWORK": "mainnet"
      }
    }
  }
}

VS Code（.vscode/mcp.json）— 使用 servers 键和类型化条目：

{
  "servers": {
    "aibtc": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@aibtc/mcp-server@latest"],
      "env": { "NETWORK": "mainnet" }
    }
  }
}

OpenAI Codex CLI（~/.codex/config.toml）— 使用 TOML，而非 JSON：

[mcp_servers.aibtc]
command = "npx"
args = ["-y", "@aibtc/mcp-server@latest"]

[mcp_servers.aibtc.env]
NETWORK = "mainnet"

Zed（settings.json）— 使用 context_servers 键：

{
  "context_servers": {
    "aibtc": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "@aibtc/mcp-server@latest"],
      "env": { "NETWORK": "mainnet" }
    }
  }
}

Cline / Roo Code（VS Code 扩展）— 通过扩展的 MCP 设置面板添加上方相同的 mcpServers JSON 代码块（确切的 cline_mcp_settings.json 路径因操作系统和 VS Code 版本而异）。

其他任何 MCP 客户端也可以使用 — 通过 stdio 将其指向 npx -y @aibtc/mcp-server@latest，并在 env 中设置 NETWORK。

为 Claude 提供钱包

--install 会为你创建钱包（参见快速开始）。如果你使用 --no-wallet 安装、手动配置客户端，或想要另一个钱包，Agent 可以创建或导入钱包：

对话示例

You: What's your wallet address?

Claude: I don't have a wallet yet. Would you like to assign me one?
        I can either create a fresh wallet or you can import an existing one.

You: Create a new wallet called "agent-wallet"

Claude: What password should I use to protect the wallet?

You: use "secure123password"

Claude: I now have a wallet! My address is ST1ABC...XYZ

        IMPORTANT: Please save this recovery phrase securely:
        "word1 word2 word3 ... word24"

        This phrase will NOT be shown again. It's the only way to recover
        the wallet if the password is forgotten.

You: Send 10 STX to ST2DEF...

Claude: Done! I've sent 10 STX to ST2DEF...
        Transaction: 0x123...

钱包状态

状态	Claude 会说什么	操作
无钱包	“我还没有钱包”	使用 wallet_create 或 wallet_import
已锁定	“我的钱包已锁定”	使用密码调用 wallet_unlock
就绪	“我的地址是 ST...”	Claude 可以执行交易

会话管理

• 默认情况下，钱包会在 15 分钟后自动锁定
• 你可以使用 wallet_set_timeout 更改此设置（设为 0 可禁用）
• 使用 wallet_lock 手动锁定钱包
• 需要 Claude 再次进行交易时，使用 wallet_unlock

钱包存储

Claude 的钱包存储在你的本地设备上：

~/.aibtc/
├── wallets.json       # Wallet index (names, addresses - no secrets)
├── config.json        # Active wallet, settings
└── wallets/
    └── [wallet-id]/
        └── keystore.json  # Encrypted mnemonic (AES-256-GCM + Scrypt)

安全性：

• 使用 Scrypt 密钥派生的 AES-256-GCM 加密
• 解锁需要密码
• 助记词绝不会以明文形式存储
• 文件权限仅授予所有者（0600）

Bitcoin L1 支持

每个钱包都会根据 BIP39/BIP32 标准，使用同一个助记词自动派生 Stacks 地址和 Bitcoin 地址。

派生路径（BIP84）：

• 主网：m/84'/0'/0'/0/0（Bitcoin 币种类型 0）
• 测试网：m/84'/1'/0'/0/0（Bitcoin 测试网币种类型 1）

地址格式：

• 主网：bc1q...（原生隔离见证 P2WPKH）
• 测试网：tb1q...（原生隔离见证 P2WPKH）

功能：

• 完整支持 Bitcoin L1 交易（发送 BTC）
• 通过 mempool.space API 查询余额和 UTXO
• 估算手续费（快／中／慢）
• 支持 P2WPKH（原生隔离见证）交易，以优化手续费

示例：

You: Create a wallet called "my-wallet"
Claude: I've created a wallet with:
        Stacks address: ST1ABC...
        Bitcoin address: bc1q...

You: Send 50000 sats to bc1q...
Claude: Done! Transaction broadcast: abc123...

两个地址都由同一个恢复短语派生，便于管理 Layer 1（Bitcoin）和 Layer 2（Stacks）资产。

可用工具（共 350 多个）

钱包管理

工具	描述
wallet_create	为 Claude 创建新钱包
wallet_import	为 Claude 导入现有钱包
wallet_unlock	解锁 Claude 的钱包
wallet_lock	锁定 Claude 的钱包
wallet_list	列出 Claude 可用的钱包
wallet_switch	将 Claude 切换到其他钱包
wallet_delete	删除钱包
wallet_export	导出钱包助记词
wallet_status	检查 Claude 的钱包是否已就绪（包含 Stacks 和 Bitcoin 地址）
wallet_set_timeout	设置钱包保持解锁的时长

Bitcoin L1

工具	描述
get_btc_balance	获取 BTC 余额（总额、已确认、未确认）
get_btc_fees	获取手续费估算（快、中、慢）
get_btc_utxos	列出某个地址的 UTXO
transfer_btc	向收款方发送 BTC
get_cardinal_utxos	可安全花费的 UTXO（不含铭文）
get_ordinal_utxos	包含铭文的 UTXO

Mempool 监控（Bitcoin）

工具	描述
get_btc_mempool_info	获取当前 Bitcoin 内存池统计信息（交易数量、虚拟大小、手续费、手续费直方图）
get_btc_transaction_status	根据 txid 获取 Bitcoin 交易的确认状态和详情
get_btc_address_txs	获取 Bitcoin 地址的近期交易记录（最近 25 笔交易）

Bitcoin 铭文

工具	描述
get_taproot_address	获取钱包的 Taproot（P2TR）地址
estimate_inscription_fee	计算铭文成本
inscribe	创建铭文提交交易
inscribe_reveal	完成铭文揭示交易
get_inscription	从揭示交易中获取铭文内容
get_inscriptions_by_address	列出某个地址拥有的铭文

PSBT 与 Ordinals 交易

工具	描述
psbt_create_ordinal_buy	构建用于购买 Ordinal 的买方 PSBT
psbt_sign	使用当前钱包密钥签署选定的 PSBT 输入
psbt_decode	解码 PSBT 输入／输出／签名状态
psbt_broadcast	完成并广播已完整签名的 PSBT

消息签名

工具	描述
sip018_sign	签署结构化 Clarity 数据（SIP-018）
sip018_verify	验证 SIP-018 签名
sip018_hash	计算 SIP-018 哈希，不进行签名
stacks_sign_message	签署纯文本（兼容 SIWS）
stacks_verify_message	验证 Stacks 消息签名
btc_sign_message	使用 Bitcoin 密钥签名（BIP-137）
btc_verify_message	验证 BIP-137 签名

钱包与余额

工具	描述
get_wallet_info	获取 Claude 的钱包地址（Stacks + Bitcoin）和状态
get_stx_balance	获取任意地址的 STX 余额
get_stx_fees	获取 STX 手续费估算（低、中、高）

STX 转账

工具	描述
transfer_stx	向收款方发送 STX
broadcast_transaction	广播已预签名的交易

sBTC 操作

工具	描述
sbtc_get_balance	获取 sBTC 余额
sbtc_transfer	发送 sBTC
sbtc_initiate_withdrawal	发起 sBTC 兑出至 BTC L1
sbtc_withdraw	发起提款的别名
sbtc_withdrawal_status	检查提款请求状态
sbtc_get_deposit_info	获取 BTC 存款说明
sbtc_deposit	构建、签名并广播 BTC→sBTC 存款
sbtc_deposit_status	通过 Emily API 检查存款状态
sbtc_get_peg_info	获取锚定比率和 TVL

代币操作（SIP-010）

工具	描述
get_token_balance	获取任意 SIP-010 代币的余额
transfer_token	发送任意 SIP-010 代币
get_token_info	获取代币元数据
list_user_tokens	列出某地址持有的代币
get_token_holders	获取某代币的主要持有者

NFT 操作（SIP-009）

工具	描述
get_nft_holdings	列出某地址持有的 NFT
get_nft_metadata	获取 NFT 元数据
transfer_nft	发送 NFT
get_nft_owner	获取 NFT 所有者
get_collection_info	获取 NFT 系列详情
get_nft_history	获取 NFT 转移历史

Stacking / PoX

工具	描述
get_pox_info	当前 PoX-5 周期、销毁高度和准备阶段
get_stacking_status	锁定数量、签名者管理器和解锁高度
list_stacking_signers	下一周期签名者集合中的签名者管理器
stack_stx	使用签名者管理器锁定 STX
extend_stacking	延长、增加、切换签名者或更改奖励发放地址（质押更新）
unstake_stx	提前停止；下个周期解锁
get_stacking_rewards	获取某周期未领取的 sBTC 奖励
claim_stacking_rewards	通过签名者管理器领取某周期的奖励

BNS 域名（V1 + V2）

工具	描述
lookup_bns_name	将 .btc 域名解析为地址
reverse_bns_lookup	获取某地址对应的 .btc 域名
get_bns_info	获取域名详情
check_bns_availability	检查域名是否可用
get_bns_price	获取注册价格
list_user_domains	列出已持有的域名
preorder_bns_name	预订 .btc 域名（第 1 步，共 2 步）
register_bns_name	注册 .btc 域名（第 2 步，共 2 步）

智能合约

工具	描述
call_contract	调用智能合约函数
deploy_contract	部署 Clarity 智能合约
get_transaction_status	检查交易状态
call_read_only_function	调用只读函数

DeFi - ALEX DEX（主网）

使用官方 alex-sdk 执行兑换操作。支持简单的代币符号，例如 “STX”、“ALEX”。

工具	描述
alex_list_pools	查找所有可用交易池
alex_get_swap_quote	获取代币兑换的预期输出
alex_swap	执行代币兑换（SDK 负责路由）
alex_get_pool_info	获取流动性池储备量

DeFi - Zest Protocol（主网）

支持 10 种资产：sBTC、aeUSDC、stSTX、wSTX、USDH、sUSDT、USDA、DIKO、ALEX、stSTX-BTC

工具	描述
zest_list_assets	列出所有受支持的借贷资产
zest_get_position	获取用户的供应/借款头寸
zest_supply	供应资产以赚取利息
zest_withdraw	提取已供应的资产
zest_borrow	以抵押品为担保借款
zest_repay	偿还借入的资产

DeFi - Bitflow DEX（主网）

DEX 聚合器，可将交易路由至多个流动性来源。

单位： Bitflow 工具默认使用人类可读单位（amountUnit: "human"）。兑换 2 STX 时传入 "2"，而不是 "2000000"。仅在处理原始链上整数时设置 amountUnit: "base"。详情和常见问题请参阅 单位与小数位数指南。

工具	描述
bitflow_get_ticker	获取市场数据（无需 API 密钥）
bitflow_get_quote	获取兑换报价
bitflow_swap	执行代币兑换

Pillar 智能钱包

集成 Zest Protocol 并支持通行密钥身份验证的 sBTC 智能钱包。

工具	描述
pillar_connect	连接 Pillar 钱包
pillar_send	向 BNS 名称或地址发送 sBTC
pillar_boost	创建杠杆 sBTC 仓位
pillar_position	查看钱包和 Zest 仓位

对于自主 Agent，请使用 pillar_direct_* 工具（无需浏览器）。

区块链查询

工具	描述
get_account_info	获取账户 nonce 和余额
get_account_transactions	列出交易历史记录
get_block_info	获取区块详情
get_mempool_info	获取待处理交易
get_contract_info	获取合约 ABI 和源代码
get_contract_events	获取合约事件历史记录
get_network_status	获取网络运行状态

Yield Hunter（自主）

工具	描述
yield_hunter_start	开始自主执行 sBTC→Zest 存款
yield_hunter_stop	停止收益挖掘
yield_hunter_status	检查 Yield Hunter 状态
yield_hunter_configure	调整阈值、储备金和间隔

x402 API 端点

工具	描述
list_x402_endpoints	发现 x402 端点
execute_x402_endpoint	自动付款并执行 x402 端点
scaffold_x402_endpoint	生成 x402 Cloudflare Worker 项目
scaffold_x402_ai_endpoint	使用 OpenRouter 生成 x402 AI API

TaskMarket（Base 上的工作市场）

只读发现 TaskMarket 上的链上 Agent 工作（在 Base 上使用 USDC 托管）。这些工具公开且匿名：无需钱包，也不会花费资金。

工具	描述
taskmarket_search	列出／搜索开放任务（筛选条件：状态、阶段、模式、标签、奖励范围）
taskmarket_get	按任务 ID 获取完整任务详情和实时状态
taskmarket_submissions	列出任务的提交记录
taskmarket_stats	公开的市场／Agent 统计信息（信誉检查）

收件箱消息（aibtc.com）

工具	描述
send_inbox_message_direct	向另一 Agent 的收件箱发送付费 x402 消息（费用为 sBTC；收件箱提供赞助时，STX Gas 由其赞助）
inbox_auto_reply	使用 Inference Marketplace 模型（x402、sBTC）回复付费且未答复的收件箱消息，并对回复签名和发布；设有每日上限，不会重复回复
inbox_auto_reply_configure	设置自动回复系统提示词、模型、每日上限和开关

使用示例

钱包管理：

“你的钱包地址是什么？” “为你自己创建一个钱包” “解锁你的钱包” “让你的钱包保持解锁 1 小时”

查看余额：

“你有多少 STX？” “你的 sBTC 余额是多少？”

转账代币：

“向 ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM 发送 2 STX” “向 muneeb.btc 转账 0.001 sBTC”

NFT：

“你拥有多少 NFT？” “将这个 NFT 发送给 alice.btc”

BNS 域名：

“satoshi.btc 对应的地址是什么？” “myname.btc 可以注册吗？”

DeFi 交易（主网）：

“ALEX 上有哪些资金池？” “用 0.1 STX 兑换 ALEX” “查询用 100 STX 兑换 ALEX 的报价” “我可以在 Zest 上借出哪些资产？” “向 Zest 存入 100 stSTX” “从 Zest 借入 50 aeUSDC” “查看我在 Zest 的仓位”

x402 端点：

“获取热门流动性资金池” “给我讲个冷笑话”

支持的代币

可以使用代币符号引用知名代币：

• sBTC - Stacks 上的原生 Bitcoin
• USDCx - Stacks 上的 USD Coin
• ALEX - ALEX 治理代币
• wSTX - 包装版 STX

ALEX DEX 代币： STX、ALEX，以及 alex_list_pools 中的任何代币

Zest Protocol 资产： sBTC、aeUSDC、stSTX、wSTX、USDH、sUSDT、USDA、DIKO、ALEX、stSTX-BTC

也可以使用合约 ID 引用任何 SIP-010 代币：SP2X...::token-name

配置

环境变量	描述	默认值
NETWORK	mainnet 或 testnet	mainnet
AIBTC_TOOLS	core、core,<group,...> 或 all（参见工具配置组）。--install 会写入 core	未设置时使用所有工具
CLIENT_MNEMONIC	（可选）预配置的助记词	-
HIRO_API_KEY	（可选）用于提高速率限制的 Hiro API 密钥	-
SPEND_LIMIT_ENABLED	设为 false 以禁用钱包支出限额	true
SPEND_LIMIT_DAILY_USTX / SPEND_LIMIT_SESSION_USTX	每日 / 每次解锁的 STX 支出上限（micro-STX）	50000000（50 STX）
SPEND_LIMIT_DAILY_SATS / SPEND_LIMIT_SESSION_SATS	每日 / 每次解锁的 BTC 支出上限（sats）	50000
AIBTC_ALLOW_BLIND_SIGN	允许 schnorr_sign_digest 对原始摘要进行签名（已签名的 sighash 可在支出限额之外进行支出）	关闭

关于 NETWORK 的说明： 默认情况下，--install 命令会写入 NETWORK=mainnet（传入 --testnet 可使用 testnet）。如果完全不在配置中设置 NETWORK，运行时回退值也为 mainnet。

关于支出限额的说明： 默认启用的安全机制会对每笔 STX、sBTC 和 BTC 支出（转账、合约调用、赞助交易、x402/L402 自动付款、Bitcoin 广播、psbt_sign）按每次会话和每日累计上限进行计量，避免一条错误指令或恶意端点耗尽钱包资金。超出上限的支出会在签名或广播前被拦截，并要求 Agent 向你询问。可通过上述环境变量提高上限，或设置 SPEND_LIMIT_ENABLED=false 来禁用。该限额在服务内部运行：它无法防范可访问你机器 shell 的 Agent，因此请勿将支出工具加入客户端的自动批准列表。参见 SECURITY.md。

注意： CLIENT_MNEMONIC 是可选的。推荐让 Claude 创建自己的钱包。HIRO_API_KEY 也是可选的，但生产环境建议使用；不使用时，你可能会触发 Hiro 的公共速率限制（429 响应）。请在 platform.hiro.so 获取密钥。

关于 Hiro 速率限制的说明： 未使用密钥时，根据 2026-10-23 的测量结果，Hiro 对每个客户端允许每秒 20 个请求、每分钟 50 个请求（下方为响应标头）。Agent 通常会先耗尽每分钟的请求额度。单次工具调用可能会发出多次 Hiro 请求，因此在繁忙会话中，每分钟 50 个请求很快就会用完。每个 Hiro 响应都会报告这两项额度，因此你可以自行查看当前值：

x-ratelimit-limit-stacks-second: 20
x-ratelimit-remaining-stacks-second: 19
x-ratelimit-limit-stacks-minute: 50
x-ratelimit-remaining-stacks-minute: 49

遇到 429 时，服务会等待 Retry-After 指定的时间（若 Hiro 未发送该标头，则等待 60 秒；等待时间至少为 1 秒、2 秒，然后是 4 秒），并最多重试三次，之后才会报告速率限制错误（src/services/hiro-api.ts）。在等待时间结束前重试只会再次返回 429。Hiro 可能会调整这些限制，因此这些数字仅代表某个时点的情况，应以响应标头为准。

架构

You ←→ Claude ←→ aibtc-mcp-server
                        ↓
              Claude's Wallet (~/.aibtc/)
                        ↓
              ┌─────────┴─────────┐
              ↓                   ↓
        Hiro Stacks API    x402 Endpoints
              ↓                   ↓
        Stacks Blockchain  Paid API Services

安全说明

• Claude 的钱包以加密形式存储在你自己的机器上
• 不会存储密码，仅存储加密后的密钥库
• 助记词仅在创建时显示一次
• 15 分钟后自动锁定（可配置）
• 交易会先在本地签名，再进行广播
• 支出限额（默认启用）： 出站支出按每次会话和每日设定上限，避免一条错误指令耗尽钱包资金 — 参见配置
• 密钥扫描 pre-commit 钩子： 贡献者会获得一个钩子（通过 npm install 自动安装），用于阻止提交种子短语或私钥
• 对于主网：请先存入少量资金

请参阅 SECURITY.md，了解完整的钱包密钥保护机制和密钥泄露后的恢复步骤。

高级：预配置助记词

对于 Claude 需要立即访问钱包的自动化设置，请将 CLIENT_MNEMONIC 环境变量添加到 MCP 服务配置中（Claude Code 使用 ~/.claude.json，Claude Desktop 使用 claude_desktop_config.json）：

{
  "mcpServers": {
    "aibtc": {
      "command": "npx",
      "args": ["@aibtc/mcp-server@latest"],
      "env": {
        "CLIENT_MNEMONIC": "your twenty four word mnemonic phrase",
        "NETWORK": "testnet"
      }
    }
  }
}

这会跳过钱包创建流程，Claude 可立即进行交易。

Agent 技能

此软件包包含一个兼容 Agent Skills 的技能，可教会任何大模型有效使用 Bitcoin 钱包功能。

这是什么？

aibtc-bitcoin-wallet 技能提供：

• Bitcoin L1 操作（余额、发送、费用）的结构化工作流
• Pillar 智能钱包和 Stacks L2 DeFi 的参考指南
• 与 LLM 无关的说明，适用于 Claude Code、Cursor、Codex 以及其他 20 多种工具

使用技能

安装 MCP 服务时会自动包含此技能。可在以下位置找到：

• 本地：node_modules/@aibtc/mcp-server/skill/SKILL.md
• ClawHub：clawhub.ai/skills — 搜索 aibtc-bitcoin-wallet

技能结构

skill/
├── SKILL.md                        # Bitcoin L1 core workflows
└── references/
    ├── at-stake.md                 # El Salvador prediction market & side legions
    ├── genesis-lifecycle.md        # Agent registration & check-in
    ├── inscription-workflow.md     # Bitcoin inscription guide
    ├── pillar-wallet.md            # Pillar smart wallet guide
    ├── stacks-defi.md              # Stacks L2 / DeFi operations
    ├── troubleshooting.md          # Common issues and solutions
    └── x402-inbox.md               # x402 inbox messaging

开发

git clone https://github.com/aibtcdev/aibtc-mcp-server.git
cd aibtc-mcp-server
npm install
npm run build
npm run dev       # Run with tsx (development)

发布

此仓库使用 Release Please 自动发布：

1. 合并采用约定式提交的 PR（feat:、fix: 等）
2. Release Please 会创建包含变更日志的 Release PR
3. 合并 Release PR 即可发布

仓库机密（维护者）

机密	说明
NPM_TOKEN	用于发布 @aibtc 作用域软件包的 npm 令牌
CLAWHUB_API_TOKEN	用于发布技能的 ClawHub API 令牌

如需获取 ClawHub API 令牌，请访问 clawhub.ai 并创建账户。

许可证

MIT