Skip to main content
这是从「装好工具」到「验证一笔交换」的完整路径。顺序是先只读，再报价，最后执行 —— 因为除第一步之外，每一步都会动用真实价值。

​
开始之前

如果你还没有安装任何组件，请先看安装。

​
选择接入方式

​
首次运行：MCP 服务器

1

把网关添加到宿主客户端

把 kaleido-mcp 配置块加入你的 MCP 宿主配置，将 KALEIDOSWAP_API_URL 指向测试环境，并把 SPARK_NETWORK 设为 REGTEST。完整 JSON 见 MCP 服务器页面。
2

重启宿主客户端

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

调用一个只读工具

先从不会动用资金的操作开始。请求行情数据，它既不需要种子也不需要节点：
这会触发 l402_get_price 和 l402_get_sentiment。只要有回答，连接就是通的。
4

确认钱包已接好

接着确认钱包工具能正常解析：
这会调用 spark_get_balance 和 spark_get_address。这一步报错说明是种子或网络问题，而不是连接问题。
5

交易前先报价

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

报价确认无误后再执行

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

​
首次运行：KaleidoAgent

1

保持 dry run 开启

agent.config.json 中的 portfolio.dry_run 默认为 true。先别动它。代理会完成推理、决策并汇报一笔交易，但不会真正提交。
2

启动代理

这会同时启动代理和监听 http://localhost:4242 的状态 API。若要使用仪表盘，另外运行 npm run dev:webapp 并打开 http://localhost:5173。
3

手动触发一轮循环

不必等定时任务，可以直接让状态 API 跑一轮：
然后读取 GET /status，查看它的决策、它看到的余额，以及 token 开销。
4

检查风险上限

确认 max_swap_usd、min_btc_reserve_sats 和 stop_loss_btc_sats 与你在测试网络上能接受的损失相符。每笔交换提交之前都会校验这些参数。
5

确认无误后再关闭 dry run

当连续几轮的 dry-run 决策都看起来正确后，再把 portfolio.dry_run 设为 false。

​
确认机制长什么样

两种代理接入方式对花费的把关方式不同，值得弄清楚你依赖的是哪一种。
通用 MCP 宿主是保护最弱的一条路径。如果你的客户端自动批准工具调用，LLM 就能不经询问地从配置的钱包中花钱。在完全弄清客户端如何处理批准之前，请只使用测试网络种子。