diff --git a/mintlify-docs/ai-tools/build-local-rgb-agent.mdx b/mintlify-docs/ai-tools/build-local-rgb-agent.mdx index f818730..619f017 100644 --- a/mintlify-docs/ai-tools/build-local-rgb-agent.mdx +++ b/mintlify-docs/ai-tools/build-local-rgb-agent.mdx @@ -92,7 +92,7 @@ RGB assets live on Bitcoin UTXOs, so the node needs a little signet BTC before i KALEIDO_NETWORK=signet RLN_NODE_URL=http://localhost:3001 npx -y kaleido-mcp ``` -The server logs `network: signet` and waits on stdio. You do not need to keep it running by hand: the agent in the next step starts it as a child process. `WDK_SEED` is optional here; without it the Spark tools stay off and the RGB, DEX, payment and market tools still work. See [MCP Servers](/ai-tools/mcp-servers#network-preset) for every variable. +The server logs `network: signet` and waits on stdio. You do not need to keep it running by hand: the agent in the next step starts it as a child process. `WDK_SEED` is optional here, and plain `npx` does not install the Spark wallet package; without them the Spark tools stay off and the RGB, DEX, payment and market tools still work. See [MCP Servers](/ai-tools/mcp-servers#network-preset) for every variable. Want to try the tools before writing any code? Add the same command to Claude Desktop or Claude Code with the config in [Client Configuration](/ai-tools/mcp-servers#client-configuration), then ask for your RGB balance. The rest of this tutorial swaps that hosted model for a local one. diff --git a/mintlify-docs/ai-tools/getting-started.mdx b/mintlify-docs/ai-tools/getting-started.mdx index fa9559d..f4bbdc7 100644 --- a/mintlify-docs/ai-tools/getting-started.mdx +++ b/mintlify-docs/ai-tools/getting-started.mdx @@ -11,8 +11,8 @@ Four surfaces expose the same Bitcoin tools to a model, and they differ mostly i | Requirement | Details | |-------------|---------| | **A test network** | Signet. The KaleidoSwap API runs a signet instance at `https://api.signet.kaleidoswap.com`, and the [RGB faucet](https://faucet.mutinynet.kaleidoswap.com) sends test assets. Never a first run on mainnet | -| **A wallet seed** | A throwaway BIP-39 mnemonic for the test network, set as `WDK_SEED` | -| **A node** | Only for the `wdk_*` tools and atomic swaps. [KaleidoCLI](/cli/installation) starts a signet RGB Lightning Node with one command. Spark tools need just a seed, market data needs nothing | +| **A wallet seed** | Only for the Spark tools: a throwaway BIP-39 mnemonic for the test network, set as `WDK_SEED`, plus the optional Spark wallet package (see [MCP Servers](/ai-tools/mcp-servers)) | +| **A node** | Only for the `wdk_*` tools and atomic swaps. [KaleidoCLI](/cli/installation) starts a signet RGB Lightning Node with one command. Spark tools need a seed and the Spark wallet package, market data needs nothing | | **An MCP host or LLM key** | Claude Desktop or another MCP client, or an Anthropic/OpenAI key for KaleidoAgent | If you have not installed anything yet, start with [Installation](/ai-tools/installation). For an end-to-end path from an empty machine to a local model moving RGB assets on signet, follow [Build a Local RGB Agent](/ai-tools/build-local-rgb-agent). diff --git a/mintlify-docs/ai-tools/installation.mdx b/mintlify-docs/ai-tools/installation.mdx index 6f70491..b36e16b 100644 --- a/mintlify-docs/ai-tools/installation.mdx +++ b/mintlify-docs/ai-tools/installation.mdx @@ -30,6 +30,8 @@ KALEIDO_NETWORK=signet npx -y kaleido-mcp resolves an older cached version, run `npx -y kaleido-mcp@latest` once. +From 0.3.1 the Spark and Liquid wallets are optional and not installed by plain `npx`. To enable them, run `npx -y -p kaleido-mcp -p @tetherto/wdk-wallet-spark -p @kaleidorg/wdk-wallet-liquid kaleido-mcp` and set `WDK_SEED` / `LIQUID_MNEMONIC`. + For the RGB tools you also need an RGB Lightning Node. [KaleidoCLI](/cli/installation) runs one on signet in Docker, see [Build a Local RGB Agent](/ai-tools/build-local-rgb-agent) for the full path. 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/mcp-servers.mdx b/mintlify-docs/ai-tools/mcp-servers.mdx index 0038351..e5338c9 100644 --- a/mintlify-docs/ai-tools/mcp-servers.mdx +++ b/mintlify-docs/ai-tools/mcp-servers.mdx @@ -65,6 +65,16 @@ KALEIDO_NETWORK=signet npx -y kaleido-mcp `npx -y kaleido-mcp@latest` once, or build from source. + + From 0.3.1 the Spark and Liquid wallets are optional peer dependencies that plain + `npx -y kaleido-mcp` does not install. With `WDK_SEED` or `LIQUID_MNEMONIC` set but + the package missing, the server still starts and logs an install hint. To enable them: + + ```bash + npx -y -p kaleido-mcp -p @tetherto/wdk-wallet-spark -p @kaleidorg/wdk-wallet-liquid kaleido-mcp + ``` + + 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: ```bash @@ -86,24 +96,25 @@ PORT=3010 KALEIDO_NETWORK=signet WDK_SEED="word1 word2 ..." node dist/index.js ### Network Preset -`KALEIDO_NETWORK` picks a set of defaults in one variable. It accepts `mainnet` (the default) or `signet`: +`KALEIDO_NETWORK` picks a set of defaults in one variable. It accepts `signet` (the default from 0.3.1) or `mainnet`: | Preset | KaleidoSwap API | Spark network | |--------|-----------------|---------------| -| `mainnet` | `https://api.kaleidoswap.com` | `MAINNET` | | `signet` | `https://api.signet.kaleidoswap.com` | Spark's test network (`REGTEST` in the Spark SDK) | +| `mainnet` | None: set `KALEIDOSWAP_API_URL` to your own maker endpoint | `MAINNET` | -The preset only fills in defaults. Any variable you set explicitly, such as `KALEIDOSWAP_API_URL` or `SPARK_NETWORK`, wins over it. An unknown value stops the server at startup rather than silently falling back to mainnet. `RLN_NODE_URL` is not part of the preset: point it at your own node, which on signet is usually the one [KaleidoCLI](/cli/installation) runs on `http://localhost:3001`. +The preset only fills in defaults. Any variable you set explicitly, such as `KALEIDOSWAP_API_URL` or `SPARK_NETWORK`, wins over it. There is no public mainnet KaleidoSwap API, so `mainnet` without `KALEIDOSWAP_API_URL` stops the server at startup, as does an unknown value. `RLN_NODE_URL` is not part of the preset: point it at your own node, which on signet is usually the one [KaleidoCLI](/cli/installation) runs on `http://localhost:3001`. | Env var | Required | Description | |---------|----------|--------------| -| `KALEIDO_NETWORK` | No | `mainnet` (default) or `signet`. Sets the defaults in [Network Preset](#network-preset) | -| `WDK_SEED` | Yes, for Spark tools | BIP-39 mnemonic for the Spark wallet. The server still boots without it, the Spark tools are just disabled | +| `KALEIDO_NETWORK` | No | `signet` (default) or `mainnet`. Sets the defaults in [Network Preset](#network-preset) | +| `WDK_SEED` | Yes, for Spark tools | BIP-39 mnemonic for the Spark wallet. Also needs the optional `@tetherto/wdk-wallet-spark` package. The server still boots without either, the Spark tools are just disabled | +| `LIQUID_MNEMONIC` | Yes, for Liquid tools | BIP-39 mnemonic for the Liquid wallet. Also needs the optional `@kaleidorg/wdk-wallet-liquid` package | | `SPARK_NETWORK` | No | Overrides the preset's Spark network: `MAINNET`, or `REGTEST` for Spark's test network | | `SPARK_SCAN_API_KEY` | No | SparkScan API key | | `SPARK_USDT_TOKEN` | No | Default Spark token identifier | | `RLN_NODE_URL` | No | RLN daemon URL, default `http://localhost:3001` | -| `KALEIDOSWAP_API_URL` | No | Overrides the preset's KaleidoSwap API URL. `KALEIDO_API_URL` is accepted as well | +| `KALEIDOSWAP_API_URL` | With `mainnet` | KaleidoSwap maker API URL, overriding the preset. Required on `mainnet`, which has no public endpoint. `KALEIDO_API_URL` is accepted as well | | `KALEIDO_BIN` | No | Path to the `kaleido` binary, for the node lifecycle tools | | `KALEIDO_NODE_URL` | No | Node URL passed as `--node-url` to the node lifecycle tools | | `KALEIDO_API_URL` | No | API URL passed as `--api-url` to the node lifecycle tools, and a fallback for `KALEIDOSWAP_API_URL` | @@ -253,7 +264,7 @@ Add a server to an MCP host such as Claude Desktop or Claude Code. `npx` works f "mcpServers": { "kaleido": { "command": "npx", - "args": ["-y", "kaleido-mcp"], + "args": ["-y", "-p", "kaleido-mcp", "-p", "@tetherto/wdk-wallet-spark", "kaleido-mcp"], "env": { "KALEIDO_NETWORK": "signet", "WDK_SEED": "your twelve word seed phrase", @@ -269,7 +280,7 @@ claude mcp add kaleido \ --env KALEIDO_NETWORK=signet \ --env RLN_NODE_URL=http://localhost:3001 \ --env WDK_SEED="your twelve word seed phrase" \ - -- npx -y kaleido-mcp + -- npx -y -p kaleido-mcp -p @tetherto/wdk-wallet-spark kaleido-mcp ``` ```json wdk-wallet-mcp @@ -302,7 +313,7 @@ claude mcp add kaleido \ ``` -On Claude Desktop the file is `claude_desktop_config.json` (**Settings > Developer > Edit Config**). `WDK_SEED` is optional: leave it out and the Spark tools are disabled while the RGB node, DEX, payment and market tools keep working. The standalone Spark server takes no network preset, so it sets `SPARK_NETWORK` directly; `REGTEST` is the name the Spark SDK gives its hosted test network. +On Claude Desktop the file is `claude_desktop_config.json` (**Settings > Developer > Edit Config**). `WDK_SEED` and the `@tetherto/wdk-wallet-spark` package are optional: leave them out and the Spark tools are disabled while the RGB node, DEX, payment and market tools keep working. The standalone Spark server takes no network preset, so it sets `SPARK_NETWORK` directly; `REGTEST` is the name the Spark SDK gives its hosted test network. ## First Run diff --git a/mintlify-docs/ai-tools/skills.mdx b/mintlify-docs/ai-tools/skills.mdx index a0c83f4..12f08ba 100644 --- a/mintlify-docs/ai-tools/skills.mdx +++ b/mintlify-docs/ai-tools/skills.mdx @@ -38,5 +38,5 @@ The [KaleidoMind](/ai-tools/kaleido-mind) repository ships its bundled skills as /plugin install kaleido-mind@kaleidoswap ``` -The plugin runs `npx -y kaleido-mcp` with `KALEIDO_NETWORK=signet`. Set `RLN_NODE_URL` to point at your RGB Lightning Node and `WDK_SEED` to enable the Spark wallet tools. Some KaleidoMind skills (Spark wallet, Bitrefill, Flashnet, merchant finder) rely on tools that only the KaleidoMind runtime provides. +The plugin runs `npx -y kaleido-mcp` with `KALEIDO_NETWORK=signet`. Set `RLN_NODE_URL` to point at your RGB Lightning Node. The plugin does not install the optional Spark wallet package; to use the Spark tools, configure `kaleido-mcp` yourself as shown in [MCP Servers](/ai-tools/mcp-servers#client-configuration). Some KaleidoMind skills (Spark wallet, Bitrefill, Flashnet, merchant finder) rely on tools that only the KaleidoMind runtime provides. diff --git a/mintlify-docs/ai-tools/troubleshooting.mdx b/mintlify-docs/ai-tools/troubleshooting.mdx index 255cc91..259bfe3 100644 --- a/mintlify-docs/ai-tools/troubleshooting.mdx +++ b/mintlify-docs/ai-tools/troubleshooting.mdx @@ -20,7 +20,7 @@ description: "Fix common KaleidoSwap AI tool problems, covering MCP connection f **Symptoms**: The host reports the process died on launch. - **Cause**: A required environment variable is missing. The standalone `wdk-wallet-spark-mcp` refuses to start without `WDK_SPARK_SEED`. `kaleido-mcp` is more forgiving: without `WDK_SEED` it still boots, logs a warning, and disables the Spark tools. + **Cause**: A required environment variable is missing. The standalone `wdk-wallet-spark-mcp` refuses to start without `WDK_SPARK_SEED`. `kaleido-mcp` is more forgiving: without `WDK_SEED`, or without the optional `@tetherto/wdk-wallet-spark` package, it still boots, logs a warning or install hint, and disables the Spark tools. On `KALEIDO_NETWORK=mainnet` it does refuse to start without `KALEIDOSWAP_API_URL`, since there is no public mainnet API. **Solutions**: 1. Confirm the seed variable is set in the `env` block of the host config, not in your shell (the host does not inherit your shell environment). diff --git a/mintlify-docs/api-reference/additional-resources.mdx b/mintlify-docs/api-reference/additional-resources.mdx index f8a9ee4..f649ac2 100644 --- a/mintlify-docs/api-reference/additional-resources.mdx +++ b/mintlify-docs/api-reference/additional-resources.mdx @@ -51,7 +51,7 @@ Integrate against Signet before mainnet. No API key is required today, and anony | Environment | REST base URL | WebSocket | |-------------|---------------|-----------| | **Signet (MutinyNet)** | `https://api.signet.kaleidoswap.com/api/v1` | `wss://api.signet.kaleidoswap.com/api/v1/market/ws/{client_id}` | -| **Mainnet** | `https://api.kaleidoswap.com/api/v1` *(coming soon)* | `wss://api.kaleidoswap.com/api/v1/market/ws/{client_id}` *(coming soon)* | +| **Mainnet** | No public endpoint yet: use your own maker's URL | — | Asset IDs are not portable between environments — read them from `GET /api/v1/market/assets` and key your configuration per environment. diff --git a/mintlify-docs/api-reference/faq.mdx b/mintlify-docs/api-reference/faq.mdx index 66b86e8..baee93f 100644 --- a/mintlify-docs/api-reference/faq.mdx +++ b/mintlify-docs/api-reference/faq.mdx @@ -31,12 +31,12 @@ description: "Common questions about the KaleidoSwap swap API, covering authenti - Signet (MutinyNet) is live today; mainnet is coming soon. + Signet (MutinyNet) is live today. There is no public mainnet endpoint yet; for mainnet, point your integration at your own maker's URL. | Environment | REST base URL | WebSocket | |-------------|---------------|-----------| | **Signet** | `https://api.signet.kaleidoswap.com/api/v1` | `wss://api.signet.kaleidoswap.com/api/v1/market/ws/{client_id}` | - | **Mainnet** | `https://api.kaleidoswap.com/api/v1` *(coming soon)* | `wss://api.kaleidoswap.com/api/v1/market/ws/{client_id}` *(coming soon)* | + | **Mainnet** | No public endpoint yet: use your own maker's URL | — | The interactive playground on the endpoint pages runs against Signet. diff --git a/mintlify-docs/api-reference/getting-started.mdx b/mintlify-docs/api-reference/getting-started.mdx index 7dc35d8..171065b 100644 --- a/mintlify-docs/api-reference/getting-started.mdx +++ b/mintlify-docs/api-reference/getting-started.mdx @@ -18,9 +18,7 @@ A public testnet with realistic network conditions, recommended for integration - **Base URL:** `https://api.signet.kaleidoswap.com/api/v1` ### Bitcoin Mainnet (Coming Soon) -The mainnet environment is the production-ready endpoint for live transactions. Stay tuned for updates about its release. - -- **Base URL:** `https://api.kaleidoswap.com/api/v1` +There is no public mainnet endpoint yet. To integrate on mainnet, point your client at your own maker's base URL; the API paths are the same as on Signet. --- diff --git a/mintlify-docs/api-reference/swap-apis.mdx b/mintlify-docs/api-reference/swap-apis.mdx index 28ca11e..2c97ffb 100644 --- a/mintlify-docs/api-reference/swap-apis.mdx +++ b/mintlify-docs/api-reference/swap-apis.mdx @@ -46,7 +46,7 @@ Retrieve the public identity of the maker's RGB Lightning Node — its pubkey, t | Environment | URL | |-------------|-----| | **Signet** | `wss://api.signet.kaleidoswap.com/api/v1/market/ws/{client_id}` | -| **Mainnet** | `wss://api.kaleidoswap.com/api/v1/market/ws/{client_id}` *(coming soon)* | +| **Mainnet** | No public endpoint yet: use your own maker's URL | ### Description Establish a WebSocket connection to request live quotes from the maker. The protocol is request/response: the client sends a message and the server replies to that message. There is no subscription mechanism — to keep a price fresh, send a new `quote_request` whenever you need an updated quote. diff --git a/mintlify-docs/api-reference/swap-protocol.mdx b/mintlify-docs/api-reference/swap-protocol.mdx index 6d6339c..2427402 100644 --- a/mintlify-docs/api-reference/swap-protocol.mdx +++ b/mintlify-docs/api-reference/swap-protocol.mdx @@ -68,7 +68,7 @@ Taker Client Maker (RGB-LSP) Taker RLN | Environment | URL | |-------------|-----| | **Signet** | `wss://api.signet.kaleidoswap.com/api/v1/market/ws/{client_id}` | -| **Mainnet** | `wss://api.kaleidoswap.com/api/v1/market/ws/{client_id}` *(coming soon)* | +| **Mainnet** | No public endpoint yet: use your own maker's URL | Replace `{client_id}` with a unique identifier for your session. diff --git a/mintlify-docs/cn/ai-tools/build-local-rgb-agent.mdx b/mintlify-docs/cn/ai-tools/build-local-rgb-agent.mdx index 71681c4..c22d447 100644 --- a/mintlify-docs/cn/ai-tools/build-local-rgb-agent.mdx +++ b/mintlify-docs/cn/ai-tools/build-local-rgb-agent.mdx @@ -92,7 +92,7 @@ RGB 资产依附在比特币 UTXO 上，因此节点在接收任何资产之前 KALEIDO_NETWORK=signet RLN_NODE_URL=http://localhost:3001 npx -y kaleido-mcp ``` -服务器会输出 `network: signet` 并在 stdio 上等待。你不需要手动保持它运行：下一步中的代理会把它作为子进程启动。这里 `WDK_SEED` 是可选的；不设置时 Spark 工具保持关闭，RGB、DEX、支付和行情工具照常可用。全部变量见 [MCP 服务器](/cn/ai-tools/mcp-servers#network-preset)。 +服务器会输出 `network: signet` 并在 stdio 上等待。你不需要手动保持它运行：下一步中的代理会把它作为子进程启动。这里 `WDK_SEED` 是可选的，而且普通的 `npx` 不会安装 Spark 钱包包；缺少它们时 Spark 工具保持关闭，RGB、DEX、支付和行情工具照常可用。全部变量见 [MCP 服务器](/cn/ai-tools/mcp-servers#network-preset)。 想在写代码之前先试用这些工具？用[客户端配置](/cn/ai-tools/mcp-servers#client-configuration)中的配置把同一条命令添加到 Claude Desktop 或 Claude Code，然后询问你的 RGB 余额。本教程余下部分会把这个托管模型换成本地模型。 diff --git a/mintlify-docs/cn/ai-tools/getting-started.mdx b/mintlify-docs/cn/ai-tools/getting-started.mdx index f7e019b..41d190d 100644 --- a/mintlify-docs/cn/ai-tools/getting-started.mdx +++ b/mintlify-docs/cn/ai-tools/getting-started.mdx @@ -11,8 +11,8 @@ description: "选择把 AI 代理接入比特币的方式：MCP 服务器、Kale | 要求 | 说明 | |-------------|---------| | **一个测试网络** | signet。KaleidoSwap API 在 `https://api.signet.kaleidoswap.com` 提供 signet 实例，[RGB 水龙头](https://faucet.mutinynet.kaleidoswap.com)可发放测试资产。首次运行绝不要用主网 | -| **一份钱包种子** | 用于测试网络的一次性 BIP-39 助记词，设置到 `WDK_SEED` | -| **一个节点** | 仅 `wdk_*` 工具和原子交换需要。[KaleidoCLI](/cn/cli/installation) 一条命令即可启动一个 signet RGB Lightning Node。Spark 工具只需要种子，行情数据什么都不需要 | +| **一份钱包种子** | 仅 Spark 工具需要：用于测试网络的一次性 BIP-39 助记词，设置到 `WDK_SEED`，并安装可选的 Spark 钱包包（见 [MCP 服务器](/cn/ai-tools/mcp-servers)） | +| **一个节点** | 仅 `wdk_*` 工具和原子交换需要。[KaleidoCLI](/cn/cli/installation) 一条命令即可启动一个 signet RGB Lightning Node。Spark 工具需要种子和 Spark 钱包包，行情数据什么都不需要 | | **一个 MCP 宿主或 LLM 密钥** | Claude Desktop 或其他 MCP 客户端，或者用于 KaleidoAgent 的 Anthropic / OpenAI 密钥 | 如果你还没有安装任何组件，请先看[安装](/cn/ai-tools/installation)。想从一台空机器一路走到让本地模型在 signet 上操作 RGB 资产，请按照[构建本地 RGB 代理](/cn/ai-tools/build-local-rgb-agent)操作。 diff --git a/mintlify-docs/cn/ai-tools/installation.mdx b/mintlify-docs/cn/ai-tools/installation.mdx index 3e3eb1d..d55fe0f 100644 --- a/mintlify-docs/cn/ai-tools/installation.mdx +++ b/mintlify-docs/cn/ai-tools/installation.mdx @@ -30,6 +30,8 @@ KALEIDO_NETWORK=signet npx -y kaleido-mcp 请运行一次 `npx -y kaleido-mcp@latest`。 +自 0.3.1 起，Spark 和 Liquid 钱包是可选的，普通的 `npx` 不会安装它们。如需启用，请运行 `npx -y -p kaleido-mcp -p @tetherto/wdk-wallet-spark -p @kaleidorg/wdk-wallet-liquid kaleido-mcp`，并设置 `WDK_SEED` / `LIQUID_MNEMONIC`。 + 使用 RGB 工具还需要一个 RGB Lightning Node。[KaleidoCLI](/cn/cli/installation) 可以在 Docker 中运行一个 signet 节点，完整流程见[构建本地 RGB 代理](/cn/ai-tools/build-local-rgb-agent)。 另有三个按钱包划分的服务器 `wdk-wallet-mcp`、`wdk-wallet-spark-mcp` 和 `wdk-wallet-liquid-mcp`，它们保持独立而未并入网关，需要从源码构建： diff --git a/mintlify-docs/cn/ai-tools/mcp-servers.mdx b/mintlify-docs/cn/ai-tools/mcp-servers.mdx index 427a801..0cf29f0 100644 --- a/mintlify-docs/cn/ai-tools/mcp-servers.mdx +++ b/mintlify-docs/cn/ai-tools/mcp-servers.mdx @@ -64,6 +64,16 @@ KALEIDO_NETWORK=signet npx -y kaleido-mcp `npx` 解析到了较旧的缓存版本，请运行一次 `npx -y kaleido-mcp@latest`，或从源码构建。 + + 自 0.3.1 起，Spark 和 Liquid 钱包是可选的 peer 依赖，普通的 `npx -y kaleido-mcp` + 不会安装它们。设置了 `WDK_SEED` 或 `LIQUID_MNEMONIC` 但缺少对应包时，服务器仍会启动， + 并输出安装提示。启用方法： + + ```bash + npx -y -p kaleido-mcp -p @tetherto/wdk-wallet-spark -p @kaleidorg/wdk-wallet-liquid kaleido-mcp + ``` + + 实际使用中由 MCP 宿主替你执行这条命令，把宿主配置指向该命令即可（见下面的[客户端配置](#client-configuration)）。若用于开发，或要运行某个特定提交，请改为从源码构建： ```bash @@ -85,24 +95,25 @@ PORT=3010 KALEIDO_NETWORK=signet WDK_SEED="word1 word2 ..." node dist/index.js ### 网络预设 {#network-preset} -`KALEIDO_NETWORK` 用一个变量选定一组默认值，可取 `mainnet`（默认）或 `signet`： +`KALEIDO_NETWORK` 用一个变量选定一组默认值，可取 `signet`（自 0.3.1 起为默认）或 `mainnet`： | 预设 | KaleidoSwap API | Spark 网络 | |--------|-----------------|---------------| -| `mainnet` | `https://api.kaleidoswap.com` | `MAINNET` | | `signet` | `https://api.signet.kaleidoswap.com` | Spark 测试网络（Spark SDK 中名为 `REGTEST`） | +| `mainnet` | 无：把 `KALEIDOSWAP_API_URL` 设为你自己的做市商端点 | `MAINNET` | -预设只负责填充默认值。你显式设置的任何变量（例如 `KALEIDOSWAP_API_URL` 或 `SPARK_NETWORK`）都会覆盖它。未知取值会让服务器在启动时直接退出，而不是悄悄回退到主网。`RLN_NODE_URL` 不属于预设：请把它指向你自己的节点，在 signet 上通常就是 [KaleidoCLI](/cn/cli/installation) 运行在 `http://localhost:3001` 的那个节点。 +预设只负责填充默认值。你显式设置的任何变量（例如 `KALEIDOSWAP_API_URL` 或 `SPARK_NETWORK`）都会覆盖它。KaleidoSwap 目前没有公开的主网 API，因此 `mainnet` 未设置 `KALEIDOSWAP_API_URL` 时，服务器会在启动时直接退出；未知取值同样如此。`RLN_NODE_URL` 不属于预设：请把它指向你自己的节点，在 signet 上通常就是 [KaleidoCLI](/cn/cli/installation) 运行在 `http://localhost:3001` 的那个节点。 | 环境变量 | 是否必需 | 说明 | |---------|----------|--------------| -| `KALEIDO_NETWORK` | 否 | `mainnet`（默认）或 `signet`。设置[网络预设](#network-preset)中的默认值 | -| `WDK_SEED` | 使用 Spark 工具时必需 | Spark 钱包的 BIP-39 助记词。没有它服务器仍能启动，只是 Spark 工具会被禁用 | +| `KALEIDO_NETWORK` | 否 | `signet`（默认）或 `mainnet`。设置[网络预设](#network-preset)中的默认值 | +| `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` | 否 | 覆盖预设中的 KaleidoSwap API URL，也接受 `KALEIDO_API_URL` | +| `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` 的备选 | @@ -252,7 +263,7 @@ PORT=3010 KALEIDO_NETWORK=signet WDK_SEED="word1 word2 ..." node dist/index.js "mcpServers": { "kaleido": { "command": "npx", - "args": ["-y", "kaleido-mcp"], + "args": ["-y", "-p", "kaleido-mcp", "-p", "@tetherto/wdk-wallet-spark", "kaleido-mcp"], "env": { "KALEIDO_NETWORK": "signet", "WDK_SEED": "your twelve word seed phrase", @@ -268,7 +279,7 @@ claude mcp add kaleido \ --env KALEIDO_NETWORK=signet \ --env RLN_NODE_URL=http://localhost:3001 \ --env WDK_SEED="your twelve word seed phrase" \ - -- npx -y kaleido-mcp + -- npx -y -p kaleido-mcp -p @tetherto/wdk-wallet-spark kaleido-mcp ``` ```json wdk-wallet-mcp @@ -301,7 +312,7 @@ claude mcp add kaleido \ ``` -在 Claude Desktop 中，配置文件是 `claude_desktop_config.json`（**Settings > Developer > Edit Config**）。`WDK_SEED` 是可选的：不设置时 Spark 工具会被禁用，而 RGB 节点、DEX、支付和行情工具照常可用。独立的 Spark 服务器没有网络预设，因此直接设置 `SPARK_NETWORK`；`REGTEST` 是 Spark SDK 对其托管测试网络的命名。 +在 Claude Desktop 中，配置文件是 `claude_desktop_config.json`（**Settings > Developer > Edit Config**）。`WDK_SEED` 和 `@tetherto/wdk-wallet-spark` 包都是可选的：不提供时 Spark 工具会被禁用，而 RGB 节点、DEX、支付和行情工具照常可用。独立的 Spark 服务器没有网络预设，因此直接设置 `SPARK_NETWORK`；`REGTEST` 是 Spark SDK 对其托管测试网络的命名。 ## 首次运行 {#first-run} diff --git a/mintlify-docs/cn/ai-tools/skills.mdx b/mintlify-docs/cn/ai-tools/skills.mdx index 5a09652..4903236 100644 --- a/mintlify-docs/cn/ai-tools/skills.mdx +++ b/mintlify-docs/cn/ai-tools/skills.mdx @@ -38,5 +38,5 @@ skill 可以在运行时通过代理的 `/skills` [状态 API 接口端点](/cn/ /plugin install kaleido-mind@kaleidoswap ``` -该插件以 `KALEIDO_NETWORK=signet` 运行 `npx -y kaleido-mcp`。将 `RLN_NODE_URL` 指向你的 RGB Lightning Node，并设置 `WDK_SEED` 以启用 Spark 钱包工具。部分 KaleidoMind skill（Spark 钱包、Bitrefill、Flashnet、商户查找）依赖仅由 KaleidoMind 运行时提供的工具。 +该插件以 `KALEIDO_NETWORK=signet` 运行 `npx -y kaleido-mcp`。将 `RLN_NODE_URL` 指向你的 RGB Lightning Node。该插件不会安装可选的 Spark 钱包包；如需使用 Spark 工具，请按 [MCP 服务器](/cn/ai-tools/mcp-servers#client-configuration)中的说明自行配置 `kaleido-mcp`。部分 KaleidoMind skill（Spark 钱包、Bitrefill、Flashnet、商户查找）依赖仅由 KaleidoMind 运行时提供的工具。 diff --git a/mintlify-docs/cn/ai-tools/troubleshooting.mdx b/mintlify-docs/cn/ai-tools/troubleshooting.mdx index 23b7885..032b7db 100644 --- a/mintlify-docs/cn/ai-tools/troubleshooting.mdx +++ b/mintlify-docs/cn/ai-tools/troubleshooting.mdx @@ -20,7 +20,7 @@ description: "解决 KaleidoSwap AI 工具的常见问题：MCP 连接失败、 **现象**：宿主报告进程在启动时就已终止。 - **原因**：缺少某个必需的环境变量。独立的 `wdk-wallet-spark-mcp` 在没有 `WDK_SPARK_SEED` 时会拒绝启动。`kaleido-mcp` 要宽容一些：没有 `WDK_SEED` 时它仍会启动，记录一条警告，并禁用 Spark 工具。 + **原因**：缺少某个必需的环境变量。独立的 `wdk-wallet-spark-mcp` 在没有 `WDK_SPARK_SEED` 时会拒绝启动。`kaleido-mcp` 要宽容一些：没有 `WDK_SEED`，或缺少可选包 `@tetherto/wdk-wallet-spark` 时，它仍会启动，记录一条警告或安装提示，并禁用 Spark 工具。但在 `KALEIDO_NETWORK=mainnet` 下如果没有 `KALEIDOSWAP_API_URL`，它会拒绝启动，因为没有公开的主网 API。 **解决办法**： 1. 确认种子变量写在宿主配置的 `env` 块中，而不是你的 shell 里（宿主不会继承你的 shell 环境）。 diff --git a/mintlify-docs/cn/api-reference/additional-resources.mdx b/mintlify-docs/cn/api-reference/additional-resources.mdx index 57df854..bba7b7f 100644 --- a/mintlify-docs/cn/api-reference/additional-resources.mdx +++ b/mintlify-docs/cn/api-reference/additional-resources.mdx @@ -51,7 +51,7 @@ description: "面向 KaleidoSwap API 集成方的链接汇总：OpenAPI 规范 | 环境 | REST 基础 URL | WebSocket | |-------------|---------------|-----------| | **signet（MutinyNet）** | `https://api.signet.kaleidoswap.com/api/v1` | `wss://api.signet.kaleidoswap.com/api/v1/market/ws/{client_id}` | -| **主网** | `https://api.kaleidoswap.com/api/v1`（即将推出） | `wss://api.kaleidoswap.com/api/v1/market/ws/{client_id}`（即将推出） | +| **主网** | 暂无公开端点：请使用你自己的做市商 URL | — | 资产 ID 在不同环境之间不通用 —— 请从 `GET /api/v1/market/assets` 读取，并按环境区分配置。 diff --git a/mintlify-docs/cn/api-reference/faq.mdx b/mintlify-docs/cn/api-reference/faq.mdx index f20ecab..5085677 100644 --- a/mintlify-docs/cn/api-reference/faq.mdx +++ b/mintlify-docs/cn/api-reference/faq.mdx @@ -31,12 +31,12 @@ description: "关于 KaleidoSwap 交换 API 的常见问题：认证、Maker API - signet（MutinyNet）目前已上线；主网即将推出。 + signet（MutinyNet）目前已上线。主网暂无公开端点；如需在主网上集成，请把集成指向你自己的做市商 URL。 | 环境 | REST 基础 URL | WebSocket | |-------------|---------------|-----------| | **signet** | `https://api.signet.kaleidoswap.com/api/v1` | `wss://api.signet.kaleidoswap.com/api/v1/market/ws/{client_id}` | - | **主网** | `https://api.kaleidoswap.com/api/v1`（即将推出） | `wss://api.kaleidoswap.com/api/v1/market/ws/{client_id}`（即将推出） | + | **主网** | 暂无公开端点：请使用你自己的做市商 URL | — | 接口端点页面上的交互式演练场运行在 signet。 diff --git a/mintlify-docs/cn/api-reference/getting-started.mdx b/mintlify-docs/cn/api-reference/getting-started.mdx index d7b6701..02a3d10 100644 --- a/mintlify-docs/cn/api-reference/getting-started.mdx +++ b/mintlify-docs/cn/api-reference/getting-started.mdx @@ -18,9 +18,7 @@ KaleidoSwap API 通过 HTTPS 提供访问，以保证通信安全。可用环境 - **基础 URL：** `https://api.signet.kaleidoswap.com/api/v1` ### 比特币主网（即将推出） -主网环境是面向真实交易的生产接口端点。发布进展请关注后续更新。 - -- **基础 URL：** `https://api.kaleidoswap.com/api/v1` +目前还没有公开的主网端点。如需在主网上集成，请把客户端指向你自己的做市商基础 URL；API 路径与 signet 相同。 --- diff --git a/mintlify-docs/cn/api-reference/swap-apis.mdx b/mintlify-docs/cn/api-reference/swap-apis.mdx index f566c34..40ec354 100644 --- a/mintlify-docs/cn/api-reference/swap-apis.mdx +++ b/mintlify-docs/cn/api-reference/swap-apis.mdx @@ -46,7 +46,7 @@ description: 用于发起、执行和查询原子 HTLC 交换的接口端点 — | Environment | URL | |-------------|-----| | **Signet** | `wss://api.signet.kaleidoswap.com/api/v1/market/ws/{client_id}` | -| **Mainnet** | `wss://api.kaleidoswap.com/api/v1/market/ws/{client_id}` *（即将上线）* | +| **Mainnet** | 暂无公开端点：请使用你自己的做市商 URL | ### 说明 建立 WebSocket 连接，向做市方请求实时报价。该协议采用请求/响应模式：客户端发送一条消息，服务端针对该消息回复。它没有订阅机制 —— 想让价格保持新鲜，就在需要更新报价时再发一条 `quote_request`。 diff --git a/mintlify-docs/cn/api-reference/swap-protocol.mdx b/mintlify-docs/cn/api-reference/swap-protocol.mdx index 908826c..5876c18 100644 --- a/mintlify-docs/cn/api-reference/swap-protocol.mdx +++ b/mintlify-docs/cn/api-reference/swap-protocol.mdx @@ -68,7 +68,7 @@ Taker Client Maker (RGB-LSP) Taker RLN | 环境 | URL | |-------------|-----| | **Signet** | `wss://api.signet.kaleidoswap.com/api/v1/market/ws/{client_id}` | -| **主网** | `wss://api.kaleidoswap.com/api/v1/market/ws/{client_id}` *（即将推出）* | +| **主网** | 暂无公开端点：请使用你自己的做市商 URL | 请将 `{client_id}` 替换为你本次会话的唯一标识符。 diff --git a/mintlify-docs/cn/desktop-app/wallet/deposits.mdx b/mintlify-docs/cn/desktop-app/wallet/deposits.mdx index 13166e5..d2a3e1d 100644 --- a/mintlify-docs/cn/desktop-app/wallet/deposits.mdx +++ b/mintlify-docs/cn/desktop-app/wallet/deposits.mdx @@ -28,6 +28,7 @@ description: "向 KaleidoSwap 钱包存入比特币和 RGB 资产：链上地址 - regtest：可以在 Telegram 上体验 RGB LN Bot（@rgb_lightning_bot）的各项功能。 - signet：可以使用 [Mutiny 水龙头](https://faucet.mutinynet.com/)，在「How much?」字段输入想接收的聪数量，把 signet 比特币地址粘贴到水龙头的「Destination」字段，然后点击「Make it rain」即可收到资金。 +- signet RGB 资产：[KaleidoSwap RGB 水龙头](https://faucet.mutinynet.kaleidoswap.com)会把测试资产发送到你钱包生成的 RGB 发票。使用 GitHub 登录。 --- diff --git a/mintlify-docs/cn/sdk/installation.mdx b/mintlify-docs/cn/sdk/installation.mdx index 3495779..bb25aad 100644 --- a/mintlify-docs/cn/sdk/installation.mdx +++ b/mintlify-docs/cn/sdk/installation.mdx @@ -141,6 +141,6 @@ client = KaleidoClient.create( | 环境 | API URL | WebSocket URL | 状态 | |-------------|---------|---------------|--------| | **signet** | `https://api.signet.kaleidoswap.com` | `wss://api.signet.kaleidoswap.com/api/v1/market/ws/{client_id}` | 已上线（默认） | -| **主网** | `https://api.kaleidoswap.com` | `wss://api.kaleidoswap.com/api/v1/market/ws/{client_id}` | 即将上线 | +| **主网** | 你自己的做市商 URL | — | 暂无公开端点 | 装好依赖包之后，请继续阅读[快速上手](/cn/sdk/getting-started)，创建客户端并获取第一笔报价。 diff --git a/mintlify-docs/cn/whats-kaleidoswap/quickstart.mdx b/mintlify-docs/cn/whats-kaleidoswap/quickstart.mdx index 7063215..d53f7c5 100644 --- a/mintlify-docs/cn/whats-kaleidoswap/quickstart.mdx +++ b/mintlify-docs/cn/whats-kaleidoswap/quickstart.mdx @@ -266,7 +266,7 @@ curl -X POST https://api.signet.kaleidoswap.com/api/v1/market/quote \ - **API URL**：`https://api.kaleidoswap.com/api/v1` + **API URL**：暂无公开端点，请使用你自己的做市商 URL - 比特币主网 —— 生产环境 - **即将上线** diff --git a/mintlify-docs/desktop-app/wallet/deposits.mdx b/mintlify-docs/desktop-app/wallet/deposits.mdx index 727a114..5d5670b 100644 --- a/mintlify-docs/desktop-app/wallet/deposits.mdx +++ b/mintlify-docs/desktop-app/wallet/deposits.mdx @@ -28,6 +28,7 @@ If during the wallet creation you selected a test network to try KaleidoSwap out - Regtest: you can explore the functions of the RGB LN Bot on telegram (@rgb_lightning_bot). - Signet: you can use the [Mutiny Faucet](https://faucet.mutinynet.com/) by entering the desired amount of SATs you want to receive in the field "How much?", pasting the signet Bitcoin address in the “Destination” field of the faucet and clicking "Make it rain" to receive the deposit. +- Signet RGB assets: the [KaleidoSwap RGB faucet](https://faucet.mutinynet.kaleidoswap.com) sends test assets to an RGB invoice from your wallet. Sign in with GitHub. --- diff --git a/mintlify-docs/sdk/installation.mdx b/mintlify-docs/sdk/installation.mdx index e257d66..1e35bda 100644 --- a/mintlify-docs/sdk/installation.mdx +++ b/mintlify-docs/sdk/installation.mdx @@ -141,6 +141,6 @@ Pass the API URL as `baseUrl` / `base_url`; the SDK appends the `/api/v1` path i | Environment | API URL | WebSocket URL | Status | |-------------|---------|---------------|--------| | **Signet** | `https://api.signet.kaleidoswap.com` | `wss://api.signet.kaleidoswap.com/api/v1/market/ws/{client_id}` | Live (default) | -| **Mainnet** | `https://api.kaleidoswap.com` | `wss://api.kaleidoswap.com/api/v1/market/ws/{client_id}` | Coming soon | +| **Mainnet** | Your own maker's URL | — | No public endpoint yet | With the package installed, continue to [Getting Started](/sdk/getting-started) to create a client and request your first quote. diff --git a/mintlify-docs/wallet-engine/concepts.mdx b/mintlify-docs/wallet-engine/concepts.mdx index be473e8..95defe3 100644 --- a/mintlify-docs/wallet-engine/concepts.mdx +++ b/mintlify-docs/wallet-engine/concepts.mdx @@ -115,7 +115,7 @@ Engine modules that persist state read `getPlatform()?.storage`. Modules whose c ```ts import { KaleidoswapSwap } from '@kaleidorg/wallet-engine/swap' -const swap = new KaleidoswapSwap(rlnAccount, { baseUrl: 'https://api.kaleidoswap.com' }) +const swap = new KaleidoswapSwap(rlnAccount, { baseUrl: 'https://api.signet.kaleidoswap.com' }) const quote = await swap.getQuote({ fromAsset: 'rgb:USDT…', toAsset: 'BTC', diff --git a/mintlify-docs/whats-kaleidoswap/quickstart.mdx b/mintlify-docs/whats-kaleidoswap/quickstart.mdx index b31b3dd..472c642 100644 --- a/mintlify-docs/whats-kaleidoswap/quickstart.mdx +++ b/mintlify-docs/whats-kaleidoswap/quickstart.mdx @@ -266,7 +266,7 @@ curl -X POST https://api.signet.kaleidoswap.com/api/v1/market/quote \ - **API URL**: `https://api.kaleidoswap.com/api/v1` + **API URL**: no public endpoint yet; use your own maker's URL - Bitcoin Mainnet — production environment - **Coming soon**