面向钱包、交换与付费 API 的比特币 MCP 服务器

KaleidoSwap 通过 kaleido-mcp 这一个统一服务器，把钱包、DEX 和支付能力开放给 AI 代理（Claude Desktop、KaleidoAgent、基于 KaleidoMind 的宿主，或任何其他 MCP 客户端），新集成应使用这个统一服务器。它已取代早期的独立钱包服务器；旧集成的迁移说明位于本页末尾。

需要准备什么

操作	前置条件
市场查询与报价	MCP 客户端和 Node.js；不需要种子或本地节点
RGB 钱包与 RGB 原子交换	可访问且已解锁的 RGB Lightning Node
Spark 或 Liquid 钱包	可选钱包包及其助记词
潜水艇交换	可选 swap SDK、Node.js 22+ 和已配置的付款钱包

模型通过 MCP 客户端调用工具。直接在终端启动服务器只会等待协议请求，不会打开聊天界面。

安装与配置

kaleido-mcp 已发布到 npm，这是跑通第一次工具调用的最快方式。请从 signet 开始：

KALEIDO_NETWORK=signet npx -y kaleido-mcp

本页描述的是 kaleido-mcp 0.3.0 及以上版本。0.3.0 新增了 KALEIDO_NETWORK 预设和 kaleido_node_* 生命周期工具，并移除了基于订单的交换工具，改为只使用原子交换。如果 npx 解析到了较旧的缓存版本，请运行一次 npx -y kaleido-mcp@latest，或从源码构建。

自 0.3.1 起，Spark 和 Liquid 钱包是可选的 peer 依赖，普通的 npx -y kaleido-mcp 不会安装它们。设置了 WDK_SEED 或 LIQUID_MNEMONIC 但缺少对应包时，服务器仍会启动，并输出安装提示。启用方法：

npx -y -p kaleido-mcp -p @tetherto/wdk-wallet-spark -p @kaleidorg/wdk-wallet-liquid kaleido-mcp

实际使用中由 MCP 宿主替你执行这条命令，把宿主配置指向该命令即可（见下面的客户端配置）。若用于开发，或要运行某个特定提交，请改为从源码构建：

git clone https://github.com/kaleidoswap/kaleido-mcp
cd kaleido-mcp
npm install
npm run build

无论哪种方式，服务器读取的环境变量都相同，并且默认使用 stdio 通信：

# stdio（Claude Desktop、Claude Code、KaleidoAgent 等）
KALEIDO_NETWORK=signet WDK_SEED="word1 word2 ..." node dist/index.js

# HTTP 传输
PORT=3010 KALEIDO_NETWORK=signet WDK_SEED="word1 word2 ..." node dist/index.js

网络预设

KALEIDO_NETWORK 用一个变量选定一组默认值，可取 signet（自 0.3.1 起为默认）或 mainnet：

预设	KaleidoSwap API	Spark 网络
`signet`	`https://api.signet.kaleidoswap.com`	Spark 测试网络（Spark SDK 中名为 `REGTEST`）
`mainnet`	无：把 `KALEIDOSWAP_API_URL` 设为你自己的做市商端点	`MAINNET`

预设只负责填充默认值。你显式设置的任何变量（例如 KALEIDOSWAP_API_URL 或 SPARK_NETWORK）都会覆盖它。KaleidoSwap 目前没有公开的主网 API，因此 mainnet 未设置 KALEIDOSWAP_API_URL 时，服务器会在启动时直接退出；未知取值同样如此。RLN_NODE_URL 不属于预设：请把它指向你自己的节点，在 signet 上通常就是 KaleidoCLI 运行在 http://localhost:3001 的那个节点。

