diff --git a/mintlify-docs/ai-tools/additional-resources.mdx b/mintlify-docs/ai-tools/additional-resources.mdx index 2836e1d..9f87867 100644 --- a/mintlify-docs/ai-tools/additional-resources.mdx +++ b/mintlify-docs/ai-tools/additional-resources.mdx @@ -6,7 +6,7 @@ description: "Links for the KaleidoSwap AI tools, covering source repositories, ## Source Repositories -Every AI surface is open source under the [KaleidoSwap organisation](https://github.com/kaleidoswap). +Every AI surface is public under the [KaleidoSwap organisation](https://github.com/kaleidoswap), with the gateway, KaleidoAgent and KaleidoMind under Apache 2.0. @@ -16,7 +16,7 @@ Every AI surface is open source under the [KaleidoSwap organisation](https://git The on-device engine: tiered funnel, recipe engine, tool contract, memory and retrieval, and the eval harness. - The gateway that composes every domain behind one connection. Published to npm. + The gateway that composes every domain behind one connection. Published to npm, though the release currently trails `main`. The React Native mobile wallet that hosts KaleidoMind with voice control. diff --git a/mintlify-docs/ai-tools/faq.mdx b/mintlify-docs/ai-tools/faq.mdx index d1ee3c7..a22ac0e 100644 --- a/mintlify-docs/ai-tools/faq.mdx +++ b/mintlify-docs/ai-tools/faq.mdx @@ -60,16 +60,23 @@ description: "Common questions about the KaleidoSwap AI tools, covering custody, - Several independent controls, and it is worth using more than one: + On KaleidoAgent, one control is enforced in code: | Control | Effect | |---------|--------| - | `dry_run` | Simulates the decision without executing | + | `dry_run` | Blocks execution before any tool is called. Simulates the decision without executing | + + The rest are passed to the model as operating rules rather than enforced independently, so treat them as guidance and not as a spending limit: + + | Control | Intended effect | + |---------|--------| | `max_swap_usd` | Caps a single trade | | `stop_loss_btc_sats` | Halts all trading below a BTC threshold | | `min_btc_reserve_sats` | Keeps a floor across the node and Spark | | `max_concurrent_orders` | Caps simultaneous open orders | + The controls that hold regardless of what the model decides are `dry_run` and keeping the funded balance small. + On KaleidoMind the equivalent is structural rather than configured: fund-moving tools are marked `requiresConfirmation` and pause for the host's confirmation sheet. @@ -84,7 +91,7 @@ description: "Common questions about the KaleidoSwap AI tools, covering custody, - Yes. Every repository is public under [github.com/kaleidoswap](https://github.com/kaleidoswap): the MCP servers, KaleidoAgent, KaleidoMind, and the skills themselves. See [Additional Resources](/ai-tools/additional-resources) for the direct links. + Yes, with one caveat. The gateway, the per-wallet MCP servers, KaleidoAgent, KaleidoMind and the skills are all public under [github.com/kaleidoswap](https://github.com/kaleidoswap). `kaleido-mcp`, KaleidoAgent and KaleidoMind are Apache 2.0. The three per-wallet servers are public but do not yet carry a licence file, so treat them as source-available until one lands. See [Additional Resources](/ai-tools/additional-resources) for the direct links. diff --git a/mintlify-docs/ai-tools/getting-started.mdx b/mintlify-docs/ai-tools/getting-started.mdx index 775b5ed..f554bf1 100644 --- a/mintlify-docs/ai-tools/getting-started.mdx +++ b/mintlify-docs/ai-tools/getting-started.mdx @@ -37,7 +37,7 @@ The two agent surfaces gate spending differently, and it is worth knowing which | Surface | Gate | |---------|------| | **[KaleidoMind](/ai-tools/kaleido-mind)** | Structural. Every fund-moving tool is marked `requiresConfirmation`, so the engine pauses for the host's confirmation sheet. The model cannot bypass it | -| **[KaleidoAgent](/ai-tools/kaleido-agent)** | Policy. `dry_run` plus the risk limits in `agent.config.json`, checked before submission | +| **[KaleidoAgent](/ai-tools/kaleido-agent)** | Mixed. `dry_run` is enforced in code; the other risk limits in `agent.config.json` are rules given to the model, not an independent ceiling | | **[MCP servers](/ai-tools/mcp-servers)** | Whatever your host provides. Most MCP clients prompt per tool call, but that is the client's behaviour, not the server's | diff --git a/mintlify-docs/ai-tools/installation.mdx b/mintlify-docs/ai-tools/installation.mdx index b5c92b8..78583fb 100644 --- a/mintlify-docs/ai-tools/installation.mdx +++ b/mintlify-docs/ai-tools/installation.mdx @@ -18,11 +18,18 @@ Each AI surface installs independently. Pick the one that matches what you are b ## MCP Servers -`kaleido-mcp` is the fastest path to a working tool call, published to npm with no local build required: +`kaleido-mcp` is the quickest path to a first tool call, published to npm: ```bash npx -y kaleido-mcp ``` + + The npm release currently trails `main`. The published build predates the node + lifecycle tools (`kaleido_node_*`) and still exposes the removed order tools, + so `npx` will not give you the full surface documented on this page. Until the + next release lands, build from source for `kaleido_node_*` and the RFQ swap flow. + + Three per-wallet servers, `wdk-wallet-mcp`, `wdk-wallet-spark-mcp`, and `wdk-wallet-liquid-mcp`, remain standalone rather than folded into the gateway and build from source: diff --git a/mintlify-docs/ai-tools/kaleido-agent.mdx b/mintlify-docs/ai-tools/kaleido-agent.mdx index 82d2c43..dfa4bce 100644 --- a/mintlify-docs/ai-tools/kaleido-agent.mdx +++ b/mintlify-docs/ai-tools/kaleido-agent.mdx @@ -76,17 +76,30 @@ Each loop is driven by a [skill](/ai-tools/skills). ## Risk Controls -Risk limits live in `agent.config.json` under `portfolio`. They are checked before any swap is submitted. +Risk limits live in `agent.config.json` under `portfolio`. They are not all enforced the same way, and the difference matters when you size them. + +`dry_run` is enforced in code. The swap executor refuses before any tool is called, so no phrasing in a prompt or a skill reaches past it. | Parameter | Default | Effect | |-----------|---------|--------| -| `dry_run` | `true` | Simulates the decision without executing a swap | +| `dry_run` | `true` | Blocks execution in code. Simulates the decision without executing a swap | + +The remaining parameters are passed to the model as operating rules, in the run prompt and in the skill files. They shape what a cooperative model does. They are not an independent ceiling, so a model that ignores them is not currently stopped by anything else. + +| Parameter | Default | Intended effect | +|-----------|---------|--------| | `max_swap_usd` | `200` | Caps the USD value of a single trade | | `min_btc_reserve_sats` | `50000` | Minimum combined BTC balance across the RLN node and Spark | | `stop_loss_btc_sats` | `30000` | Halts all trading below this BTC threshold | | `rebalance_threshold_pct` | `5` | Minimum drift percentage that triggers a swap | | `max_concurrent_orders` | `3` | Caps simultaneous open orders | + + Treat the second table as guidance to the model, not as a spending limit. Until + these are enforced outside the reasoning loop, `dry_run` and a small funded + balance are the only controls that hold against a model that gets it wrong. + + ## Trading Modes | Mode | Settlement | @@ -180,7 +193,7 @@ With the agent running, drive one loop by hand and read what it decided before l - Confirm `max_swap_usd`, `min_btc_reserve_sats`, and `stop_loss_btc_sats` match what you are willing to lose on a test network. These are checked before any swap is submitted, see [Risk Controls](#risk-controls) above. + Confirm `max_swap_usd`, `min_btc_reserve_sats`, and `stop_loss_btc_sats` match what you are willing to lose on a test network. These are passed to the model as rules rather than enforced in code, so keep `dry_run` on and the balance small until you trust the decisions, see [Risk Controls](#risk-controls) above. diff --git a/mintlify-docs/ai-tools/mcp-servers.mdx b/mintlify-docs/ai-tools/mcp-servers.mdx index 411cf06..e4eaa97 100644 --- a/mintlify-docs/ai-tools/mcp-servers.mdx +++ b/mintlify-docs/ai-tools/mcp-servers.mdx @@ -52,11 +52,18 @@ If you have an integration still pointing at `kaleidoswap-mcp` or `l402-gateway- ## Installation & Configuration -`kaleido-mcp` is published to npm, so the fastest path needs no local build: +`kaleido-mcp` is published to npm, which is the quickest way to a first tool call: ```bash npx -y kaleido-mcp ``` + + The npm release currently trails `main`. The published build predates the node + lifecycle tools (`kaleido_node_*`) and still exposes the removed order tools, + so `npx` will not give you the full surface documented on this page. Until the + next release lands, build from source for `kaleido_node_*` and the RFQ swap flow. + + In practice an MCP host runs this for you, point its config at the command (see [Client Configuration](#client-configuration) below). For development, or to run a specific commit, build from source instead: @@ -164,11 +171,6 @@ All tools below are served by `kaleido-mcp` over a single connection. The 🔒 i | `kaleidoswap_get_pairs` | Tradeable pairs with available layer routes | | `kaleidoswap_get_quote` | Price quote for a swap, returns output amount, price, fee, `rfq_id` | | `kaleidoswap_get_spreads` | Quotes across every route for a pair, to compare or find arbitrage | - | `kaleidoswap_place_order` | Place a REST swap order, returns a `deposit_address` | - | `kaleidoswap_get_order_status` | Poll order status until `FILLED`, `FAILED`, `EXPIRED`, or `CANCELLED` | - | `kaleidoswap_get_open_orders` | Orders placed in this session with last known status | - | `kaleidoswap_cancel_order` | Mark an order cancelled in the local session tracker | - | `kaleidoswap_get_position` | Session trading stats: fill rate, volume by asset | | `kaleidoswap_atomic_init` | Step 1 of an atomic swap, returns `swapstring` and `payment_hash` | | `kaleidoswap_atomic_execute` 🔒 | Step 3, confirm execution after `wdk_atomic_taker` whitelists the HTLC | | `kaleidoswap_atomic_status` | Poll atomic swap status by `payment_hash` | diff --git a/mintlify-docs/ai-tools/troubleshooting.mdx b/mintlify-docs/ai-tools/troubleshooting.mdx index f2b0b82..6be31cb 100644 --- a/mintlify-docs/ai-tools/troubleshooting.mdx +++ b/mintlify-docs/ai-tools/troubleshooting.mdx @@ -155,7 +155,7 @@ description: "Fix common KaleidoSwap AI tool problems, covering MCP connection f **Symptoms**: The agent was executing, then stopped submitting swaps. - **Cause**: A risk limit tripped. Most often `stop_loss_btc_sats`, which halts all trading below its BTC threshold, or `min_btc_reserve_sats`. + **Cause**: Usually `dry_run` is still on, so decisions are simulated rather than executed. Otherwise the model declined to trade, which can happen when it applies `stop_loss_btc_sats` or `min_btc_reserve_sats` from its instructions, or when a tool call failed. **Solutions**: 1. Read `GET /status` for balances and recent runs. diff --git a/mintlify-docs/cn/ai-tools/additional-resources.mdx b/mintlify-docs/cn/ai-tools/additional-resources.mdx index 44ed165..5b74f57 100644 --- a/mintlify-docs/cn/ai-tools/additional-resources.mdx +++ b/mintlify-docs/cn/ai-tools/additional-resources.mdx @@ -6,7 +6,7 @@ description: "KaleidoSwap AI 工具的相关链接：各个源码仓库、MCP ## 源码仓库 -每一种 AI 接入方式都在 [KaleidoSwap 组织](https://github.com/kaleidoswap)下开源。 +每一种 AI 接入方式都公开在 [KaleidoSwap 组织](https://github.com/kaleidoswap) 下，其中网关、KaleidoAgent 和 KaleidoMind 采用 Apache 2.0。 diff --git a/mintlify-docs/cn/ai-tools/faq.mdx b/mintlify-docs/cn/ai-tools/faq.mdx index 28c9f43..0b72008 100644 --- a/mintlify-docs/cn/ai-tools/faq.mdx +++ b/mintlify-docs/cn/ai-tools/faq.mdx @@ -60,7 +60,7 @@ description: "关于 KaleidoSwap AI 工具的常见问题：托管方式、种 - 有几种相互独立的控制手段，而且值得同时用上多个： + 在 KaleidoAgent 上，只有一项控制在代码层面强制生效：`dry_run`。下表其余项是作为运行规则传递给模型的，请当作指引而非支出上限： | 控制项 | 效果 | |---------|--------| @@ -84,7 +84,7 @@ description: "关于 KaleidoSwap AI 工具的常见问题：托管方式、种 - 是的。所有仓库都公开在 [github.com/kaleidoswap](https://github.com/kaleidoswap) 下：MCP 服务器、KaleidoAgent、KaleidoMind，以及 skill 本身。直达链接见[更多资源](/cn/ai-tools/additional-resources)。 + 是的，但有一点需要说明。网关、各个钱包 MCP 服务器、KaleidoAgent、KaleidoMind 和 skill 都公开在 [github.com/kaleidoswap](https://github.com/kaleidoswap) 下。`kaleido-mcp`、KaleidoAgent 和 KaleidoMind 采用 Apache 2.0。三个钱包服务器虽然公开，但尚未附带许可证文件，在许可证落地之前请按 source-available 对待。直达链接见[更多资源](/cn/ai-tools/additional-resources)。 diff --git a/mintlify-docs/cn/ai-tools/getting-started.mdx b/mintlify-docs/cn/ai-tools/getting-started.mdx index 97bfbba..193f521 100644 --- a/mintlify-docs/cn/ai-tools/getting-started.mdx +++ b/mintlify-docs/cn/ai-tools/getting-started.mdx @@ -37,7 +37,7 @@ description: "选择把 AI 代理接入比特币的方式：MCP 服务器、Kale | 接入方式 | 把关机制 | |---------|------| | **[KaleidoMind](/cn/ai-tools/kaleido-mind)** | 结构性把关。每个会动用资金的工具都标记了 `requiresConfirmation`，引擎会暂停并等待宿主的确认面板。模型无法绕过 | -| **[KaleidoAgent](/cn/ai-tools/kaleido-agent)** | 策略性把关。`dry_run` 加上 `agent.config.json` 中的风险上限，在提交前校验 | +| **[KaleidoAgent](/cn/ai-tools/kaleido-agent)** | 混合把关。`dry_run` 在代码层面强制生效；`agent.config.json` 中其余风险上限是给模型的规则，不是独立的上限 | | **[MCP 服务器](/cn/ai-tools/mcp-servers)** | 取决于你的宿主客户端。多数 MCP 客户端会为每次工具调用弹出确认，但那是客户端的行为，不是服务器的 | diff --git a/mintlify-docs/cn/ai-tools/installation.mdx b/mintlify-docs/cn/ai-tools/installation.mdx index f7f2a02..c4c16bf 100644 --- a/mintlify-docs/cn/ai-tools/installation.mdx +++ b/mintlify-docs/cn/ai-tools/installation.mdx @@ -23,6 +23,12 @@ description: "安装 KaleidoSwap AI 工具：MCP 服务器网关、KaleidoAgent ```bash npx -y kaleido-mcp ``` + + npm 上的发布版本落后于 `main`。已发布的构建不包含节点生命周期工具（`kaleido_node_*`）， + 并且仍然暴露已移除的订单工具，因此 `npx` 无法提供本页所记录的完整工具集。 + 在下一个发布版本发布之前，请从源码构建以使用 `kaleido_node_*` 和 RFQ 交换流程。 + + 另有三个按钱包划分的服务器 `wdk-wallet-mcp`、`wdk-wallet-spark-mcp` 和 `wdk-wallet-liquid-mcp`，它们保持独立而未并入网关，需要从源码构建： diff --git a/mintlify-docs/cn/ai-tools/kaleido-agent.mdx b/mintlify-docs/cn/ai-tools/kaleido-agent.mdx index 6f555ba..e0a5c72 100644 --- a/mintlify-docs/cn/ai-tools/kaleido-agent.mdx +++ b/mintlify-docs/cn/ai-tools/kaleido-agent.mdx @@ -76,7 +76,11 @@ KaleidoAgent 把 `kaleido-mcp`（[统一的 MCP 服务器](/cn/ai-tools/mcp-serv ## 风险控制 {#risk-controls} -风险上限位于 `agent.config.json` 的 `portfolio` 之下。每笔交换提交之前都会校验它们。 +风险上限位于 `agent.config.json` 的 `portfolio` 之下。它们的生效方式并不相同，在设定数值时这一区别很重要。 + +`dry_run` 在代码层面强制生效：交换执行器会在调用任何工具之前拒绝，提示词或 skill 中的任何措辞都无法绕过它。 + +其余参数是作为运行规则传递给模型的，写在运行提示词和 skill 文件里。它们能约束一个配合的模型，但并不是独立的上限，因此忽略它们的模型目前不会被其他机制阻止。 | 参数 | 默认值 | 作用 | |-----------|---------|--------| diff --git a/mintlify-docs/cn/ai-tools/mcp-servers.mdx b/mintlify-docs/cn/ai-tools/mcp-servers.mdx index b33111d..f9eb544 100644 --- a/mintlify-docs/cn/ai-tools/mcp-servers.mdx +++ b/mintlify-docs/cn/ai-tools/mcp-servers.mdx @@ -57,6 +57,12 @@ KaleidoSwap 通过 **`kaleido-mcp`** 这一个统一服务器，把钱包、DEX ```bash npx -y kaleido-mcp ``` + + npm 上的发布版本落后于 `main`。已发布的构建不包含节点生命周期工具（`kaleido_node_*`）， + 并且仍然暴露已移除的订单工具，因此 `npx` 无法提供本页所记录的完整工具集。 + 在下一个发布版本发布之前，请从源码构建以使用 `kaleido_node_*` 和 RFQ 交换流程。 + + 实际使用中由 MCP 宿主替你执行这条命令，把宿主配置指向该命令即可（见下面的[客户端配置](#client-configuration)）。若用于开发，或要运行某个特定提交，请改为从源码构建： @@ -164,11 +170,6 @@ PORT=3010 WDK_SEED="word1 word2 ..." node dist/index.js | `kaleidoswap_get_pairs` | 可交易的交易对及其可用的分层路由 | | `kaleidoswap_get_quote` | 一笔交换的价格报价，返回输出数量、价格、费用和 `rfq_id` | | `kaleidoswap_get_spreads` | 某个交易对在每条路由上的报价，用于比价或发现套利机会 | - | `kaleidoswap_place_order` | 下一个 REST 交换订单，返回一个 `deposit_address` | - | `kaleidoswap_get_order_status` | 轮询订单状态，直到 `FILLED`、`FAILED`、`EXPIRED` 或 `CANCELLED` | - | `kaleidoswap_get_open_orders` | 本会话中下过的订单及其最后已知状态 | - | `kaleidoswap_cancel_order` | 在本地会话跟踪器中把订单标记为已取消 | - | `kaleidoswap_get_position` | 本会话交易统计：成交率、按资产统计的交易量 | | `kaleidoswap_atomic_init` | 原子交换的第 1 步，返回 `swapstring` 和 `payment_hash` | | `kaleidoswap_atomic_execute` 🔒 | 第 3 步，在 `wdk_atomic_taker` 把 HTLC 加入白名单后确认执行 | | `kaleidoswap_atomic_status` | 按 `payment_hash` 轮询原子交换状态 | diff --git a/mintlify-docs/cn/ai-tools/troubleshooting.mdx b/mintlify-docs/cn/ai-tools/troubleshooting.mdx index 919e000..3acdb9b 100644 --- a/mintlify-docs/cn/ai-tools/troubleshooting.mdx +++ b/mintlify-docs/cn/ai-tools/troubleshooting.mdx @@ -155,7 +155,7 @@ description: "解决 KaleidoSwap AI 工具的常见问题：MCP 连接失败、 **现象**：代理原本在执行，之后就不再提交交换了。 - **原因**：某个风险上限被触发。最常见的是 `stop_loss_btc_sats`（低于其 BTC 阈值时停止所有交易），或者 `min_btc_reserve_sats`。 + **原因**：通常是 `dry_run` 仍然开启，因此决策只是模拟而未执行。否则就是模型自己选择不交易，例如它根据指令应用了 `stop_loss_btc_sats` 或 `min_btc_reserve_sats`，或者某次工具调用失败了。 **解决办法**： 1. 读取 `GET /status` 查看余额和最近的运行记录。 diff --git a/mintlify-docs/cn/desktop-app/support/changelog.mdx b/mintlify-docs/cn/desktop-app/support/changelog.mdx index ddd0d4a..ed2bb0e 100644 --- a/mintlify-docs/cn/desktop-app/support/changelog.mdx +++ b/mintlify-docs/cn/desktop-app/support/changelog.mdx @@ -6,7 +6,7 @@ description: "KaleidoSwap 桌面应用版本历史：从最新版本回溯到 al ## v0.5.0（当前版本） -**发布日期：** 21 June 2026 +**发布日期：** 2026 年 7 月 10 日 **支持平台：** macOS（Apple Silicon 和 Intel）、Windows (x64)、Linux（AppImage、deb、rpm） diff --git a/mintlify-docs/cn/whats-kaleidoswap/architecture.mdx b/mintlify-docs/cn/whats-kaleidoswap/architecture.mdx index 1170c3b..9ce6c67 100644 --- a/mintlify-docs/cn/whats-kaleidoswap/architecture.mdx +++ b/mintlify-docs/cn/whats-kaleidoswap/architecture.mdx @@ -19,7 +19,7 @@ KaleidoSwap 是垂直整合的：同一套 SDK 驱动我们发布的每一个客 | **智能层** | 负责本地推理的 KaleidoMind，负责自主执行的 KaleidoAgent | | **结算** | 比特币 —— 上面所有层最终锚定的地方 | -桌面应用、SDK、CLI、钱包引擎以及 MCP/AI 工具链均为开源（MIT），可在 [GitHub](https://github.com/kaleidoswap) 上查阅；浏览器扩展和做市方的询价引擎目前尚未开源。 +桌面应用、SDK、CLI 和钱包引擎以 MIT 开源，AI 工具链（`kaleido-mcp`、KaleidoAgent、KaleidoMind）以 Apache 2.0 开源，均可在 [GitHub](https://github.com/kaleidoswap) 上查阅；浏览器扩展和做市方的询价引擎目前尚未开源。 ## 集成层 diff --git a/mintlify-docs/desktop-app/support/changelog.mdx b/mintlify-docs/desktop-app/support/changelog.mdx index 706df03..7d8cdce 100644 --- a/mintlify-docs/desktop-app/support/changelog.mdx +++ b/mintlify-docs/desktop-app/support/changelog.mdx @@ -6,7 +6,7 @@ description: "KaleidoSwap Desktop App version history: new features, changes, an ## v0.5.0 (Current) -**Released:** 21 June 2026 +**Released:** 10 July 2026 **Platforms:** macOS (Apple Silicon and Intel), Windows (x64), Linux (AppImage, deb, rpm) diff --git a/mintlify-docs/whats-kaleidoswap/architecture.mdx b/mintlify-docs/whats-kaleidoswap/architecture.mdx index d918088..59ed7ca 100644 --- a/mintlify-docs/whats-kaleidoswap/architecture.mdx +++ b/mintlify-docs/whats-kaleidoswap/architecture.mdx @@ -19,7 +19,7 @@ This page walks the stack from the top down. For the protocols themselves and wh | **Intelligence layer** | KaleidoMind for local reasoning, KaleidoAgent for autonomous execution | | **Settlement** | Bitcoin — where every layer above anchors | -The desktop app, SDKs, CLI, wallet engine, and MCP/AI tooling are open source (MIT) and inspectable on [GitHub](https://github.com/kaleidoswap); the browser extension and the maker-side RFQ engine are not public today. +The desktop app, SDKs, CLI and wallet engine are open source under MIT, and the AI tooling (`kaleido-mcp`, KaleidoAgent, KaleidoMind) under Apache 2.0, all inspectable on [GitHub](https://github.com/kaleidoswap); the browser extension and the maker-side RFQ engine are not public today. ## Integration layer