环境变量	是否必需	说明
`KALEIDO_NETWORK`	否	`signet`（默认）或 `mainnet`。设置网络预设中的默认值
`WDK_SEED`	使用 Spark 工具时必需	Spark 钱包的 BIP-39 助记词，同时需要可选包 `@tetherto/wdk-wallet-spark`。两者缺一服务器仍能启动，只是 Spark 工具会被禁用
`LIQUID_MNEMONIC`	使用 Liquid 工具时必需	Liquid 钱包的 BIP-39 助记词，同时需要可选包 `@kaleidorg/wdk-wallet-liquid`
`SPARK_NETWORK`	否	覆盖预设中的 Spark 网络：`MAINNET`，或代表 Spark 测试网络的 `REGTEST`
`SPARK_SCAN_API_KEY`	否	SparkScan API 密钥
`SPARK_USDT_TOKEN`	否	默认的 Spark 代币标识符
`RLN_NODE_URL`	否	RLN 守护进程 URL，默认 `http://localhost:3001`
`KALEIDOSWAP_API_URL`	使用 `mainnet` 时必填	KaleidoSwap 做市商 API URL，覆盖预设。主网没有公开端点，因此 `mainnet` 必须设置。也接受 `KALEIDO_API_URL`
`KALEIDO_BIN`	否	`kaleido` 可执行文件的路径，供节点生命周期工具使用
`KALEIDO_NODE_URL`	否	以 `--node-url` 传给节点生命周期工具的节点 URL
`KALEIDO_API_URL`	否	以 `--api-url` 传给节点生命周期工具的 API URL，同时作为 `KALEIDOSWAP_API_URL` 的备选
`KALEIDO_ENV_NAME`	否	节点生命周期工具的默认环境名
`PORT`	否	启用 Streamable HTTP 传输，替代 stdio
`MCP_AUTH_TOKEN`	否	HTTP 模式下的 Bearer token

运行时兼容性

排查集成问题时，请核对实际安装的包版本。使用 QVAC 的 Mind 宿主需要 @qvac/sdk >=0.20.0。kaleidoswap_submarine_* 工具还需要可选的 @kaleidorg/swap-sdk 包，以及 Node.js 22 或更新版本。工具出现在目录中不代表钱包、节点或可选依赖已配置完成。 /health 成功仅表示 HTTP 进程正在运行。自动生成的 MCP 参考列出了当前参数结构。固定版本的集成应查看对应 release tag 中的参考。

遗留别名

为兼容早期集成，部分工具仍可通过旧名称调用（rln_* 对应 wdk_*，通用 get_* 对应 l402_get_* 行情工具）。新的集成应使用规范的 wdk_* / l402_* 名称。

按领域划分的工具集

下面所有工具都由 kaleido-mcp 通过同一条连接提供。🔒 图标在本文档中标记会动用资金的工具；kaleido-mcp 本身不携带确认标志，因此调用在执行前是否需要确认，取决于 MCP 宿主的行为。例外是 WDK 内置的 sendTransaction 和 transfer，它们会在广播前自行发起一次 MCP elicitation 确认。

Spark 二层钱包（spark_*）

WDK 内置工具（通过 @tetherto/wdk-mcp-toolkit，作用域限定在 spark 链）：getAddress、getBalance、getMaxSpendableBtc、sendTransaction、transfer、getTokenBalance、quoteSendTransaction、quoteTransfer、getFeeRates、sign、verify。在内置工具之上的自定义 Spark 工具：

工具	用途
`spark_get_balance`	Spark 二层钱包余额，以聪计价（转账免费）
`spark_get_address`	用于接收聪或代币的 Spark 二层地址
`spark_get_token_balance`	按代币标识符查询某个 Spark 代币（如 USDT）的余额
`spark_get_deposit_address`	将 BTC 桥接进 Spark 二层钱包的比特币一层地址
`spark_create_lightning_invoice`	通过闪电网络把 BTC 收入 Spark 的 BOLT11 发票
`spark_pay_lightning_invoice` 🔒	从 Spark 钱包支付一张 BOLT11 发票
`spark_quote_lightning_payment`	支付前预估闪电路由费
`spark_send_sats` 🔒	向另一个 Spark 二层地址发送聪（免费）
`spark_transfer_token` 🔒	把 Spark 代币（如 USDT）转到另一个地址（免费）
`spark_quote_withdraw`	协作退出提取到比特币一层的费用报价
`spark_withdraw` 🔒	从 Spark 二层提取 BTC 到比特币一层地址
`spark_get_transfers`	最近的 Spark 二层转账历史
`spark_create_sats_invoice`	用于接收 BTC 聪的 Spark 发票（`spark1...`）
`spark_create_tokens_invoice`	用于接收代币的 Spark 发票（`spark1...`）
`spark_pay_spark_invoice` 🔒	支付一张或多张 Spark 发票
`spark_get_spark_invoices`	查询一张或多张 Spark 发票的状态
`spark_mpp_pay` 🔒	从 Spark 钱包支付一个 MPP 闪电挑战

在 kaleido-mcp 中设置 WDK_SEED 并安装可选包 @tetherto/wdk-wallet-spark。SPARK_NETWORK、SPARK_SCAN_API_KEY 和 SPARK_USDT_TOKEN 可选。

RLN，即 RGB Lightning Node（wdk_，别名 rln_）

工具	用途
`wdk_get_node_info`	节点身份信息：pubkey、通道数量、闪电余额、对等节点
`wdk_get_balances`	BTC 链上余额（普通与着色 UTXO）以及闪电余额
`wdk_get_asset_balance`	按 `asset_id` 查询某个 RGB 资产（USDT、XAUT）的余额
`wdk_list_assets`	节点持有的全部 RGB 资产（NIA、UDA、CFA schema）
`wdk_get_address`	用于接收存入的链上 BTC 地址
`wdk_create_rgb_invoice`	创建一张 RGB 发票以接收 RGB 资产
`wdk_create_ln_invoice`	创建一张 BOLT11 发票，通过闪电网络接收 BTC
`wdk_pay_invoice` 🔒	支付一张 BOLT11 闪电发票
`wdk_send_btc` 🔒	链上发送 BTC
`wdk_send_asset` 🔒	链上发送 RGB 资产（USDT/XAUT）
`wdk_list_channels`	所有闪电通道：容量、余额、可用性、RGB 分配
`wdk_connect_peer`	连接到某个闪电对等节点（`pubkey@host:port`），LSPS1 购买通道前必需
`wdk_open_channel` 🔒	开通一条闪电通道，可选携带 RGB 资产分配
`wdk_close_channel` 🔒	关闭一条闪电通道（`force=true` 仅用于无响应的对等节点）
`wdk_get_channel_id`	把 `temporary_channel_id` 解析为永久的 `channel_id`
`wdk_list_payments`	最近的闪电支付，收发均含
`wdk_refresh_transfers`	同步待处理的 RGB 资产转移，在 KaleidoSwap 订单成交后调用
`wdk_atomic_taker` 🔒	原子 HTLC 交换的第 2 步，把进入的 HTLC 加入白名单
`wdk_list_swaps`	列出节点上的所有原子交换，含做市方与接单方两侧
`wdk_get_swap`	按 `payment_hash` 查询原子交换状态
`wdk_mpp_pay` 🔒	从 RLN 钱包支付一个 MPP 闪电挑战

需要一个运行中的 RGB Lightning Node，可通过 RLN_NODE_URL 访问，默认 http://localhost:3001。

KaleidoSwap DEX（kaleidoswap_*）

工具	用途
`kaleidoswap_get_assets`	可交易资产：代号、名称、精度、RGB 协议 ID
`kaleidoswap_get_pairs`	可交易的交易对及其可用的分层路由
`kaleidoswap_get_quote`	一笔交换的价格报价，返回输出数量、价格、费用和 `rfq_id`
`kaleidoswap_get_spreads`	某个交易对在每条路由上的报价，用于比价或发现套利机会
`kaleidoswap_atomic_init`	原子交换的第 1 步，返回 `swapstring` 和 `payment_hash`
`kaleidoswap_atomic_execute` 🔒	第 3 步，在 `wdk_atomic_taker` 把 HTLC 加入白名单后确认执行
`kaleidoswap_atomic_status`	按 `payment_hash` 轮询原子交换状态
`kaleidoswap_lsp_get_info`	LSP 的对等节点连接信息与通道容量上限
`kaleidoswap_lsp_estimate_fees`	在下单前预估 LSPS1 开通通道的费用
`kaleidoswap_lsp_create_order` 🔒	申请一条新的闪电通道（LSPS1），返回一张 BOLT11 发票
`kaleidoswap_lsp_get_order`	轮询 LSPS1 通道订单状态
`kaleidoswap_lsp_quote_asset_channel`	为预装了 RGB 资产（USDT、XAUT）的新通道报价
`kaleidoswap_lsp_create_asset_channel` 🔒	向 LSP 订购一条预装资产的新通道

通过 KALEIDO_NETWORK 配置，自定义端点则用 KALEIDOSWAP_API_URL。交换只走原子交换：基于订单的工具（kaleidoswap_place_order、kaleidoswap_get_order_status 等）已在 0.3.0 中移除。底层接口端点请见交换协议和 RGB LSPS1 API参考。

MPP / L402 支付（mpp_、l402_）

工具	用途
`mpp_request_challenge`	探测一个受 MPP 保护的 URL，把 HTTP 402 解析为发票 + `challenge_id`
`mpp_submit_credential`	提交支付凭据（在 `wdk_mpp_pay` / `spark_mpp_pay` 之后）以访问资源
`mpp_parse_challenge_header`	不发 HTTP 请求，直接解析原始的 `WWW-Authenticate` 头
`l402_request_challenge`	针对付费接口端点的遗留 L402 挑战，返回 BOLT11 发票加 macaroon
`l402_fetch_resource`	支付发票后获取受 L402 保护的资源
`search_paid_apis`	在 402index.io 目录中搜索付费门控 API（L402/MPP/x402），含以聪计价的价格和健康状态

行情数据（l402_get_、别名 get_）

WDK 内置行情工具（Bitfinex）：getCurrentPrice、getHistoricalPrice。

工具	用途
`l402_get_price`	单个资产的现货价格和 24 小时统计
`l402_get_market_data`	一次调用批量获取多个资产的价格
`l402_get_ohlcv`	OHLCV K 线，附带区间涨跌幅
`l402_get_sentiment`	恐慌与贪婪指数，0 到 100，附带一个交易信号

使用免费的公开 API（CoinGecko、alternative.me），无需任何配置。CoinGecko 免费层有速率限制，因此调用行情工具的间隔不要短于 30 秒。

节点生命周期（kaleido_node_*）

通过调用本地的 kaleido 可执行文件工作，因此代理可以自己把节点拉起来并解锁，而不必要求节点已在运行。这些操作的 CLI 原生等价方式见节点环境。

工具	用途
`kaleido_node_list`	列出所有 kaleido 节点环境及其节点 URL
`kaleido_node_up`	为指定环境启动 Docker 容器
`kaleido_node_stop`	停止运行中的容器，数据保留
`kaleido_node_down`	停止并删除容器和网络，卷保留
`kaleido_node_ps`	指定环境的 Docker 容器状态
`kaleido_node_status`	RLN 节点健康检查
`kaleido_node_info`	来自当前 RLN 节点的详细节点与网络信息
`kaleido_node_use`	在 kaleido 配置中设置当前节点 URL
`kaleido_node_init`	首次初始化 RLN 钱包
`kaleido_node_unlock`	重启后解锁 RLN 钱包
`kaleido_node_lock`	锁定 RLN 钱包

客户端配置

把服务器添加到 Claude Desktop 或 Claude Code 这类 MCP 宿主中。已发布的网关用 npx 即可；独立的钱包服务器则从本地构建运行。

下方初始配置不需要助记词。如果之后添加钱包种子，请将配置保密，并排除在版本控制之外。

{
  "mcpServers": {
    "kaleido": {
      "command": "npx",
      "args": ["-y", "kaleido-mcp"],
      "env": {
        "KALEIDO_NETWORK": "signet",
        "RLN_NODE_URL": "http://localhost:3001"
      }
    }
  }
}

claude mcp add kaleido \
  --env KALEIDO_NETWORK=signet \
  --env RLN_NODE_URL=http://localhost:3001 \
  -- npx -y kaleido-mcp

在 Claude Desktop 中，配置文件是 claude_desktop_config.json（Settings > Developer > Edit Config）。WDK_SEED 和 @tetherto/wdk-wallet-spark 包都是可选的：不提供时 Spark 工具会被禁用，而 RGB 节点、DEX、支付和行情工具照常可用。REGTEST 是 Spark SDK 对其托管测试网络的命名。

首次运行

先查询市场和钱包，再请求报价，最后才执行。余额查询和报价不会转移资金；支付与执行工具才会。

把网关添加到宿主客户端

把 kaleido-mcp 配置块加入你的 MCP 宿主配置，并把 KALEIDO_NETWORK 设为 signet。完整 JSON 见上面的客户端配置。

重启宿主客户端

MCP 宿主只在启动时读取配置。已经在运行的客户端不会自动识别新服务器，必须重启。

调用一个只读工具

先从不会动用资金的操作开始。请求行情数据，它既不需要种子也不需要节点：

What is the current Bitcoin price and the Fear and Greed index?

这会触发 l402_get_price 和 l402_get_sentiment。请核对客户端是否报告了成功的工具调用；仅有模型文字回答不能证明连接成功。

确认钱包已接好

启用可选 Spark 包并设置种子后，再确认钱包工具能正常解析：

Show me my Spark balance and my Spark address.

这会调用 spark_get_balance 和 spark_get_address。如果工具发现成功但调用失败，请检查可选钱包包、种子、网络及工具返回的错误。

交易前先报价

只询价，不执行：

Quote 100000 sats of BTC into USDT. Do not execute anything.

kaleidoswap_get_quote 会返回一个 rfq_id、原始数量、费用和过期时间。请仔细核对原始数量：它们以资产的最小单位计价，不是显示单位。

报价确认无误后再执行

一笔原子交换需要 DEX 工具和钱包工具配合，并且节点必须在通道中持有该资产。下面的跨服务器调用顺序按顺序列出了每一次调用。

通用 MCP 宿主是保护最弱的一条路径。kaleido-mcp 不编码确认标志，所以如果你的客户端自动批准工具调用，LLM 就能不经询问地从配置的钱包中花钱。在完全弄清客户端如何处理批准之前，请只使用测试网络种子。

原子交换流程

一笔原子交换需要 DEX 工具和钱包工具配合。kaleido-mcp 用它的 kaleidoswap_* 工具与做市方通信，并用 wdk_* 工具驱动接单方节点。任何一步都不涉及托管，HTLC 在闪电网络上结算。

kaleidoswap_get_quote        → rfq_id + raw amounts
kaleidoswap_atomic_init      → swapstring + payment_hash
wdk_atomic_taker             → whitelist the HTLC on the node
wdk_get_node_info            → taker_pubkey
kaleidoswap_atomic_execute   → trigger HTLC settlement
kaleidoswap_atomic_status    → poll until Succeeded

上面每一步都走同一条 kaleido-mcp 连接，因为两组前缀同时可用。

付费 API 访问

Machine Payments Protocol 流程让代理无需 API 密钥、无需注册就能买到受门控资源的访问权，直接通过闪电网络支付发票。

mpp_request_challenge(url)          → challenge { invoice, challenge_id }
wdk_mpp_pay(invoice, challenge_id)  → payment credential
mpp_submit_credential(url, cred)    → { ok, data, receipt }

已退役的服务器

下列名称仅用于旧集成迁移，不是需要额外安装的服务器：

旧入口	当前用法
`wdk-wallet-mcp`	`kaleido-mcp` 中的 `wdk_*`
`wdk-wallet-spark-mcp`	`spark_*` 加可选 Spark 包；用 `WDK_SEED` 替代 `WDK_SPARK_SEED`
`wdk-wallet-liquid-mcp`	`liquid_*` 加可选 Liquid 包
`kaleidoswap-mcp`	`kaleidoswap_*`；已移除的 REST 订单流程请改为原子交换
`l402-gateway-mcp`	`mpp_` / `l402_`
`kaleido-node-mcp`	`kaleido_node_` 管理节点，`wdk_` 操作钱包

宿主需要的 rln_* 别名仍可保留。新建原始 MCP 集成应使用规范名称，迁移参数前请核对所安装版本的自动生成参数结构。

​需要准备什么

​安装与配置

​网络预设

​运行时兼容性

​遗留别名

​按领域划分的工具集

​客户端配置

​首次运行

​原子交换流程

​付费 API 访问

​已退役的服务器

需要准备什么

安装与配置

网络预设

运行时兼容性

遗留别名

按领域划分的工具集

客户端配置

首次运行

原子交换流程

付费 API 访问

已退役的服务器