From e8660613284e3546285ebf8ebbfffcc996ee44a8 Mon Sep 17 00:00:00 2001 From: Emile Jellinek Date: Mon, 17 Aug 2026 16:29:09 +0200 Subject: [PATCH 1/2] docs: align Reference groups across tabs and rebuild CLI docs from source Every product tab now opens with Overview / Installation / Getting Started and closes with the same Reference group. The CLI and API Reference tabs were the only two missing the FAQ / Troubleshooting / Additional Resources trio; both now have it, and Installation is split out of Getting Started for the CLI and the SDK. The CLI tab is verified against the kaleido-cli source (v0.1.1) rather than its README, which fixes several inaccuracies: - Documents `node unlock --chain-sync block|transaction` and the three service profiles, previously undocumented - Corrects the install path: the CLI is not on PyPI, so `pip install` cannot work; the one-line bootstrap installer is now the primary route - Records the display-vs-raw amount split (`market quote` and `swap atomic` take display units, `asset` and `payment` take raw) and the per-command layer sets - Drops the `swap order` group from the copy, since it no longer exists - Fixes `asset send-batch` (takes a JSON file path), `channel close` (`--force`), `wallet create-utxos` flags, and ~20 further flag gaps - New Troubleshooting is built on the CLI's actual error strings - Renames nav groups and page labels for cross-tab consistency Error Handling pages are folded into Troubleshooting under an `#error-reference` section, and the standalone pages are removed. All changes are mirrored in the Simplified Chinese tree. Co-Authored-By: Claude Opus 5 --- .../ai-tools/additional-resources.mdx | 56 +- mintlify-docs/ai-tools/faq.mdx | 4 +- mintlify-docs/ai-tools/getting-started.mdx | 92 +-- mintlify-docs/ai-tools/installation.mdx | 14 +- mintlify-docs/ai-tools/introduction.mdx | 4 +- mintlify-docs/ai-tools/kaleido-agent.mdx | 36 +- mintlify-docs/ai-tools/kaleido-mind.mdx | 4 +- mintlify-docs/ai-tools/mcp-servers.mdx | 52 ++ mintlify-docs/ai-tools/troubleshooting.mdx | 6 +- .../api-reference/additional-resources.mdx | 111 ++++ .../api-reference/error-handling.mdx | 143 ----- mintlify-docs/api-reference/faq.mdx | 124 ++++ .../api-reference/getting-started.mdx | 21 +- mintlify-docs/api-reference/introduction.mdx | 16 +- mintlify-docs/api-reference/market-apis.mdx | 6 +- .../api-reference/rgb-lsps1-apis.mdx | 4 - mintlify-docs/api-reference/swap-apis.mdx | 4 - mintlify-docs/api-reference/swap-protocol.mdx | 17 - .../api-reference/troubleshooting.mdx | 424 +++++++++++++ mintlify-docs/cli/additional-resources.mdx | 73 +++ mintlify-docs/cli/channels-lsp.mdx | 34 +- mintlify-docs/cli/command-reference.mdx | 68 ++- mintlify-docs/cli/faq.mdx | 205 +++++++ mintlify-docs/cli/getting-started.mdx | 46 +- mintlify-docs/cli/installation.mdx | 67 ++ mintlify-docs/cli/introduction.mdx | 25 +- mintlify-docs/cli/market-and-swaps.mdx | 30 +- mintlify-docs/cli/node-environments.mdx | 57 +- mintlify-docs/cli/troubleshooting.mdx | 476 +++++++++++++++ mintlify-docs/cli/wallet-assets-payments.mdx | 53 +- .../cn/ai-tools/additional-resources.mdx | 56 +- mintlify-docs/cn/ai-tools/faq.mdx | 4 +- mintlify-docs/cn/ai-tools/getting-started.mdx | 92 +-- mintlify-docs/cn/ai-tools/installation.mdx | 20 +- mintlify-docs/cn/ai-tools/introduction.mdx | 4 +- mintlify-docs/cn/ai-tools/kaleido-agent.mdx | 38 +- mintlify-docs/cn/ai-tools/kaleido-mind.mdx | 4 +- mintlify-docs/cn/ai-tools/mcp-servers.mdx | 52 ++ mintlify-docs/cn/ai-tools/troubleshooting.mdx | 6 +- .../cn/api-reference/additional-resources.mdx | 111 ++++ .../cn/api-reference/error-handling.mdx | 143 ----- mintlify-docs/cn/api-reference/faq.mdx | 124 ++++ .../cn/api-reference/getting-started.mdx | 21 +- .../cn/api-reference/introduction.mdx | 16 +- .../cn/api-reference/market-apis.mdx | 4 - .../cn/api-reference/rgb-lsps1-apis.mdx | 4 - mintlify-docs/cn/api-reference/swap-apis.mdx | 4 - .../cn/api-reference/swap-protocol.mdx | 17 - .../cn/api-reference/troubleshooting.mdx | 424 +++++++++++++ mintlify-docs/cn/cli/additional-resources.mdx | 73 +++ mintlify-docs/cn/cli/channels-lsp.mdx | 34 +- mintlify-docs/cn/cli/command-reference.mdx | 68 ++- mintlify-docs/cn/cli/faq.mdx | 203 +++++++ mintlify-docs/cn/cli/getting-started.mdx | 46 +- mintlify-docs/cn/cli/installation.mdx | 67 ++ mintlify-docs/cn/cli/introduction.mdx | 25 +- mintlify-docs/cn/cli/market-and-swaps.mdx | 30 +- mintlify-docs/cn/cli/node-environments.mdx | 59 +- mintlify-docs/cn/cli/troubleshooting.mdx | 476 +++++++++++++++ .../cn/cli/wallet-assets-payments.mdx | 53 +- .../desktop-app/channels/channel-backups.mdx | 4 +- .../support/additional-resources.mdx | 33 +- mintlify-docs/cn/desktop-app/support/faq.mdx | 6 +- .../cn/desktop-app/support/settings.mdx | 4 +- .../desktop-app/support/troubleshooting.mdx | 12 +- .../additional-resources.mdx | 21 +- .../extensions/kaleidoswap-extension/faq.mdx | 4 +- .../kaleidoswap-extension/getting-started.mdx | 4 +- .../kaleidoswap-extension/troubleshooting.mdx | 6 +- mintlify-docs/cn/sdk/additional-resources.mdx | 60 +- mintlify-docs/cn/sdk/api-reference.mdx | 9 + mintlify-docs/cn/sdk/best-practices.mdx | 125 +--- mintlify-docs/cn/sdk/changelog.mdx | 34 +- mintlify-docs/cn/sdk/error-handling.mdx | 372 ----------- mintlify-docs/cn/sdk/examples.mdx | 4 +- mintlify-docs/cn/sdk/faq.mdx | 14 +- mintlify-docs/cn/sdk/getting-started.mdx | 149 +---- mintlify-docs/cn/sdk/how-to-swap.mdx | 19 +- mintlify-docs/cn/sdk/installation.mdx | 146 +++++ mintlify-docs/cn/sdk/introduction.mdx | 13 +- .../cn/sdk/maker-api-compatibility.mdx | 52 +- mintlify-docs/cn/sdk/nwc.mdx | 4 +- .../cn/sdk/rln-api-compatibility.mdx | 60 +- mintlify-docs/cn/sdk/troubleshooting.mdx | 278 ++++++--- mintlify-docs/cn/sdk/utilities.mdx | 4 +- mintlify-docs/cn/sdk/websocket.mdx | 12 +- .../additional-resources.mdx | 123 ++++ .../cn/whats-kaleidoswap/glossary.mdx | 4 +- .../cn/whats-kaleidoswap/introduction.mdx | 2 +- .../cn/whats-kaleidoswap/quickstart.mdx | 8 +- .../cn/whats-kaleidoswap/troubleshooting.mdx | 575 ++---------------- .../desktop-app/channels/channel-backups.mdx | 4 +- .../support/additional-resources.mdx | 33 +- mintlify-docs/desktop-app/support/faq.mdx | 6 +- .../desktop-app/support/settings.mdx | 4 +- .../desktop-app/support/troubleshooting.mdx | 12 +- mintlify-docs/docs.json | 98 ++- .../additional-resources.mdx | 21 +- .../extensions/kaleidoswap-extension/faq.mdx | 4 +- .../kaleidoswap-extension/getting-started.mdx | 4 +- .../kaleidoswap-extension/troubleshooting.mdx | 6 +- mintlify-docs/sdk/additional-resources.mdx | 60 +- mintlify-docs/sdk/api-reference.mdx | 9 + mintlify-docs/sdk/best-practices.mdx | 125 +--- mintlify-docs/sdk/changelog.mdx | 34 +- mintlify-docs/sdk/error-handling.mdx | 372 ----------- mintlify-docs/sdk/examples.mdx | 4 +- mintlify-docs/sdk/faq.mdx | 14 +- mintlify-docs/sdk/getting-started.mdx | 143 +---- mintlify-docs/sdk/how-to-swap.mdx | 19 +- mintlify-docs/sdk/installation.mdx | 146 +++++ mintlify-docs/sdk/introduction.mdx | 13 +- mintlify-docs/sdk/maker-api-compatibility.mdx | 52 +- mintlify-docs/sdk/nwc.mdx | 4 +- mintlify-docs/sdk/rln-api-compatibility.mdx | 60 +- mintlify-docs/sdk/troubleshooting.mdx | 282 ++++++--- mintlify-docs/sdk/utilities.mdx | 2 +- mintlify-docs/sdk/websocket.mdx | 10 +- mintlify-docs/snippets/versions.mdx | 4 +- .../additional-resources.mdx | 123 ++++ mintlify-docs/whats-kaleidoswap/glossary.mdx | 4 +- .../whats-kaleidoswap/introduction.mdx | 2 +- .../whats-kaleidoswap/quickstart.mdx | 8 +- .../whats-kaleidoswap/troubleshooting.mdx | 573 ++--------------- scripts/check-cn-parity.py | 2 +- 125 files changed, 5085 insertions(+), 3883 deletions(-) create mode 100644 mintlify-docs/api-reference/additional-resources.mdx delete mode 100644 mintlify-docs/api-reference/error-handling.mdx create mode 100644 mintlify-docs/api-reference/faq.mdx create mode 100644 mintlify-docs/api-reference/troubleshooting.mdx create mode 100644 mintlify-docs/cli/additional-resources.mdx create mode 100644 mintlify-docs/cli/faq.mdx create mode 100644 mintlify-docs/cli/installation.mdx create mode 100644 mintlify-docs/cli/troubleshooting.mdx create mode 100644 mintlify-docs/cn/api-reference/additional-resources.mdx delete mode 100644 mintlify-docs/cn/api-reference/error-handling.mdx create mode 100644 mintlify-docs/cn/api-reference/faq.mdx create mode 100644 mintlify-docs/cn/api-reference/troubleshooting.mdx create mode 100644 mintlify-docs/cn/cli/additional-resources.mdx create mode 100644 mintlify-docs/cn/cli/faq.mdx create mode 100644 mintlify-docs/cn/cli/installation.mdx create mode 100644 mintlify-docs/cn/cli/troubleshooting.mdx delete mode 100644 mintlify-docs/cn/sdk/error-handling.mdx create mode 100644 mintlify-docs/cn/sdk/installation.mdx create mode 100644 mintlify-docs/cn/whats-kaleidoswap/additional-resources.mdx delete mode 100644 mintlify-docs/sdk/error-handling.mdx create mode 100644 mintlify-docs/sdk/installation.mdx create mode 100644 mintlify-docs/whats-kaleidoswap/additional-resources.mdx diff --git a/mintlify-docs/ai-tools/additional-resources.mdx b/mintlify-docs/ai-tools/additional-resources.mdx index baf9748..2836e1d 100644 --- a/mintlify-docs/ai-tools/additional-resources.mdx +++ b/mintlify-docs/ai-tools/additional-resources.mdx @@ -23,16 +23,6 @@ Every AI surface is open source under the [KaleidoSwap organisation](https://git -### Focused MCP servers - -| Repository | Tool prefix | Domain | -|-----------|-------------|--------| -| [wdk-wallet-mcp](https://github.com/kaleidoswap/wdk-wallet-mcp) | `wdk_*` | RGB Lightning Node wallet, channels, atomic swap taker | -| [wdk-wallet-spark-mcp](https://github.com/kaleidoswap/wdk-wallet-spark-mcp) | `spark_*` | Spark wallet, Lightning, token transfers, BTC bridge | -| [wdk-wallet-liquid-mcp](https://github.com/kaleidoswap/wdk-wallet-liquid-mcp) | `liquid_*` | Liquid wallet, L-BTC and asset balances, confidential sends | -| [kaleidoswap-mcp](https://github.com/kaleidoswap/kaleidoswap-mcp) _(archived)_ | `kaleidoswap_*` | Superseded by the `kaleidoswap_*` tools in kaleido-mcp | -| [l402-gateway-mcp](https://github.com/kaleidoswap/l402-gateway-mcp) _(archived)_ | `mpp_*`, `l402_*` | Superseded by the `mpp_*` / `l402_*` tools in kaleido-mcp | - ## Protocol Specifications @@ -50,42 +40,32 @@ Every AI surface is open source under the [KaleidoSwap organisation](https://git -## KaleidoSwap References +## Get Help -Reading these first makes the agent tooling considerably easier to reason about, since the tools are thin wrappers over them. +Check [Troubleshooting](/ai-tools/troubleshooting) for errors and the [FAQ](/ai-tools/faq) for questions. - - - How the atomic HTLC flow settles, which is what the swap tools orchestrate. - - - The channel-ordering endpoints behind `kaleidoswap_lsp_*`. - - - The binary KaleidoAgent shells out to, and the source of the node lifecycle tools. - - - Call the swap infrastructure directly from TypeScript or Python, skipping the agent layer. - - +For anything else, report a problem through your preferred channel from the options below, including: -## Product and Community +1. Which surface and version (MCP server name, KaleidoAgent commit, or Desktop App version) +2. The network you are on (Regtest, Signet, or mainnet) +3. The tool name that failed and the error text +4. Host and runtime versions (MCP client, Node.js) +5. Your config with the seed and any keys removed - - - Product overview, plus readable and downloadable copies of each skill. + + + Ask the community. - - Community support and discussion. - - - Issues, pull requests, and the full source. + + Report a bug on the relevant repository. Direct support for urgent issues. - - When reporting a problem with an AI surface, include the tool name that failed, the network you are on, and your config with the seed and any API keys removed. See [Troubleshooting](/ai-tools/troubleshooting) first. - +--- + + + Product overview, plus readable and downloadable copies of each skill. + diff --git a/mintlify-docs/ai-tools/faq.mdx b/mintlify-docs/ai-tools/faq.mdx index 8286841..d1ee3c7 100644 --- a/mintlify-docs/ai-tools/faq.mdx +++ b/mintlify-docs/ai-tools/faq.mdx @@ -94,7 +94,9 @@ description: "Common questions about the KaleidoSwap AI tools, covering custody, ## Get Help -Check the [Troubleshooting](/ai-tools/troubleshooting) for errors rather than questions. For anything else, report a problem through your preferred channel from the options below, including: +Check the [Troubleshooting](/ai-tools/troubleshooting) for errors rather than questions, and [Additional Resources](/ai-tools/additional-resources) for upstream documentation and links. + +For anything else, report a problem through your preferred channel from the options below, including: 1. Which surface and version (MCP server name, KaleidoAgent commit, or Desktop App version) 2. The network you are on (Regtest, Signet, or mainnet) diff --git a/mintlify-docs/ai-tools/getting-started.mdx b/mintlify-docs/ai-tools/getting-started.mdx index ee420dc..775b5ed 100644 --- a/mintlify-docs/ai-tools/getting-started.mdx +++ b/mintlify-docs/ai-tools/getting-started.mdx @@ -1,10 +1,10 @@ --- title: "AI Tools: Getting Started" sidebarTitle: "Getting Started" -description: "Connect an AI agent to Bitcoin, from a first read-only tool call on a test network through to a verified quote before you enable live execution" +description: "Pick the right way to connect an AI agent to Bitcoin, MCP servers, KaleidoAgent, or KaleidoMind, with the prerequisites and the spend gate each one gives you" --- -This is the path from an installed tool to a verified swap. It goes read-only first, then quoting, then execution, because every step after the first one moves real value. +Four surfaces expose the same Bitcoin tools to a model, and they differ mostly in who runs the agent loop and what stops a spend. This page covers what to have in place first, which surface fits, and how each one gates the calls that move value. ## Before You Start @@ -26,87 +26,9 @@ If you have not installed anything yet, start with [Installation](/ai-tools/inst | Talk to a wallet by chat or voice, on-device | [KaleidoMind](/ai-tools/kaleido-mind) | | Change agent behavior without touching code | [Skills](/ai-tools/skills) | -## First Run: MCP Servers +Whichever surface you pick, the first run follows the same order: a read-only call, then a wallet call, then a quote, and only then an execution. That order is diagnostic as much as it is cautious. A failure at the read-only step is a connection problem, a failure at the wallet step is a seed or network problem, and anything that reaches a quote has both already ruled out. - - - Drop the `kaleido-mcp` block into your MCP host's config, pointing `KALEIDOSWAP_API_URL` at a test environment and `SPARK_NETWORK` at `REGTEST`. The full JSON is on the [MCP Servers page](/ai-tools/mcp-servers#client-configuration). - - - - MCP hosts read their config at startup. A running client will not pick up a new server until you restart it. - - - - Start with something that cannot move funds. Ask for market data, which needs no seed and no node: - - ``` - What is the current Bitcoin price and the Fear and Greed index? - ``` - - That exercises `l402_get_price` and `l402_get_sentiment`. If it answers, the connection works. - - - - Now confirm the wallet tools resolve: - - ``` - Show me my Spark balance and my Spark address. - ``` - - This calls `spark_get_balance` and `spark_get_address`. An error here is a seed or network problem, not a connection problem. - - - - Ask for a price without placing anything: - - ``` - Quote 100000 sats of BTC into USDT. Do not place an order. - ``` - - `kaleidoswap_get_quote` returns an `rfq_id`, raw amounts, the fee, and an expiry. Read the raw amounts carefully: they are in the asset's smallest unit, not display units. - - - - An atomic swap needs the DEX tools and the wallet tools together, and the node must hold the asset in a channel. The [cross-server sequence](/ai-tools/mcp-servers#atomic-swap-across-servers) shows each call in order. - - - -## First Run: KaleidoAgent - - - - `portfolio.dry_run` defaults to `true` in `agent.config.json`. Leave it there. The agent will reason, decide, and report a trade without submitting it. - - - - ```bash - npm start - ``` - - That runs the agent and the status API on `http://localhost:4242`. For the dashboard, also run `npm run dev:webapp` and open `http://localhost:5173`. - - - - Rather than waiting on the schedule, ask the status API to run one: - - ```bash - curl -X POST http://localhost:4242/run \ - -H 'Content-Type: application/json' \ - -d '{"task_id":"rebalance"}' - ``` - - Then read `GET /status` to see the decision, the balances it saw, and the token cost. - - - - 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. - - - - Set `portfolio.dry_run` to `false` when the dry-run decisions have looked correct across several runs. - - +Each surface carries its own walkthrough: [MCP Servers](/ai-tools/mcp-servers#first-run) and [KaleidoAgent](/ai-tools/kaleido-agent#first-run). KaleidoMind ships inside a host rather than running on its own, so its first run is the [Desktop App installation](/desktop-app/getting-started/installation). [Skills](/ai-tools/skills) change how an agent behaves on any of these surfaces, they are not a surface of their own. ## What Confirmation Looks Like @@ -114,9 +36,9 @@ The two agent surfaces gate spending differently, and it is worth knowing which | Surface | Gate | |---------|------| -| **KaleidoMind** | Structural. Every fund-moving tool is marked `requiresConfirmation`, so the engine pauses for the host's confirmation sheet. The model cannot bypass it | -| **KaleidoAgent** | Policy. `dry_run` plus the risk limits in `agent.config.json`, checked before submission | -| **MCP servers in a generic host** | Whatever your host provides. Most MCP clients prompt per tool call, but that is the client's behaviour, not the server's | +| **[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 | +| **[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 | A generic MCP host is the least protected path. If your client auto-approves tool calls, an LLM can spend from the configured wallet without asking you. Use a test network seed until you know how your client handles approvals. diff --git a/mintlify-docs/ai-tools/installation.mdx b/mintlify-docs/ai-tools/installation.mdx index 3f232c2..b5c92b8 100644 --- a/mintlify-docs/ai-tools/installation.mdx +++ b/mintlify-docs/ai-tools/installation.mdx @@ -8,9 +8,9 @@ Each AI surface installs independently. Pick the one that matches what you are b | Surface | Install path | Prerequisites | |---------|-------------|---------------| -| **[MCP servers](/ai-tools/mcp-servers)** | `npx` for the gateway, local build for the focused servers | Node.js 20+, an MCP host | -| **[KaleidoAgent](/ai-tools/kaleido-agent)** | Clone and build from source | Node.js 20+, KaleidoCLI, Nanobot, an LLM API key | -| **[KaleidoMind](/ai-tools/kaleido-mind)** | Ships inside the Desktop App, or build the repo for development | Desktop App, or pnpm and the QVAC SDK | +| **[MCP servers](#mcp-servers)** | `npx` for the gateway, local build for the focused servers | Node.js 20+, an MCP host | +| **[KaleidoAgent](#kaleidoagent)** | Clone and build from source | Node.js 20+, KaleidoCLI, Nanobot, an LLM API key | +| **[KaleidoMind](#kaleidomind)** | Ships inside the Desktop App, or build the repo for development | Desktop App, or pnpm and the QVAC SDK | Every surface here signs with a real BIP-39 mnemonic or drives a live node. Start on test networks, keep `dry_run` enabled until a setup is verified, and never put a mainnet seed in a file you commit or share. @@ -38,11 +38,11 @@ node dist/index.js `kaleidoswap-mcp` and `l402-gateway-mcp` are archived, their own READMEs point integrators at `kaleido-mcp` instead. Do not clone or build them for a new setup. -Full environment variable reference, stdio vs. HTTP transport, the tool surface, and client config JSON for every server live on the [MCP Servers page](/ai-tools/mcp-servers#installation-&-configuration). +For the full environment variable reference, stdio vs. HTTP transport, the tool surface by domain, and client config JSON for every server, check the [MCP Servers page](/ai-tools/mcp-servers). ## KaleidoAgent -Prerequisites: Node.js 20 or newer, [KaleidoCLI](/cli/getting-started) in `$PATH`, the [Nanobot](https://nanobot.dev) runtime, and an Anthropic or OpenAI API key. +Prerequisites: Node.js 20 or newer, [KaleidoCLI](/cli/installation) in `$PATH`, the [Nanobot](https://nanobot.dev) runtime, and an Anthropic or OpenAI API key. ```bash git clone https://github.com/kaleidoswap/kaleido-agent.git @@ -50,7 +50,7 @@ cd kaleido-agent npm run install:all ``` -From there, setting the API key, configuring the wallet in `agent.config.json`, and starting the dashboard are covered step by step on the [KaleidoAgent page](/ai-tools/kaleido-agent#run-it), along with the container deployment option. +To set the API key, configure the wallet in `agent.config.json`, start the dashboard, or deploy in a container, check the [KaleidoAgent page](/ai-tools/kaleido-agent#run-it). ## KaleidoMind @@ -86,3 +86,5 @@ To exercise the engine against a model without a phone, use the playground from ```bash pnpm play "pay bob 3 eur" ``` + +For how the tiered funnel routes a request, the tool contract shared across transports, the skills the engine loads, and where it runs across desktop, phone, and paired devices, check the [KaleidoMind page](/ai-tools/kaleido-mind). diff --git a/mintlify-docs/ai-tools/introduction.mdx b/mintlify-docs/ai-tools/introduction.mdx index d1aab95..d43c10c 100644 --- a/mintlify-docs/ai-tools/introduction.mdx +++ b/mintlify-docs/ai-tools/introduction.mdx @@ -25,9 +25,9 @@ The product overview lives at [kaleidoswap.com/products/ai-tools](https://kaleid - + Every tool surface here signs with a real BIP-39 mnemonic or drives a live node. See [Installation](/ai-tools/installation) for how to keep test and mainnet seeds apart. - + ## Which one do I need? diff --git a/mintlify-docs/ai-tools/kaleido-agent.mdx b/mintlify-docs/ai-tools/kaleido-agent.mdx index 5cb36dd..82d2c43 100644 --- a/mintlify-docs/ai-tools/kaleido-agent.mdx +++ b/mintlify-docs/ai-tools/kaleido-agent.mdx @@ -8,9 +8,9 @@ description: "Run an autonomous non-custodial agent that rebalances a Bitcoin L2 It manages a Lightning and RGB wallet, executes atomic HTLC swaps on the KaleidoSwap DEX, runs portfolio rebalancing and DCA strategies, keeps Lightning channel liquidity healthy, and serves as an interactive wallet-assistant chat, all driven by an LLM (Claude or OpenAI) reasoning over [KaleidoCLI](/cli/introduction) and MCP tool calls. - + KaleidoAgent is a separate, always-on server. It does **not** currently embed [KaleidoMind](/ai-tools/kaleido-mind)'s `Engine` and runs its own agent loop instead. See [KaleidoMind's relationship note](/ai-tools/kaleido-mind#relationship-to-kaleidoagent) for the convergence path being considered. - + ## Capabilities @@ -109,7 +109,7 @@ Same 5-step HTLC protocol as elsewhere in the KaleidoSwap stack, driven via `kal ## Run It -Prerequisites: Node.js 20 or newer, [KaleidoCLI](/cli/getting-started) in `$PATH`, the [Nanobot](https://nanobot.dev) runtime, and an Anthropic or OpenAI API key. +Prerequisites: Node.js 20 or newer, [KaleidoCLI](/cli/installation) in `$PATH`, the [Nanobot](https://nanobot.dev) runtime, and an Anthropic or OpenAI API key. @@ -158,6 +158,36 @@ docker compose --env-file .env.container -f docker-compose.container.yml up -d `agent.config.json` holds a real BIP-39 mnemonic. Start on test networks, keep `dry_run` enabled until the setup is verified, and never commit or share the file. +## First Run + +With the agent running, drive one loop by hand and read what it decided before letting it trade for real. + + + + `portfolio.dry_run` defaults to `true` in `agent.config.json`. Leave it there. The agent will reason, decide, and report a trade without submitting it. + + + + Rather than waiting on the schedule, ask the [status API](#status-api) to run one: + + ```bash + curl -X POST http://localhost:4242/run \ + -H 'Content-Type: application/json' \ + -d '{"task_id":"rebalance"}' + ``` + + Then read `GET /status` to see the decision, the balances it saw, and the token cost. The dashboard on `http://localhost:5173` shows the same run if you started it. + + + + 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. + + + + Set `portfolio.dry_run` to `false` when the dry-run decisions have looked correct across several runs. + + + ## Status API The agent exposes a localhost-only control API on port `4242`, used by the dashboard and callable directly. diff --git a/mintlify-docs/ai-tools/kaleido-mind.mdx b/mintlify-docs/ai-tools/kaleido-mind.mdx index 0102637..c237c1a 100644 --- a/mintlify-docs/ai-tools/kaleido-mind.mdx +++ b/mintlify-docs/ai-tools/kaleido-mind.mdx @@ -8,9 +8,9 @@ description: "On-device reasoning engine behind agentic KaleidoSwap wallets, wit The design starts from a hard constraint: small on-device models are slow and unreliable at multi-step planning. KaleidoMind avoids asking them to do that work. - + KaleidoMind does not run by itself, it is a library embedded by a host: the [Rate mobile wallet](https://github.com/kaleidoswap/Rate) (React Native, fully on-device QVAC), the [Desktop App](/desktop-app/getting-started/introduction)'s Tauri sidecar, or an eval and benchmark harness. **[KaleidoAgent](/ai-tools/kaleido-agent) does not currently use this library**, it has its own separate agent loop. See [Relationship to KaleidoAgent](#relationship-to-kaleidoagent) below. - + ## The Tiered Funnel diff --git a/mintlify-docs/ai-tools/mcp-servers.mdx b/mintlify-docs/ai-tools/mcp-servers.mdx index 0057362..411cf06 100644 --- a/mintlify-docs/ai-tools/mcp-servers.mdx +++ b/mintlify-docs/ai-tools/mcp-servers.mdx @@ -281,6 +281,58 @@ Add a server to an MCP host such as Claude Desktop. `npx` works for the publishe ``` +## First Run + +Go read-only first, then quoting, then execution. Every step after the first one moves real value. + + + + Drop the `kaleido-mcp` block into your MCP host's config, pointing `KALEIDOSWAP_API_URL` at a test environment and `SPARK_NETWORK` at `REGTEST`. The full JSON is in [Client Configuration](#client-configuration) above. + + + + MCP hosts read their config at startup. A running client will not pick up a new server until you restart it. + + + + Start with something that cannot move funds. Ask for market data, which needs no seed and no node: + + ``` + What is the current Bitcoin price and the Fear and Greed index? + ``` + + That exercises `l402_get_price` and `l402_get_sentiment`. If it answers, the connection works. + + + + Now confirm the wallet tools resolve: + + ``` + Show me my Spark balance and my Spark address. + ``` + + This calls `spark_get_balance` and `spark_get_address`. An error here is a seed or network problem, not a connection problem. + + + + Ask for a price without placing anything: + + ``` + Quote 100000 sats of BTC into USDT. Do not place an order. + ``` + + `kaleidoswap_get_quote` returns an `rfq_id`, raw amounts, the fee, and an expiry. Read the raw amounts carefully: they are in the asset's smallest unit, not display units. + + + + An atomic swap needs the DEX tools and the wallet tools together, and the node must hold the asset in a channel. The [cross-server sequence](#atomic-swap-across-servers) below shows each call in order. + + + + + A generic MCP host is the least protected path. `kaleido-mcp` does not encode a confirmation flag, so if your client auto-approves tool calls, an LLM can spend from the configured wallet without asking you. Use a test network seed until you know how your client handles approvals. + + ## Atomic Swap Across Servers An atomic swap needs the DEX tools and the wallet tools together. `kaleido-mcp` speaks to the maker via its `kaleidoswap_*` tools and drives the taker node via its `wdk_*` tools. Nothing is custodied at any step, and the HTLC settles on Lightning. diff --git a/mintlify-docs/ai-tools/troubleshooting.mdx b/mintlify-docs/ai-tools/troubleshooting.mdx index a519176..f2b0b82 100644 --- a/mintlify-docs/ai-tools/troubleshooting.mdx +++ b/mintlify-docs/ai-tools/troubleshooting.mdx @@ -91,7 +91,7 @@ description: "Fix common KaleidoSwap AI tool problems, covering MCP connection f **Solutions**: 1. Confirm it resolves: `kaleido --version` 2. Set `KALEIDO_BIN` to the absolute path of the binary in the server or agent config. - 3. Install it per [CLI Getting Started](/cli/getting-started) if it is missing. + 3. Install it per [CLI Installation](/cli/installation) if it is missing. @@ -196,7 +196,9 @@ description: "Fix common KaleidoSwap AI tool problems, covering MCP connection f ## Get Help -Check the [FAQ](/ai-tools/faq) for questions rather than errors. For anything else, report a problem through your preferred channel from the options below, including: +Check the [FAQ](/ai-tools/faq) for questions rather than errors, and [Additional Resources](/ai-tools/additional-resources) for upstream documentation and links. + +For anything else, report a problem through your preferred channel from the options below, including: 1. Which surface and version (MCP server name, KaleidoAgent commit, or Desktop App version) 2. The network you are on (Regtest, Signet, or mainnet) diff --git a/mintlify-docs/api-reference/additional-resources.mdx b/mintlify-docs/api-reference/additional-resources.mdx new file mode 100644 index 0000000..f8a9ee4 --- /dev/null +++ b/mintlify-docs/api-reference/additional-resources.mdx @@ -0,0 +1,111 @@ +--- +title: "Bitcoin Swap API: Additional Resources" +sidebarTitle: "Additional Resources" +description: "Links for KaleidoSwap API integrators — OpenAPI specifications, SDKs and CLI, node and protocol references, test networks, and support channels" +--- + +## Specifications & Clients + + + + Versioned specs for the KaleidoSwap APIs, updated on each release. Diff two versions instead of discovering changes at runtime. + + + + Typed clients generated from those specs, wrapping both the Maker API and your node behind `client.maker.*` and `client.rln.*`. + + + + Drive a node, quote, and swap from the terminal — useful for probing the API by hand before writing a client. + + + + Base URLs, authentication, request format, versioning, and rate limits. + + + +## Protocol References + + + + The atomic HTLC flow end to end, with the sequence diagram and the endpoints used at each step. + + + + The node that serves the RLN API and whitelists swapstrings. This is the KaleidoSwap fork; the [upstream project](https://github.com/RGB-Tools/rgb-lightning-node) is maintained by RGB Tools. + + + + The Channel Requests specification our [channel order endpoints](/api-reference/rgb-lsps1-apis) implement, extended here with RGB asset allocation. + + + + Client-side validation, asset interfaces, and the specification behind the `rgb:` contract IDs the API returns. + + + +## Environments & Testing + +Integrate against Signet before mainnet. No API key is required today, and anonymous requests are still served. + +| 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)* | + +Asset IDs are not portable between environments — read them from `GET /api/v1/market/assets` and key your configuration per environment. + + + + Get Signet Bitcoin to fund a node and open test channels. + + + + Confirm on-chain that a swap settled or a channel open actually confirmed. + + + + Deployment options for the RGB Lightning Node the swap endpoints require. + + + +## Related Documentation + + + + The three error envelopes, status-code semantics, retry strategy, and a fix per symptom. + + + + End-to-end code for the atomic swap flow, if you would rather read working code than endpoint tables. + + + + Where the maker, the LSP, and your node sit relative to each other. + + + + RFQ, swapstring, HTLC, layer, and the rest of the vocabulary these endpoints assume. + + + +## Get Help + +Check [Troubleshooting](/api-reference/troubleshooting) for errors and the [FAQ](/api-reference/faq) for questions. + +For anything else, report a problem through your preferred channel from the options below, including: + +1. Request URL and HTTP method +2. Request payload (redact any API key) +3. Full error response, including `request_id` +4. Timestamp of the request +5. Environment (Signet / Mainnet) + + + + Ask the community. + + + Direct support for urgent issues. + + diff --git a/mintlify-docs/api-reference/error-handling.mdx b/mintlify-docs/api-reference/error-handling.mdx deleted file mode 100644 index fcef3e6..0000000 --- a/mintlify-docs/api-reference/error-handling.mdx +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: "Swap API Error Handling" -sidebarTitle: "Error Handling" -description: "How the KaleidoSwap API reports errors, covering HTTP status codes, the error response format, and handling strategies for resilient integrations" ---- - -The KaleidoSwap API uses standard HTTP status codes and detailed error messages to communicate the outcome of API requests. This section provides an overview of common error types and how to handle them effectively. - ---- - -## HTTP Status Codes - -### 2xx: Success -- **200 OK**: The request was successful, and the server returned the expected response. - -### 4xx: Client Errors -These errors indicate an issue with the client’s request: -- **400 Bad Request**: The request is malformed or contains invalid parameters. -- **401 Unauthorized**: The Bearer API key is missing or invalid (returned once API-key enforcement is enabled). -- **403 Forbidden**: The client does not have permission to access the requested resource. -- **404 Not Found**: The requested resource could not be found. -- **429 Too Many Requests**: The client has exceeded the allowed rate limit. - -### 5xx: Server Errors -These errors indicate an issue on the server side: -- **500 Internal Server Error**: An unexpected error occurred on the server. -- **502 Bad Gateway**: The server received an invalid response from an upstream server. -- **503 Service Unavailable**: The service is temporarily unavailable, possibly due to maintenance or overload. - ---- - -## Error Response Format - -The API returns **three distinct error envelopes** depending on where the request failed. - -### Application errors - -Business and application errors (invalid parameters, missing resources, conflicts, rate limits, server errors) return a structured envelope: - -```json -{ - "error_code": "PAIR_NOT_FOUND", - "message": "Trading pair not found: BTC/USDT", - "details": {}, - "request_id": "req_01HV8Q9X7G0Q7Y3Z" -} -``` - -- `error_code` (`string`): Stable, machine-readable error code (e.g. `PAIR_NOT_FOUND`, `VALIDATION_ERROR`, `NOT_FOUND`, `RATE_LIMIT_EXCEEDED`, `INTERNAL_ERROR`). -- `message` (`string`): Human-readable description of the error. -- `details` (`object`): Optional structured context about the error (may be empty). -- `request_id` (`string`): Request correlation identifier — include it when contacting support. - -### Request-validation errors (HTTP 422) - -Requests that fail schema validation *before* reaching application logic return FastAPI's validation envelope with HTTP `422`: - -```json -{ - "detail": [ - { - "loc": ["body", "rfq_id"], - "msg": "Field required", - "type": "missing" - } - ] -} -``` - -- `detail` (`array`): One entry per validation failure. - - `loc` (`array<(string | integer)>`): Path to the offending field. - - `msg` (`string`): Validation error message. - - `type` (`string`): FastAPI/Pydantic validation error type. - -### Legacy errors - -A few endpoints still return some `400` responses as a bare detail object, **without** `error_code` or `request_id` — for example an unsupported route on `POST /market/quote` or a malformed `pair_ticker` filter on `GET /market/pairs`: - -```json -{ - "detail": "Route not supported for this pair. From: BTC_LN, To: RGB_LN" -} -``` - -- `detail` (`string`): Human-readable description of the error. - -Clients handling `400` responses should accept both the structured envelope and this legacy shape. - ---- - -## Common Errors -Here are some typical errors and their resolutions: - -### 400 Bad Request -- **Cause**: Missing or invalid parameters in the request. -- **Solution**: Verify the request payload and ensure all required fields are provided with valid data. - -### 404 Not Found -- **Cause**: The requested endpoint or resource does not exist. -- **Solution**: Check the endpoint URL and resource identifiers. - -### 429 Too Many Requests -- **Cause**: The client has sent too many requests in a short period. -- **Solution**: Implement rate-limiting in your client application and retry after the specified wait time (if provided). - -### 500 Internal Server Error -- **Cause**: An unexpected error occurred on the server. -- **Solution**: Retry the request later. If the issue persists, contact support with details about the request. - ---- - -## WebSocket Error Handling -For WebSocket connections, errors are communicated as JSON messages. If a critical error occurs, the server may close the connection. - -### Reconnection Strategy -If a WebSocket connection is closed unexpectedly: - -1. Wait for a few seconds (e.g., 5-10 seconds). -2. Re-establish the connection. -3. Re-issue any pending `quote_request` messages to obtain fresh quotes. - ---- - -### Debugging Tips -1. **Check Logs**: Monitor your application logs for details about failed requests. -2. **Validate Inputs**: Ensure all request parameters and payloads meet the API requirements. -3. **Contact Support**: For persistent or unclear errors, provide the following details: - - Request URL - - HTTP method - - Request payload - - Timestamp of the error - - Full error response from the API - ---- - -## Best Practices -1. **Handle Errors Gracefully**: Implement proper error-handling logic in your application to avoid crashes or user frustration. -2. **Rate-Limiting**: Respect the API rate limits to avoid `429 Too Many Requests` errors. -3. **Retry Mechanism**: For transient errors (e.g., 500 Internal Server Error), implement a retry mechanism with exponential backoff. - ---- - -For additional details on error codes and troubleshooting, refer to the API documentation. diff --git a/mintlify-docs/api-reference/faq.mdx b/mintlify-docs/api-reference/faq.mdx new file mode 100644 index 0000000..66b86e8 --- /dev/null +++ b/mintlify-docs/api-reference/faq.mdx @@ -0,0 +1,124 @@ +--- +title: "Bitcoin Swap API FAQ" +sidebarTitle: "FAQ" +description: "Common questions about the KaleidoSwap swap API, covering authentication, the maker and node APIs, amount units, quote lifetime, WebSocket quoting, and browser use" +--- + +## Frequently Asked Questions + + + + **Not today.** Anonymous requests are still served on every Maker API endpoint, so you can integrate immediately. Bearer keys (`Authorization: Bearer `) are already **accepted and attributed** — they carry scopes such as `quote:read` for market data and quotes and `swap:execute` for swap init and execute. + + Enforcement is rolling out gradually. Once it is on, a missing or invalid key returns `401`, so send a key now rather than retrofitting it later. Details in the [Overview](/api-reference/introduction#authentication). + + + + They are two different servers, and only one of them is ours. + + | API | Where it lives | Covers | + |-----|----------------|--------| + | **Maker API** | `https://api.signet.kaleidoswap.com/api/v1` | Market data, quotes, swap init/execute/status, LSPS1 channel orders | + | **RLN API** | the root of **your own** node, e.g. `http://:3001/` | Wallet and RGB assets, channels, invoices, swap whitelisting | + + Everything documented under Endpoints in this tab is the Maker API. The RLN API is served by the [RGB Lightning Node](https://github.com/kaleidoswap/rgb-lightning-node) you run yourself — there is no KaleidoSwap-hosted RLN endpoint to call. The table in the [Overview](/api-reference/introduction) maps each goal to the right API. + + + + **For market data, no.** Assets, pairs, routes, and quotes are plain HTTP calls against the maker. + + **For atomic swaps, yes.** Your node is what whitelists the `swapstring` and routes the HTLC. That is exactly why the maker never takes custody — there is no step in the protocol where it holds your funds. See [Node Hosting](/desktop-app/getting-started/node-hosting) for deployment options. + + + + Signet (MutinyNet) is live today; mainnet is coming soon. + + | 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)* | + + The interactive playground on the endpoint pages runs against Signet. + + + + **BTC legs are millisatoshis.** `POST /api/v1/swaps/init` states this explicitly, and the quote examples follow the same convention: `1000000` on a BTC leg is 1,000 sats. + + **RGB asset legs are raw smallest units**, decided by the asset's own `precision` from `GET /api/v1/market/assets`. Precision differs per asset — USDT at precision `6` means `1000000` is 1.00 USDT. + + Never hardcode a divisor. Read `precision` per asset, and treat the `precision` field as display metadata rather than as the unit of the amount you send. + + + + `price` is the price of **one whole unit** of `from_asset`, expressed in the **smallest unit** of `to_asset`. It is not a display price, and it is not the amount you will receive. + + The amount you will actually get is already on the response leg — `to_asset.amount` — with the fee folded in. Use that for anything user-facing, and use `price` only if you need the rate itself. + + + + Until its `expires_at` (unix time) — a short window, measured in tens of seconds. One quote backs one `POST /api/v1/swaps/init`. + + Do not hold an `rfq_id` across user think-time. Fetch the quote, then init, whitelist, and execute promptly; if a user pauses on a confirmation screen, request a fresh quote when they resume. + + + + Either — they return the same quote shape. + + The WebSocket is **request/response, not publish/subscribe**: you send a `quote_request` and the server answers that one message. There is no subscription, so a price only stays fresh if you keep asking. Send periodic `ping` messages to keep the connection healthy. + + Use the WebSocket when you are showing a moving price and want to avoid the per-request HTTP overhead; use `POST /api/v1/market/quote` for a one-off swap. See [Swap Protocol](/api-reference/swap-protocol). + + + + The `swapstring` returned by `/swaps/init` encodes the exact terms of the swap — both amounts, both assets, and the payment hash. Whitelisting it on your own node is how *you* authorise those precise terms. + + This is the non-custodial hinge of the protocol: the maker cannot move your assets, it can only offer an HTLC your node has already agreed to honour. Whitelisting happens through the `/taker` API of your RGB Lightning Node, not through the Maker API. + + + + The `access_token` is a per-swap credential and is returned **only once**, at init. You need it alongside the `payment_hash` to poll `POST /api/v1/swaps/atomic/status`. + + Without it, the status endpoint returns a uniform `404 Swap not found` — by design, so the endpoint cannot be used to probe for other people's payment hashes. Persist the token with the payment hash the moment init returns. LSPS1 channel orders work the same way: `create_order` returns a per-order `access_token` required by `get_order` and `rate_decision`. + + + + Not reliably. CORS is disabled on most Maker API endpoints, so a browser-only app needs its own backend to proxy the calls. Keep API keys server-side regardless — once enforcement is on, a key shipped to the browser is a key you have published. + + + + The defaults are 600 requests per minute per IP, 300 per minute per endpoint, and 1,000 per minute globally. They are configurable per deployment, so treat them as a starting point rather than a contract. + + Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` — read them instead of guessing. Cache `assets` and `pairs` locally; they change rarely. + + + + The version lives in the path: `v1`, as in `https://api.signet.kaleidoswap.com/api/v1`. The versioned OpenAPI specifications are published in the [specs repository](https://github.com/kaleidoswap/specs) and updated on each release, so you can diff two versions rather than discover changes at runtime. + + + + For most integrations, yes. The [TypeScript and Python SDKs](/sdk/introduction) generate their types from the same OpenAPI specifications, wrap both the Maker API and your node behind `client.maker.*` and `client.rln.*`, and give you a typed error hierarchy with retry hints. + + Call REST directly when you are in a language the SDKs do not cover, or when you need control the client abstracts away. There is also a [CLI](/cli/introduction) for driving a node from the terminal. + + + +## Get Help + +Check [Troubleshooting](/api-reference/troubleshooting) for errors rather than questions, and [Additional Resources](/api-reference/additional-resources) for specifications and upstream links. + +For anything else, report a problem through your preferred channel from the options below, including: + +1. Request URL and HTTP method +2. Request payload (redact any API key) +3. Full error response, including `request_id` +4. Timestamp of the request +5. Environment (Signet / Mainnet) + + + + Ask the community. + + + Direct support for urgent issues. + + diff --git a/mintlify-docs/api-reference/getting-started.mdx b/mintlify-docs/api-reference/getting-started.mdx index c861ad4..7dc35d8 100644 --- a/mintlify-docs/api-reference/getting-started.mdx +++ b/mintlify-docs/api-reference/getting-started.mdx @@ -138,23 +138,4 @@ The API returns standard HTTP status codes to indicate the outcome of a request: - **400**: Bad Request (e.g., invalid parameters) - **404**: Resource Not Found - **500**: Internal Server Error -For more information on error handling, see [Error Handling](/api-reference/error-handling). - ---- - -## Next Steps - - - - Understand the full taker-maker swap lifecycle before calling swap endpoints - - - Fetch assets, pairs, and quotes - - - Create and track swap orders - - - Order channels and manage liquidity - - +For the full status-code list, the error response format, and per-symptom fixes, see [Troubleshooting](/api-reference/troubleshooting). diff --git a/mintlify-docs/api-reference/introduction.mdx b/mintlify-docs/api-reference/introduction.mdx index a16fe2c..9ffcd5d 100644 --- a/mintlify-docs/api-reference/introduction.mdx +++ b/mintlify-docs/api-reference/introduction.mdx @@ -105,7 +105,7 @@ HTTP status codes follow standard conventions: | `500` | Internal server error | | `503` | Service unavailable — maker or LSP node temporarily unreachable | -See [Error Handling](/api-reference/error-handling) for a complete list of error codes. +See [Troubleshooting](/api-reference/troubleshooting) for the complete list of error codes and the fix for each failure. --- @@ -117,14 +117,8 @@ Rate limits apply to all API endpoints. Requests that exceed the limit receive a ## Using the SDK -Instead of calling the REST API directly, you can use the official KaleidoSDK libraries that wrap these endpoints with type safety and convenience methods: +Instead of calling the REST API directly, you can use the official KaleidoSDK libraries, which wrap these endpoints with type safety and convenience methods in both TypeScript and Python. - - - Auto-generated typed client from the OpenAPI spec with `client.maker.*` and `client.rln.*` sub-clients - - - - Synchronous Python client with Pydantic models, using the same sub-client architecture - - + + Typed clients generated from the same OpenAPI specs, with `client.maker.*` and `client.rln.*` sub-clients. + diff --git a/mintlify-docs/api-reference/market-apis.mdx b/mintlify-docs/api-reference/market-apis.mdx index 5bb3b3c..1ab7621 100644 --- a/mintlify-docs/api-reference/market-apis.mdx +++ b/mintlify-docs/api-reference/market-apis.mdx @@ -385,8 +385,4 @@ Exactly one of `from_asset.amount` or `to_asset.amount` must be provided: set `f - Amounts should stay within the per-layer `min_amount`/`max_amount` limits found in each asset's `endpoints` array. - The `expires_at` field indicates when this quote will no longer be valid for initiating a swap. - The fee is already reflected in the calculated leg amount. -- The `rfq_id` can be used in subsequent swap initiation or LSPS1 order requests until it expires. - ---- - -For details about swap operations, proceed to [Swap APIs](/api-reference/swap-apis). \ No newline at end of file +- The `rfq_id` can be used in subsequent swap initiation or LSPS1 order requests until it expires. \ No newline at end of file diff --git a/mintlify-docs/api-reference/rgb-lsps1-apis.mdx b/mintlify-docs/api-reference/rgb-lsps1-apis.mdx index 73af53f..b32a9bb 100644 --- a/mintlify-docs/api-reference/rgb-lsps1-apis.mdx +++ b/mintlify-docs/api-reference/rgb-lsps1-apis.mdx @@ -311,7 +311,3 @@ Resolve a repricing event on an asset-backed order. If the market rate moves sig ``` Calling this endpoint on an order that is not in the `PENDING_RATE_DECISION` state returns a `400` error. When a refund is requested and processed, `refund_txid` carries the on-chain transaction ID. - ---- - -For more details about trading and market operations, proceed to [Market APIs](/api-reference/market-apis). diff --git a/mintlify-docs/api-reference/swap-apis.mdx b/mintlify-docs/api-reference/swap-apis.mdx index 41654b0..28ca11e 100644 --- a/mintlify-docs/api-reference/swap-apis.mdx +++ b/mintlify-docs/api-reference/swap-apis.mdx @@ -293,7 +293,3 @@ Retrieve the current status of an atomic swap using the associated `payment_hash - **`Succeeded`**: The swap has been successfully completed. - **`Expired`**: The swap was not completed within the required timeframe. - **`Failed`**: The swap encountered an error and did not complete successfully. - ---- - -For error details, refer to [Error Handling](/api-reference/error-handling). diff --git a/mintlify-docs/api-reference/swap-protocol.mdx b/mintlify-docs/api-reference/swap-protocol.mdx index b17bcb0..6d6339c 100644 --- a/mintlify-docs/api-reference/swap-protocol.mdx +++ b/mintlify-docs/api-reference/swap-protocol.mdx @@ -117,20 +117,3 @@ client.maker.enable_websocket("wss://api.signet.kaleidoswap.com/api/v1/market/ws # See sdk/examples for full atomic swap flow ``` - ---- - - - - Endpoints for atomic swap init and execute - - - Endpoints for quotes and market data - - - End-to-end code examples for the atomic swap flow - - - Handle swap failures and edge cases - - diff --git a/mintlify-docs/api-reference/troubleshooting.mdx b/mintlify-docs/api-reference/troubleshooting.mdx new file mode 100644 index 0000000..8f20ce7 --- /dev/null +++ b/mintlify-docs/api-reference/troubleshooting.mdx @@ -0,0 +1,424 @@ +--- +title: "Swap API Errors & Troubleshooting" +sidebarTitle: "Troubleshooting" +description: "How the KaleidoSwap API reports errors and how to fix them, covering the three error envelopes, HTTP status codes, symptom-by-symptom solutions, and retry strategy" +--- + +The KaleidoSwap API uses standard HTTP status codes and structured error bodies to report the outcome of a request. This page covers how to read an error, what each status code means, and the fix for the failures integrations actually hit. For questions rather than failures, see the [FAQ](/api-reference/faq). + +--- + +## Error Response Format + +The API returns **three distinct error envelopes** depending on where the request failed. A client that handles all three is a client that never has to guess. + +### Application errors + +Business and application errors (invalid parameters, missing resources, conflicts, rate limits, server errors) return a structured envelope: + +```json +{ + "error_code": "PAIR_NOT_FOUND", + "message": "Trading pair not found: BTC/USDT", + "details": {}, + "request_id": "req_01HV8Q9X7G0Q7Y3Z" +} +``` + +- `error_code` (`string`): Stable, machine-readable error code (e.g. `PAIR_NOT_FOUND`, `VALIDATION_ERROR`, `NOT_FOUND`, `RATE_LIMIT_EXCEEDED`, `INTERNAL_ERROR`). +- `message` (`string`): Human-readable description of the error. +- `details` (`object`): Optional structured context about the error (may be empty). +- `request_id` (`string`): Request correlation identifier — include it when contacting support. + +Branch on `error_code`, never on `message`. The codes are stable; the wording is not. + +### Request-validation errors (HTTP 422) + +Requests that fail schema validation *before* reaching application logic return FastAPI's validation envelope with HTTP `422`: + +```json +{ + "detail": [ + { + "loc": ["body", "rfq_id"], + "msg": "Field required", + "type": "missing" + } + ] +} +``` + +- `detail` (`array`): One entry per validation failure. + - `loc` (`array<(string | integer)>`): Path to the offending field. + - `msg` (`string`): Validation error message. + - `type` (`string`): FastAPI/Pydantic validation error type. + +### Legacy errors + +A few endpoints still return some `400` responses as a bare detail object, **without** `error_code` or `request_id` — for example an unsupported route on `POST /market/quote` or a malformed `pair_ticker` filter on `GET /market/pairs`: + +```json +{ + "detail": "Route not supported for this pair. From: BTC_LN, To: RGB_LN" +} +``` + +- `detail` (`string`): Human-readable description of the error. + +Clients handling `400` responses should accept both the structured envelope and this legacy shape. + +--- + +## HTTP Status Codes + +| Status | Meaning | Retry? | +|--------|---------|--------| +| `200` | Success — the request completed and returned the expected response | — | +| `400` | Bad request — the request is malformed or contains invalid parameters | No, fix the request | +| `401` | Unauthorized — the Bearer API key is missing or invalid (returned once API-key enforcement is enabled) | No, attach a valid key | +| `403` | Forbidden — the key is not allowed from this origin | No | +| `404` | Not found — the endpoint or resource does not exist | No | +| `422` | Unprocessable entity — schema validation failed | No, the same payload always fails | +| `429` | Too many requests — the rate limit was exceeded | Yes, after backing off | +| `500` | Internal server error — an unexpected error occurred on the server | Yes, with backoff | +| `502` | Bad gateway — the server received an invalid response from an upstream server | Yes, with backoff | +| `503` | Service unavailable — the maker or LSP node is temporarily unreachable, or under maintenance or overload | Yes, with backoff | + +The `4xx` class means the request needs changing; the `5xx` class means the request was fine and something upstream was not. Only the `5xx` class plus `429` are worth retrying — see [Retry and Resilience](#retry-and-resilience). + +--- + +## Requests and Authentication + + + + **Symptoms:** `400`, with either an `error_code` envelope or a bare `detail` string + + **Cause:** missing or invalid parameters in the request. + + **Solutions:** + 1. Verify the payload and confirm every required field is present with valid data + 2. Make your handler accept **both** `400` shapes — read `error_code` if present, fall back to `detail` + 3. For `{"detail": "Route not supported for this pair..."}`, check the pair's actual `routes` with `POST /api/v1/market/pairs/routes` and send a `from_asset.layer` → `to_asset.layer` combination that appears there + 4. For pair filters, `pair_ticker` must be `BASE/QUOTE` (e.g. `BTC/USDT`), and single-pair identifiers are mutually exclusive + + + + **Symptoms:** requests that used to work start returning `401`, or `401` on first call with a key attached + + **Causes:** + - API-key enforcement has been enabled for your environment and no valid key is being sent + - The header is malformed — it must be `Authorization: Bearer `, not the bare token + - The key lacks the scope for that endpoint (`quote:read` for market data, `swap:execute` for swap init/execute) + + **Solutions:** + 1. Log the exact `Authorization` header your client sends and check for a missing `Bearer ` prefix or a trailing newline + 2. If the call is a swap init or execute, confirm the key carries `swap:execute` and not only `quote:read` + 3. Verify the key is valid and has not been revoked + 4. If you have no key yet, note that anonymous access still works on Signet — a `401` means enforcement is live for you + + + + **Symptoms:** `403` on an endpoint that accepts your key elsewhere + + **Cause:** the key is valid but not allowed from this origin. + + **Solution:** call from an allowed origin, or request that the origin be added. This is the failure mode you hit when a key intended for a backend is used from a browser or a new deployment host — see also the CORS note in the [FAQ](/api-reference/faq). + + + + **Symptoms:** `422` with a `detail` **array** rather than an `error_code` + + **Cause:** the request failed schema validation before reaching application logic, so no business error was produced. + + **Solution:** read `detail[].loc` — it is the exact path to the offending field. `["body", "rfq_id"]` with `"type": "missing"` means you omitted `rfq_id` entirely; a `"type"` of `int_parsing` usually means an amount was sent as a string. Do not treat `422` as retryable: the same payload will always fail. + + + + **Symptoms:** `PAIR_NOT_FOUND`, `NOT_FOUND`, or an empty `assets` array for a ticker you know is supported + + **Causes:** + - The endpoint URL or a resource identifier is wrong + - The asset or pair is inactive, and `GET /market/pairs` filters to active pairs by default (`active_only=true`) + - You filtered by `asset_id` where the maker expects the RGB contract ID exactly, including the `rgb:` prefix + - You are on the wrong environment — asset IDs are **not** portable between Signet and mainnet + + **Solutions:** + 1. Check the endpoint path and resource identifiers, including the `/api/v1` prefix + 2. Re-query with `active_only=false` to see whether the pair exists but is disabled + 3. Discover IDs from `GET /api/v1/market/assets` rather than hardcoding them, and key your config by environment + 4. Check `total` in the response — it is the count of all matches, so a `total` above your page size means you are looking at pagination, not absence + + + + **Symptoms:** `RATE_LIMIT_EXCEEDED`, typically while polling for prices + + **Cause:** too many requests in a short period. + + **Solutions:** + 1. Read `X-RateLimit-Remaining` and `X-RateLimit-Reset` and back off before you are cut off, rather than reacting to the `429` + 2. Retry after the indicated wait time, if one is provided + 3. Stop polling `POST /market/quote` in a loop — open the WebSocket and send a `quote_request` when you actually need a new price + 4. Cache `market/assets` and `market/pairs`; both are safe to cache and change rarely + 5. Remember the limits are per IP *and* per endpoint *and* global, so a noisy neighbour behind the same NAT can consume your budget + + + + **Symptoms:** `INTERNAL_ERROR`, or `503` on endpoints that were working a minute ago + + **Causes:** + - `500` — an unexpected error on the server + - `502` — an invalid response from an upstream server + - `503` — the maker or the LSP node is temporarily unreachable, under maintenance, or overloaded + + None of these mean your request was malformed. + + **Solutions:** + 1. Retry with exponential backoff and jitter; these are the transient class of failures + 2. Do **not** blind-retry a `/swaps/execute` call on a timeout — poll `POST /api/v1/swaps/atomic/status` first to see whether it actually landed + 3. If it persists, report it with the `request_id` from the error body + + + +--- + +## Quotes and Amounts + + + + **Symptoms:** `/swaps/init` rejects an `rfq_id` that was valid moments ago + + **Cause:** the quote's `expires_at` has passed. The window is tens of seconds, not minutes. + + **Solutions:** + 1. Quote as late as possible — immediately before init, never before a confirmation screen the user might sit on + 2. Keep the whole init → whitelist → execute sequence tight; it all runs against one quote + 3. If a user hesitates, discard the `rfq_id` and request a fresh quote when they resume + + + + **Symptoms:** `VALIDATION_ERROR` or a `400` mentioning the amount + + **Causes:** + - Below `min_amount` or above `max_amount` for that **layer** — the limits live per-layer in each asset's `endpoints` array, not on the asset itself + - Display units sent instead of raw units + - An amount on both legs, or on neither + + **Solutions:** + 1. Read the limits from the matching `endpoints` entry for the layer you are routing over + 2. Send BTC legs in millisatoshis and RGB legs in raw units per the asset's `precision` — see the [FAQ](/api-reference/faq) + 3. Set exactly one of `from_asset.amount` (forward quote) or `to_asset.amount` (reverse quote) + + + + **Symptoms:** the quote is arithmetically "wrong" by a factor of 1,000 or 100,000,000 + + **Causes:** + - A BTC leg treated as satoshis when the API means millisatoshis + - One asset's precision applied to another — precision is per asset, and BTC and USDT do not share one + - `price` read as a display rate; it is one whole `from_asset` unit expressed in the smallest unit of `to_asset` + + **Solutions:** + 1. Display `to_asset.amount` from the response — the fee is already folded into it — instead of recomputing from `price` + 2. Pull `precision` per asset from `GET /api/v1/market/assets` and never hardcode a divisor + 3. Sanity-check a small quote round-trip on Signet before wiring the conversion into a UI + + + +--- + +## Swaps + + + + **Symptoms:** `init` returned a `swapstring`, but `execute` fails + + **Cause:** the `swapstring` was never whitelisted on your own node, so the taker side cannot honour the HTLC. This is the single most common integration failure, because the middle step is not a Maker API call. + + **Solution:** the three steps must run in order, against two different servers: + + 1. `POST /api/v1/swaps/init` on the **Maker API** → returns `swapstring`, `payment_hash`, `access_token` + 2. Whitelist the `swapstring` via the `/taker` API of **your own RGB Lightning Node** + 3. `POST /api/v1/swaps/execute` on the **Maker API** with `swapstring`, `taker_pubkey`, and `payment_hash` + + Also confirm `taker_pubkey` is your node's pubkey and that the `payment_hash` matches the one from init. See [Swap Protocol](/api-reference/swap-protocol). + + + + **Symptoms:** `POST /api/v1/swaps/atomic/status` returns `404` for a swap you know exists + + **Cause:** a missing or invalid `access_token`. The `404` is deliberately uniform — it does not distinguish "wrong token" from "no such swap", so the endpoint cannot be used to probe payment hashes. + + **Solutions:** + 1. Send both `payment_hash` **and** the `access_token` returned by `/swaps/init` + 2. If the token was never persisted, it cannot be recovered — it is returned only once. Store it with the payment hash at init time + 3. Check you are polling the environment the swap was created on + + + + **Symptoms:** `execute` returned `200`, but the status stays `Pending` and the assets have not arrived + + **Causes:** + - The HTLC is still in flight — `execute` returning is not settlement + - No route with enough capacity on the asset leg + - Pending RGB transfers on your node have not been advanced + + **Solutions:** + 1. Keep polling `/swaps/atomic/status`; the terminal states are `Succeeded`, `Expired`, and `Failed` + 2. On your node, refresh transfers and check outbound capacity on the specific asset — not just the total balance + 3. Compare `expires_at` on the swap object against the current time to know how long the HTLC still has + + + + **Symptoms:** status moves to `Expired` or `Failed` + + **Causes:** + - `Expired` — the HTLC timeout elapsed before both sides completed, usually because whitelisting or execute came too late + - `Failed` — the HTLC could not be routed or settled, typically a capacity or liquidity problem + + **Solutions:** + 1. Your funds are not at risk: an incomplete atomic swap returns both sides' funds automatically. Do not re-send funds manually + 2. Retry from a **fresh quote** — the old `rfq_id` and `swapstring` are spent + 3. If it fails repeatedly on the same pair, check capacity on that asset's channel and order more liquidity via [LSPS1](/api-reference/rgb-lsps1-apis) + + + +--- + +## WebSocket + +WebSocket errors are not HTTP responses — they arrive as JSON messages on the open socket, and on a critical error the server may close the connection outright. + + + + **Symptoms:** the socket is open and the `quote_request` was sent, but no `quote_response` comes back + + **Cause:** the request failed. Failures come back as a message with an `error` field instead of a `quote_response`, so a client that only listens for `quote_response` sees silence. + + **Solutions:** + 1. Log every inbound frame, not just the ones you expect, and handle the `error` shape + 2. Check the usual culprits: unknown asset, a route the pair does not support, an amount outside the per-layer limits + 3. Confirm you set exactly one of `from_amount` / `to_amount` + + + + **Symptoms:** the first quote arrives, then nothing changes + + **Cause:** the protocol is request/response — there is no subscription. The server answers the message you sent, and does not push updates. + + **Solution:** send a new `quote_request` whenever you need a current price, and drive it from your own interval or from user action. + + + + **Symptoms:** the socket closes unexpectedly, sometimes mid-flow + + **Reconnection strategy** — when a connection closes unexpectedly: + + 1. Wait a few seconds (5–10 s) + 2. Re-establish the connection + 3. Re-issue any pending `quote_request` messages to obtain fresh quotes — quotes do not survive the reconnect + + **Also check:** + - Send periodic `ping` messages and expect a `pong`; an idle connection through a proxy is a connection about to be closed + - Use a fresh unique `{client_id}` per session, and verify the URL is `wss://`, not `ws://` + - If you are behind a corporate proxy that strips WebSocket upgrades, fall back to `POST /market/quote` + + + +--- + +## Channel Orders (LSPS1) + + + + **Symptoms:** the call fails when you include `client_asset_amount` + + **Cause:** when `client_asset_amount > 0` the client is *purchasing* assets, so a fresh `rfq_id` from `POST /api/v1/market/quote` is required to price them. + + **Solutions:** + 1. Quote first, then pass that `rfq_id` into `estimate_fees` / `create_order` + 2. Requote if the quote expired between the two calls + 3. Omit `client_asset_amount` entirely if you only want LSP-side liquidity — no quote is needed then + + + + **Symptoms:** `create_order` fails validation on balances or asset amounts + + **Cause:** the request falls outside the LSP's advertised limits. + + **Solutions:** + 1. Read `options` from `GET /api/v1/lsps1/get_info` and stay inside `min_channel_balance_sat` / `max_channel_balance_sat`, the initial-balance bounds, and `max_channel_expiry_blocks` + 2. Check the per-asset caps in the same response — `min_initial_lsp_amount` / `max_initial_lsp_amount` are per asset and can be `0`, which means that side is not available for it + 3. Connect to the peer at `lsp_connection_url` before ordering, so the channel has somewhere to open + + + + **Symptoms:** the channel never opens and `order_state` is `PENDING_RATE_DECISION` + + **Cause:** the market rate moved significantly before the payment settled, so the LSP paused the order instead of opening a channel at a stale price. It is waiting on you. + + **Solution:** call `POST /api/v1/lsps1/rate_decision` with the `order_id`, the order's `access_token`, and `accept_new_rate` — `true` to proceed at the current rate, `false` to trigger a refund to `refund_onchain_address`. Refunds return a `refund_txid`. Calling this endpoint on an order in any other state returns `400`. + + + + **Symptoms:** you cannot read back an order you created + + **Cause:** unlike swaps, these two are distinguishable — an invalid `access_token` returns `400`, an unknown `order_id` returns `404`. + + **Solution:** store the `access_token` from `create_order` alongside the `order_id`; it is returned only at creation and is required by both `get_order` and `rate_decision`. Set `email` on the order if you want notifications as a backstop. + + + + **Symptoms:** payment settled, `order_state` is `CHANNEL_OPENING` + + **Solutions:** + 1. Keep polling `get_order` — it is safe to poll, and `channel` stays `null` until the channel exists + 2. Compare `required_channel_confirmations` against the current height from `GET /api/v1/lsps1/network_info` + 3. Note that payment expiries live under `payment.bolt11.expires_at` and `payment.onchain.expires_at`, and the channel's own expiry under `channel.expires_at` — there is no top-level `expires_at` to read + + + +--- + +## Retry and Resilience {#retry-and-resilience} + +Design the client so a bad response is a handled case rather than a crash. + +1. **Handle errors gracefully.** Parse all three envelopes, branch on `error_code`, and surface something actionable instead of propagating a raw failure to the user. +2. **Retry only what is retryable.** Transient failures — `500`, `502`, `503`, and `429` — are worth another attempt with **exponential backoff and jitter**. Client errors (`400`, `401`, `403`, `404`, `422`) will fail identically no matter how many times you send them. +3. **Respect the rate limits.** Read the `X-RateLimit-*` headers and stay under the ceiling rather than discovering it. Cache static data such as assets and pairs. +4. **Treat swap execution as non-idempotent.** A timeout on `/swaps/execute` is not proof of failure — poll `/swaps/atomic/status` before re-sending anything. +5. **Cap total attempts.** An unbounded retry loop against a `503` becomes your own denial of service. + +--- + +## Before You Report + +A reproducible report is usually diagnosed in one round trip. + +1. **Check your logs** for the full error response, not just the status code — application errors carry a `request_id` that correlates your request with our logs. +2. **Validate the inputs**: confirm every parameter and payload field meets the endpoint's requirements, and that amounts are in raw units. +3. **Reproduce with `curl`**, with any API key redacted. +4. **Confirm the base URL** includes `/api/v1` and points at the environment you think it does. +5. **Try the interactive playground** on the endpoint pages, which runs against Signet — if the same call succeeds there, the difference is in your client. + +## Get Help + +Check the [FAQ](/api-reference/faq) for questions rather than errors, and [Additional Resources](/api-reference/additional-resources) for specifications and upstream links. + +For anything else, report a problem through your preferred channel from the options below, including: + +1. Request URL and HTTP method +2. Request payload (redact any API key) +3. Full error response, including `request_id` +4. Timestamp of the request +5. Environment (Signet / Mainnet) + + + + Ask the community. + + + Direct support for urgent issues. + + diff --git a/mintlify-docs/cli/additional-resources.mdx b/mintlify-docs/cli/additional-resources.mdx new file mode 100644 index 0000000..85dcfbf --- /dev/null +++ b/mintlify-docs/cli/additional-resources.mdx @@ -0,0 +1,73 @@ +--- +title: "KaleidoCLI: Additional Resources" +sidebarTitle: "Additional Resources" +description: "Links for KaleidoCLI users — the tooling behind a local node, protocol references, test networks, and support channels" +--- + +## Tooling + + + + The Python tool manager behind `uv tool install`, and the simplest way to keep the `kaleido` binary isolated and current. + + + + What `kaleido node` drives underneath. Useful when you need to inspect a generated environment by hand. + + + +## Protocol References + + + + `kaleido-mcp` shells out to this same `kaleido` binary, exposing node lifecycle and trading as tools an LLM can call. + + + + The channel-ordering interface behind `channel order` and `channel lsp`. + + + + The node every `node`, `wallet`, `asset`, `channel`, and `payment` command drives. This is the KaleidoSwap fork; the [upstream project](https://github.com/RGB-Tools/rgb-lightning-node) is maintained by RGB Tools. + + + + Client-side validation, asset interfaces, and the `nia` / `cfa` / `uda` schemas `asset issue` writes to. + + + +## Development & Testing + + + + Get signet Bitcoin to fund a node and open test channels. Pair it with `kaleido wallet address`. + + + + Look up the transactions behind `wallet transactions` and `asset transfers`. + + + +## Get Help + +Check [Troubleshooting](/cli/troubleshooting) for errors and the [FAQ](/cli/faq) for questions. + +For anything else, report a problem through your preferred channel from the options below, including: + +1. How you installed the CLI, and the output of `uv tool list` (there is no `--version` flag) +2. Python version (`python --version`) and your operating system +3. The exact command you ran, plus its output with `--json` added +4. Whether the node is a local Docker environment or a remote one, and the network +5. `kaleido config show` and `kaleido node ps` output, with passwords removed + + + + Ask the community. + + + Report a bug on the relevant repository. + + + Direct support for urgent issues. + + diff --git a/mintlify-docs/cli/channels-lsp.mdx b/mintlify-docs/cli/channels-lsp.mdx index bb74346..a707441 100644 --- a/mintlify-docs/cli/channels-lsp.mdx +++ b/mintlify-docs/cli/channels-lsp.mdx @@ -1,5 +1,6 @@ --- title: 'Channels And LSP Flows' +sidebarTitle: 'Channels & LSP' description: 'Open Lightning channels directly or use KaleidoSwap LSP channel-order workflows from the KaleidoCLI' --- @@ -11,9 +12,9 @@ The `channel` group covers direct Lightning channel management against your loca |--------|---------| | `kaleido channel list` | List current channels | | `kaleido channel open ` | Open a channel to a peer | -| `kaleido channel close ` | Close a channel | +| `kaleido channel close --peer ` | Close a channel | -Peer arguments use `pubkey@host:port` format. +Peer arguments use `pubkey@host:port` format. Closing needs both the channel ID and `--peer`; add `--force` for a unilateral close, and only when the peer is unresponsive, since it locks funds until the timelock expires. ## Open A Channel @@ -50,9 +51,9 @@ Use `channel order` when you want KaleidoSwap's LSP flow instead of manually ope | Command | Purpose | |--------|---------| -| `kaleido channel order create ` | Create a channel order | +| `kaleido channel order create [client-pubkey]` | Create a channel order, defaulting to the local node pubkey | | `kaleido channel order get ` | Fetch status and details | -| `kaleido channel order pay ` | Pay an order with local wallet funds | +| `kaleido channel order pay ` | Pay an order with local wallet funds (`--onchain` or `--offchain`) | | `kaleido channel order decide ` | Submit a rate decision | | `kaleido channel order estimate-fees` | Estimate opening fees | @@ -64,17 +65,28 @@ kaleido channel order create 03abc... \ --client-balance 500000 ``` +The pubkey is optional and defaults to your local node, so `kaleido channel order create --lsp-balance 1000000 --client-balance 500000` is equivalent when you are ordering for yourself. + Useful options: -- `--confirmations` -- `--funding-within` -- `--expiry-blocks` -- `--refund-address` +- `--confirmations`, default 6 +- `--funding-within`, default 144 blocks +- `--expiry-blocks`, at least 1 +- `--refund-address`, defaulting to a local node address - `--announce` or `--private` - `--asset-id` -- `--lsp-asset-amount` -- `--client-asset-amount` +- `--lsp-asset-amount`, required with `--asset-id` +- `--client-asset-amount`, which must not exceed `--lsp-asset-amount` - `--email` +- `--yes`, `-y` to accept the fetched RFQ price, required non-interactively + +### Pay an order + +```bash +kaleido channel order pay --access-token --offchain +``` + +Choose the funding source with `--onchain` or `--offchain`; interactively the CLI asks, but in `--agent` or `--json` mode exactly one is required, along with `--yes`. On-chain payments accept `--fee-rate` in sat/vbyte. Example colored channel order: @@ -107,4 +119,4 @@ kaleido channel order estimate-fees --lsp-balance 1000000 --client-balance 50000 kaleido channel order create 03abc... --lsp-balance 1000000 --client-balance 500000 ``` -See [Market And Swaps](/cli/market-and-swaps) for server-side trading flows that often run alongside channels and liquidity management. +See [Market And Swaps](/cli/market-and-swaps) for server-side trading flows that often run alongside channels and liquidity management, or [Troubleshooting](/cli/troubleshooting#channels-and-lsp-orders) when a channel or an order will not go through. diff --git a/mintlify-docs/cli/command-reference.mdx b/mintlify-docs/cli/command-reference.mdx index 6128ff1..aff3d60 100644 --- a/mintlify-docs/cli/command-reference.mdx +++ b/mintlify-docs/cli/command-reference.mdx @@ -1,5 +1,6 @@ --- title: 'Command Reference' +sidebarTitle: 'Commands' description: 'Full command map for the KaleidoCLI, including nested command groups and the most important flags' --- @@ -20,6 +21,8 @@ kaleido [global options] [subcommand] [args] | `--install-completion` | Install shell completion | | `--show-completion` | Print shell completion | +There is no `--version` flag. Global flags go before the sub-command: `kaleido --json market pairs`, not `kaleido market pairs --json`. + ## Top-Level Commands | Command | Summary | @@ -63,7 +66,7 @@ Key flags: `--mode`, `--defaults`, `--api-url`, `--node-url`, `--create-node`, ` | `kaleido node info` | Show node details | | `kaleido node network` | Show network information | | `kaleido node init` | Initialize the wallet | -| `kaleido node unlock` | Unlock the wallet | +| `kaleido node unlock` | Unlock the wallet (`--chain-sync block\|transaction`, `--bitcoind-*`, `--indexer-url`, `--proxy-endpoint`, `--announce-alias`, `--announce-address`) | | `kaleido node lock` | Lock the wallet | | `kaleido node shutdown` | Gracefully shut down the node | @@ -74,7 +77,7 @@ Key flags: `--mode`, `--defaults`, `--api-url`, `--node-url`, `--create-node`, ` | `kaleido node swap pubkey` | Print the taker public key | | `kaleido node swap init` | Start a local maker-init swap flow (`--from-asset`, `--qty-from`, `--to-asset`, `--qty-to`, `--timeout`) | | `kaleido node swap whitelist --swapstring ''` | Whitelist a swap on the taker side | -| `kaleido node swap execute` | Execute a local node swap | +| `kaleido node swap execute` | Execute a local node swap (`--swapstring`, `--payment-secret`, `--taker-pubkey`) | | `kaleido node swap status ` | Check local node swap status (`--taker` or `--maker`) | | `kaleido node swap list` | List swaps known to the node | @@ -83,14 +86,14 @@ Key flags: `--mode`, `--defaults`, `--api-url`, `--node-url`, `--create-node`, ` | Command | Summary | |--------|---------| | `kaleido wallet address` | New BTC deposit address | -| `kaleido wallet balance` | BTC balance | -| `kaleido wallet send
` | Send BTC | -| `kaleido wallet utxos` | List UTXOs | -| `kaleido wallet create-utxos` | Create UTXOs for RGB usage (`--up-to`, `--fee-rate`, `--skip-sync`) | +| `kaleido wallet balance` | BTC balance (`--skip-sync`) | +| `kaleido wallet send
` | Send BTC (`--fee-rate`, `--skip-sync`) | +| `kaleido wallet utxos` | List UTXOs (`--skip-sync`) | +| `kaleido wallet create-utxos` | Create UTXOs for RGB usage (`--num/-n`, `--size`, `--up-to`, `--fee-rate`, `--skip-sync`) | | `kaleido wallet transactions` | Transaction history | | `kaleido wallet backup ` | Backup wallet data | | `kaleido wallet restore ` | Restore wallet data | -| `kaleido wallet change-password` | Change wallet password | +| `kaleido wallet change-password` | Change wallet password (`--old-password`, `--new-password`) | | `kaleido wallet estimate-fee` | Estimate fee rate (`--blocks/-b`, default 6) | ## `asset` @@ -100,14 +103,14 @@ Key flags: `--mode`, `--defaults`, `--api-url`, `--node-url`, `--create-node`, ` | `kaleido asset list` | List assets | | `kaleido asset balance ` | Asset balance | | `kaleido asset metadata ` | Asset metadata | -| `kaleido asset invoice ` | Create an RGB invoice | -| `kaleido asset send ` | Send RGB assets | -| `kaleido asset send-batch` | Send to many recipients | +| `kaleido asset invoice ` | Create an RGB invoice (`--amount/-a`, `--min-confirmations`, `--duration`, `--transport-endpoint`) | +| `kaleido asset send ` | Send RGB assets (`--fee-rate`, `--min-confirmations`, `--donation`, `--transport-endpoint`, `--witness-amount-sat`, `--witness-blinding`, `--skip-sync`) | +| `kaleido asset send-batch ` | Send to many recipients, from a JSON file | | `kaleido asset transfers ` | Transfer history | -| `kaleido asset refresh` | Refresh pending transfers | +| `kaleido asset refresh` | Refresh pending transfers (`--skip-sync`) | | `kaleido asset sync` | Sync RGB wallet | -| `kaleido asset fail-transfers` | Mark pending transfers as failed | -| `kaleido asset media` | Fetch asset media | +| `kaleido asset fail-transfers` | Mark pending transfers as failed (`--batch-idx`, `--no-asset-only`, `--skip-sync`) | +| `kaleido asset media ` | Fetch asset media by SHA-256 digest | ### `asset issue` @@ -117,15 +120,15 @@ Key flags: `--mode`, `--defaults`, `--api-url`, `--node-url`, `--create-node`, ` | `kaleido asset issue cfa` | Issue a collectible fungible asset | | `kaleido asset issue uda` | Issue a unique digital asset | -All `issue` subcommands accept `--precision` for the number of decimal places. +All `issue` subcommands accept `--precision` for the number of decimal places, and express `--supply` in the smallest raw unit. `cfa` and `uda` also accept `--description` and `--file`. ## `channel` | Command | Summary | |--------|---------| | `kaleido channel list` | List channels | -| `kaleido channel open ` | Open a channel | -| `kaleido channel close ` | Close a channel (requires `--peer `) | +| `kaleido channel open ` | Open a channel (`--capacity/-c`, `--push-msat`, `--asset-id`, `--asset-amount`, `--push-asset-amount`, `--public/--private`, `--with-anchors`, `--fee-base-msat`, `--fee-proportional-millionths`, `--temporary-channel-id`) | +| `kaleido channel close ` | Close a channel (requires `--peer `; `--force` for a unilateral close) | ### `channel order` @@ -135,7 +138,7 @@ All `issue` subcommands accept `--precision` for the number of decimal places. | `kaleido channel order get ` | Fetch order status (`--access-token`) | | `kaleido channel order pay ` | Pay for a channel order (`--access-token`; non-interactively pass `--onchain` or `--offchain`, plus `--fee-rate` and `--yes`) | | `kaleido channel order decide ` | Submit a rate decision (`--accept` or `--reject`, `--access-token`) | -| `kaleido channel order estimate-fees` | Estimate channel-order fees | +| `kaleido channel order estimate-fees` | Estimate channel-order fees (`--lsp-balance`, `--client-balance`, `--asset-id`, `--lsp-asset-amount`, `--client-asset-amount`, `--expiry-blocks`, `--token`, `--rfq-id`) | ### `channel lsp` @@ -170,7 +173,7 @@ All `issue` subcommands accept `--precision` for the number of decimal places. |--------|---------| | `kaleido market assets` | List assets | | `kaleido market pairs` | List pairs | -| `kaleido market quote ` | Request a quote | +| `kaleido market quote ` | Request a quote (`--from-amount`/`--to-amount`, `--from-layer`, `--to-layer`) | | `kaleido market info` | Maker node information | | `kaleido market routes ` | Available routes | @@ -180,7 +183,7 @@ All `issue` subcommands accept `--precision` for the number of decimal places. | Command | Summary | |--------|---------| -| `kaleido swap atomic init ` | Initialize an atomic swap | +| `kaleido swap atomic init ` | Initialize an atomic swap (`--from-amount`/`--to-amount`, `--from-layer`, `--to-layer`, `--yes/-y`) | | `kaleido swap atomic execute` | Execute the swap (`--swapstring`, `--taker-pubkey`, `--payment-hash`, prompted if omitted; `--auto-whitelist` whitelists on the local node first) | | `kaleido swap atomic status ` | Atomic swap status | | `kaleido swap atomic run ` | Run the full atomic flow | @@ -191,11 +194,34 @@ All `issue` subcommands accept `--precision` for the number of decimal places. |--------|---------| | `kaleido config show` | Print current config | | `kaleido config set ` | Update one config key | -| `kaleido config reset` | Reset config to defaults | +| `kaleido config reset` | Reset config to defaults (`--yes/-y`) | | `kaleido config path` | Print config file path | Valid config keys: `node-url`, `api-url`, `network`, `spawn-dir` +## Amounts And Layers + +| Commands | Amount unit | +|----------|-------------| +| `market quote`, `swap atomic init`, `swap atomic run` | Display units — `--from-amount 0.001` is 0.001 BTC | +| `asset invoice`, `asset send`, `payment *` | Raw integer units, per the asset's precision | +| `wallet send`, `wallet create-utxos`, `channel open --capacity` | Satoshis | + +Layer values also differ by command: `market quote` accepts `BTC_LN`, `RGB_LN`, and `BTC_ONCHAIN`, while `swap atomic init` and `swap atomic run` accept `BTC_L1`, `BTC_LN`, `RGB_L1`, and `RGB_LN`. + +## Short Aliases + +| Alias | Option | Used by | +|-------|--------|---------| +| `-p` | `--password` | `node init`, `node unlock`, `wallet backup`, `wallet restore` | +| `-y` | `--yes` | `node clean`, `config reset`, `channel order create`, `channel order pay`, `swap atomic init`, `swap atomic run` | +| `-n` | `--node` / `--num` | `node use` / `wallet create-utxos` | +| `-s` | `--service` | `node logs` | +| `-c` | `--capacity` | `channel open` | +| `-a` | `--amount` / `--amount-msat` | `asset invoice` / `payment invoice` | +| `-e` | `--expiry` | `payment invoice` | +| `-b` | `--blocks` | `wallet estimate-fee` | + ## Machine-Readable Mode Every command group can be combined with `--json`: @@ -204,3 +230,5 @@ Every command group can be combined with `--json`: kaleido --json wallet balance kaleido --json market quote BTC/USDT --from-amount 0.001 ``` + +Pair it with `--agent` in scripts so a missing value fails fast instead of waiting on a prompt, and add `--yes` to anything that spends funds or accepts a price. See [Troubleshooting](/cli/troubleshooting#scripting-and-automation). diff --git a/mintlify-docs/cli/faq.mdx b/mintlify-docs/cli/faq.mdx new file mode 100644 index 0000000..5d8ab3f --- /dev/null +++ b/mintlify-docs/cli/faq.mdx @@ -0,0 +1,205 @@ +--- +title: "KaleidoCLI FAQ" +sidebarTitle: "FAQ" +description: "Common questions about the KaleidoCLI, covering Docker requirements, amount units, swap scopes, custody, configuration precedence, and scripted use" +--- + +## Frequently Asked Questions + + + + Only for the commands that talk to a node. + + | Command groups | Needs a node | + | ---------------------------------------------------------------------- | ----------------------------------------- | + | `market`, `config`, `channel lsp`, `channel order get` / `decide` | No — these only reach the KaleidoSwap API | + | `node`, `wallet`, `asset`, `channel`, `peer`, `payment`, `swap atomic` | Yes | + + You can browse pairs and request quotes with nothing installed but the CLI itself: + + ```bash + kaleido setup --mode market --defaults + kaleido market pairs + ``` + + Docker is needed only for the Docker-backed environments that `node` manages. If you already run an RGB Lightning Node elsewhere, point the CLI at it with `--node-url` and skip Docker entirely. + + + + `setup` is the first-run path, `node create` is the wizard for additional environments. + + * **`kaleido setup`** saves your API and node defaults to `~/.kaleido/config.json` and, in `local` mode, creates and starts one environment with default ports. Bare `kaleido setup` runs non-interactively, so Docker must already be running. + * **`kaleido node create [name]`** prompts for base directory, name, node count, network, and base ports. Use it when you want a second environment or non-default ports. + + See [Getting Started](/cli/getting-started) and [Node Environments](/cli/node-environments). + + + + Because two different unit conventions are in play, depending on the command. + + | Commands | Unit | + | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------- | + | `market quote`, `swap atomic init`, `swap atomic run` | **Display units** — `--from-amount 0.001` means 0.001 BTC | + | `asset invoice`, `asset send`, `payment invoice`, `payment send`, `payment keysend` | **Raw integer units** — the asset's precision decides the conversion | + | `wallet send`, `wallet create-utxos`, `channel open --capacity` | Satoshis | + + So `--from-amount 0.001` is right for a quote, while `kaleido asset send rgb:abc... 100 rgb:invoice...` sends 100 raw units, not 100 display units. Check an asset's precision with `kaleido asset metadata ` before sending. + + + + They are two different scopes over the same protocol. + + | Scope | Maker side | Use it for | + | ----------------------- | ---------------------------- | -------------------------------------------------------- | + | `kaleido swap atomic …` | The remote KaleidoSwap maker | Real trades, using your local node as taker | + | `kaleido node swap …` | Your own node | Debugging, demos, and driving each protocol step by hand | + + For a normal trade, `kaleido swap atomic run ` wraps init, whitelist, and execute in one command. See [Market And Swaps](/cli/market-and-swaps). + + + + The accepted set depends on the command: + + * `market quote` — `BTC_LN`, `RGB_LN`, `BTC_ONCHAIN` + * `swap atomic init` and `swap atomic run` — `BTC_L1`, `BTC_LN`, `RGB_L1`, `RGB_LN` + + Both `--from-layer` and `--to-layer` are optional: when omitted, the layers are derived from the requested pair direction. Pass them explicitly when you need a specific route, such as sending over Lightning and receiving over RGB on Lightning: + + ```bash + kaleido market quote BTC/USDT --from-amount 0.001 --from-layer BTC_LN --to-layer RGB_LN + ``` + + + + **No.** The CLI is a terminal client over two HTTP APIs. The mnemonic is generated inside the RGB Lightning Node when you run `kaleido node init`, and every signature happens there. Nothing in the CLI can move funds the node has not authorised. + + Wallet passwords passed with `--password` land in your shell history — prefer the interactive prompt for anything you care about, and keep backups from `kaleido wallet backup` somewhere safe. + + + + The node keeps its keys encrypted at rest, so it starts locked. `kaleido node init` runs once per node; `kaleido node unlock` runs after every restart. + + Unlock also tells the node which Bitcoin services to use. Interactively the CLI offers three profiles — signet defaults, regtest defaults, or custom — and asks how the node should follow the chain: + + * `--chain-sync block` (default) reads blocks from a bitcoind over RPC + * `--chain-sync transaction` follows the chain from the indexer only, with no bitcoind at all + + With `--chain-sync transaction`, the `--bitcoind-*` options are ignored. See [Node Environments](/cli/node-environments#initialize-and-unlock). + + + + In this order, highest first: + + 1. Command-line flags: `--node-url`, `--api-url` + 2. Environment variables: `KALEIDO_NODE_URL`, `KALEIDO_API_URL` + 3. Stored config in `~/.kaleido/config.json` + + Inspect the stored layer with `kaleido config show` and its path with `kaleido config path`. Note that `kaleido node use ` writes to the stored config, so it has no effect on a command that also passes `--node-url`. + + + + Yes. Each environment is a separate Docker Compose project with its own compose file, volumes, and ports, and one environment can hold several nodes. + + ```bash + kaleido node create testenv # ask for 2 nodes at the wizard prompt + kaleido node list # ● marks the active node + kaleido node use testenv --node 2 + ``` + + Node 1 gets daemon port 3001 and peer port 9735, node 2 gets 3002 and 9736, and so on. When exactly one environment exists, commands like `up`, `stop`, `logs`, and `clean` auto-detect it; with several, you must name one. + + + + How much they destroy: + + | Command | Containers | Networks | Data volumes | + | -------------------- | ---------- | -------- | ------------ | + | `kaleido node stop` | Stopped | Kept | Kept | + | `kaleido node down` | Removed | Removed | Kept | + | `kaleido node clean` | Removed | Removed | **Deleted** | + + `clean` is irreversible: it takes the environment down and then deletes the data volumes, wallet included. Take a `kaleido wallet backup` first if the node holds anything you need. + + + + RGB assignments live on specific Bitcoin outputs, so the node needs spare "colored" UTXOs to allocate before it can issue, receive, or send an asset. A funded on-chain balance sitting in one large UTXO is not enough. + + ```bash + kaleido wallet create-utxos --num 10 --size 3000 + ``` + + Create them ahead of heavy RGB activity rather than one at a time. `--up-to` changes `--num` from "create this many" to "top up to this many in total". + + + + Three flags cover it: + + * `--json` returns raw JSON instead of tables, for piping into `jq` + * `--agent` disables every interactive prompt, so a missing value fails instead of blocking + * `--yes` accepts quotes, payments, and destructive confirmations that would otherwise prompt + + ```bash + kaleido --json --agent market quote BTC/USDT --from-amount 0.001 | jq '.to_asset.amount' + kaleido --agent swap atomic run BTC/USDT --from-amount 0.001 --yes + ``` + + In non-interactive mode the CLI refuses rather than guessing, with messages like `--yes is required in non-interactive mode to accept the quoted price.` See [Troubleshooting](/cli/troubleshooting#scripting-and-automation). + + + + Yes — it wraps the Python SDK (`kaleido-sdk`), which is why command output maps so closely onto the API models. Practical consequences: + + * Requests use a 30-second timeout and up to 3 retries + * Errors surface as `Error: ` from the underlying SDK exception, so the [SDK error reference](/sdk/troubleshooting#error-reference) explains what a failure means + * `market quote` display amounts are converted with the same precision helpers the SDK exposes + + If you are building an application rather than running commands, use the [KaleidoSDK](/sdk/introduction) directly. + + + + | Tool | Best for | + | -------------------------------------------------------- | --------------------------------------------------------------------- | + | [KaleidoCLI](/cli/introduction) | Running a node, scripting, CI, and agent-driven flows from a terminal | + | [KaleidoSDK](/sdk/introduction) | Building an application in TypeScript or Python | + | [Desktop App](/desktop-app/getting-started/introduction) | A graphical wallet with the same trading and channel features | + + They all drive the same two APIs, so a node created with the CLI can be used from the SDK, and the other way round. + + + + The CLI is installed from source — it is not published on PyPI, so `pip install kaleido-cli` will not find it. Use the bootstrap installer or `uv`: + + ```bash + curl -fsSL https://raw.githubusercontent.com/kaleidoswap/kaleido-cli/master/install.sh | sh + uv tool install git+https://github.com/kaleidoswap/kaleido-cli.git + ``` + + Update by re-running the same command; `uv` installs replace the existing tool. There is no `kaleido --version` flag, so report your version as the output of `uv tool list` or the commit you installed from. Full options in [Installation](/cli/installation). + + + +## Get Help + +Check the [Troubleshooting](/cli/troubleshooting) for errors rather than questions, and [Additional Resources](/cli/additional-resources) for upstream documentation and links. + +For anything else, report a problem through your preferred channel from the options below, including: + +1. How you installed the CLI, and the output of `uv tool list` (there is no `--version` flag) +2. Python version (`python --version`) and your operating system +3. The exact command you ran, plus its output with `--json` added +4. Whether the node is a local Docker environment or a remote one, and the network +5. `kaleido config show` and `kaleido node ps` output, with passwords removed + + + + Ask the community. + + + + Report a bug on the relevant repository. + + + + Direct support for urgent issues. + + diff --git a/mintlify-docs/cli/getting-started.mdx b/mintlify-docs/cli/getting-started.mdx index 8091c3b..60bb606 100644 --- a/mintlify-docs/cli/getting-started.mdx +++ b/mintlify-docs/cli/getting-started.mdx @@ -1,38 +1,10 @@ --- title: "KaleidoCLI: Getting Started" sidebarTitle: "Getting Started" -description: 'Install the KaleidoCLI, run first-time setup, and configure your default API and node endpoints' +description: 'Run KaleidoCLI first-time setup, store your default API and node endpoints, and issue your first market and node commands' --- -## Requirements - -- Python 3.10 or newer -- [`uv`](https://docs.astral.sh/uv/) recommended, or `pip` -- Docker and Docker Compose for `node` commands and any local RLN workflow - -## Installation - -### Install globally with `uv` - -```bash -uv tool install git+https://github.com/kaleidoswap/kaleido-cli.git -``` - -This installs the `kaleido` executable without cloning the repository first. - -### Install from a local checkout - -```bash -git clone https://github.com/kaleidoswap/kaleido-cli -cd kaleido-cli -make install -``` - -### Bootstrap from a checkout - -```bash -python install.py -``` +This is the path from an installed CLI to your first commands. If you have not installed it yet, start with [Installation](/cli/installation). ## First-Run Setup @@ -124,20 +96,6 @@ kaleido node info kaleido wallet address ``` -## Shell Completion - -Install completion for your current shell with: - -```bash -kaleido --install-completion -``` - -Or print the completion script for manual installation: - -```bash -kaleido --show-completion -``` - ## When To Override Config Stored config is useful for your default environment. Override it per command when needed: diff --git a/mintlify-docs/cli/installation.mdx b/mintlify-docs/cli/installation.mdx new file mode 100644 index 0000000..af3798c --- /dev/null +++ b/mintlify-docs/cli/installation.mdx @@ -0,0 +1,67 @@ +--- +title: "KaleidoCLI: Installation" +sidebarTitle: "Installation" +description: 'Install the KaleidoCLI with the one-line installer, uv, or a local checkout, with the runtime requirements and shell completion' +--- + +The CLI is installed from source. It is not published on PyPI, so `pip install kaleido-cli` will not find it. + +## Requirements + +- Python 3.10 or newer +- Docker and Docker Compose for `node` commands and any local RLN workflow +- `curl` or `wget`, only for the one-line shell installer + +## Install the CLI + +### One-line installer + +For macOS, Linux, and WSL: + +```bash +curl -fsSL https://raw.githubusercontent.com/kaleidoswap/kaleido-cli/master/install.sh | sh +``` + +With Python alone, and no `curl` or `wget`: + +```bash +python3 -c "import urllib.request; exec(urllib.request.urlopen('https://raw.githubusercontent.com/kaleidoswap/kaleido-cli/master/install.py').read())" +``` + +The installer prefers `uv tool install` when available, and otherwise creates an isolated Kaleido virtual environment with a `kaleido` launcher in your user script directory. It never installs into the system Python. + +### Install globally with `uv` + +```bash +uv tool install git+https://github.com/kaleidoswap/kaleido-cli.git +``` + +This installs the `kaleido` executable without cloning the repository first. Re-run the same command to update. + +### Install from a local checkout + +```bash +git clone https://github.com/kaleidoswap/kaleido-cli +cd kaleido-cli +./install.sh +``` + +`make install` does the same through `uv tool`, and `python install.py` is the cross-platform path for Windows. + +If your shell cannot find `kaleido` after installing, the installer prints the directory to add to your `PATH` — see [Troubleshooting](/cli/troubleshooting#installation-issues). + +## Shell Completion + +Install completion for your current shell with: + +```bash +kaleido --install-completion +``` + +Or print the completion script for manual installation: + +```bash +kaleido --show-completion +``` + +With `kaleido` on your `PATH`, continue to [Getting Started](/cli/getting-started) to run first-time setup. diff --git a/mintlify-docs/cli/introduction.mdx b/mintlify-docs/cli/introduction.mdx index dae42db..49a39c2 100644 --- a/mintlify-docs/cli/introduction.mdx +++ b/mintlify-docs/cli/introduction.mdx @@ -13,23 +13,6 @@ description: 'Use the KaleidoCLI to manage local multi-asset Lightning nodes and The same binary supports both interactive terminal use and scripted automation. -## Why Use It - - - - Start in market-only mode or provision a local node environment from one setup flow. - - - Keep multiple local node stacks isolated and switch the active node with one command. - - - Work with BTC, RGB assets, invoices, transfers, backups, and Lightning payments. - - - Query pairs and quotes, and run atomic or local node swap flows. - - - ## Global Flags All command groups inherit the same root flags: @@ -64,6 +47,8 @@ Command-line flags take precedence over environment variables and stored config. ## Command Groups +Work is split across ten groups. Each one is documented subcommand by subcommand, with its arguments and flags, in [Commands](/cli/command-reference) — this table is the map of what you will find there. + | Group | Purpose | |------|---------| | `setup` | First-run setup for market-only or local-node use | @@ -86,9 +71,3 @@ kaleido --json market quote BTC/USDT --from-amount 0.001 ``` Use `--agent` when the command must fail instead of prompting for missing input. - -## Next Steps - -- Start with [Getting Started](/cli/getting-started) if you are installing the CLI for the first time. -- See [Node Environments](/cli/node-environments) if you need a local RLN stack. -- Use [Command Reference](/cli/command-reference) for the full command map. diff --git a/mintlify-docs/cli/market-and-swaps.mdx b/mintlify-docs/cli/market-and-swaps.mdx index 43cebe2..e2e9f88 100644 --- a/mintlify-docs/cli/market-and-swaps.mdx +++ b/mintlify-docs/cli/market-and-swaps.mdx @@ -1,6 +1,7 @@ --- title: 'Market And Swaps' -description: 'Browse KaleidoSwap markets, request quotes, and run order, atomic, or local node swap flows from the CLI' +sidebarTitle: 'Market & Swaps' +description: 'Browse KaleidoSwap markets, request quotes, and run atomic or local node swap flows from the CLI' --- ## Market Data @@ -24,11 +25,24 @@ kaleido market quote BTC/USDT --to-amount 500 --from-layer BTC_LN --to-layer RGB Important quote options: -- `--from-amount` or `--to-amount` +- `--from-amount` or `--to-amount` — exactly one of the two, since a quote is anchored on one side only - `--from-layer` - `--to-layer` -Supported layer values include `BTC_LN`, `RGB_LN`, and `BTC_ONCHAIN` for market quotes. + + **Amounts here are display units.** `--from-amount 0.001` means 0.001 BTC, not 1000 sat. The raw integer amounts described in [Wallet, Assets, And Payments](/cli/wallet-assets-payments) apply to `asset` and `payment` commands, not to quotes and swaps. + + +### Layer values + +The accepted set depends on the command: + +| Command | Layers | +|---------|--------| +| `market quote` | `BTC_LN`, `RGB_LN`, `BTC_ONCHAIN` | +| `swap atomic init`, `swap atomic run` | `BTC_L1`, `BTC_LN`, `RGB_L1`, `RGB_LN` | + +Both options are optional: when omitted, the layers are derived from the requested pair direction. ## Swap Scopes @@ -47,7 +61,7 @@ Use `swap atomic` when the maker side is remote but execution uses your local no | Command | Purpose | |--------|---------| -| `kaleido swap atomic init ` | Initialize the atomic swap | +| `kaleido swap atomic init ` | Initialize the atomic swap (`--yes` accepts the quoted price, required non-interactively) | | `kaleido swap atomic execute` | Execute the initialized swap (`--swapstring`, `--taker-pubkey`, `--payment-hash`, prompted if omitted; `--auto-whitelist`) | | `kaleido swap atomic status ` | Track atomic swap status | | `kaleido swap atomic run ` | Run init, whitelist, and execute in one command | @@ -79,6 +93,14 @@ Use `node swap` for low-level RLN swap steps (these live under the `node` comman This path is useful for debugging, demos, and lower-level protocol operations where you want each step exposed separately. +A swapstring carries six slash-separated fields, and the CLI validates them before whitelisting: + +```text +///// +``` + +Always quote it on the command line so the shell leaves it intact. See [Troubleshooting](/cli/troubleshooting#market-and-swaps) for what the validation errors mean. + ## Recommended Trade Flow ### Browse the market (no node required) diff --git a/mintlify-docs/cli/node-environments.mdx b/mintlify-docs/cli/node-environments.mdx index fe343ce..f2362f7 100644 --- a/mintlify-docs/cli/node-environments.mdx +++ b/mintlify-docs/cli/node-environments.mdx @@ -1,5 +1,6 @@ --- title: 'Node Environments' +sidebarTitle: 'Environments' description: 'Create, run, switch, and maintain named local multi-asset Lightning node environments with the KaleidoCLI' --- @@ -17,19 +18,25 @@ Example layout: ```text ~/.kaleido/ +├── config.json ├── default/ │ ├── docker-compose.yml │ └── volumes/ -└── staging/ +│ └── dataldk0/ +└── testenv/ ├── docker-compose.yml └── volumes/ + ├── dataldk0/ + └── dataldk1/ ``` +Each node in an environment is a `rgb_node_` service with its own data volume. Only the node itself runs locally: bitcoind, the indexer, and the RGB proxy are remote services. + ## Create An Environment ```bash kaleido node create -kaleido node create staging +kaleido node create testenv ``` The wizard prompts for: @@ -62,9 +69,11 @@ Use `kaleido node use` to update the configured node URL: ```bash kaleido node use default -kaleido node use staging --node 2 +kaleido node use testenv --node 2 ``` +Node 1 listens on daemon port 3001 and peer port 9735, node 2 on 3002 and 9736, and so on from the base ports chosen at creation. `kaleido node list` marks the active node with `●`. + This is the bridge between Docker-managed environments and all node-dependent commands such as `wallet`, `asset`, `channel`, and `payment`. ## Initialize And Unlock @@ -86,19 +95,39 @@ After every restart, unlock the wallet: kaleido node unlock ``` -Notable unlock options: +Unlock is also where the node learns which Bitcoin services to use. Run interactively, it offers a service profile — signet defaults, regtest defaults, or custom — and then asks how the node should follow the chain. + +### Chain sync mode + +| Mode | Behaviour | +|------|-----------| +| `--chain-sync block` (default) | Reads blocks from a bitcoind over RPC | +| `--chain-sync transaction` | Follows the chain from the indexer alone, with no bitcoind | -- `--password` -- `--bitcoind-user` -- `--bitcoind-pass` -- `--bitcoind-host` -- `--bitcoind-port` -- `--indexer-url` -- `--proxy-endpoint` -- `--announce-alias` -- `--announce-address` +With `transaction`, every `--bitcoind-*` option is ignored: + +```bash +kaleido node unlock --chain-sync transaction --indexer-url https://esplora.signet.kaleidoswap.com +``` -By default, the command uses the KaleidoSwap signet services exposed by the CLI. +### Unlock options + +| Option | Purpose | +|--------|---------| +| `--password`, `-p` | Wallet password, prompted securely if omitted | +| `--chain-sync` | `block` or `transaction`, as above | +| `--bitcoind-user`, `--bitcoind-pass` | bitcoind RPC credentials | +| `--bitcoind-host`, `--bitcoind-port` | bitcoind RPC endpoint | +| `--indexer-url` | Esplora (`https://…`) or Electrum (`host:port`) | +| `--proxy-endpoint` | RGB proxy endpoint | +| `--announce-alias` | Lightning peer alias to announce | +| `--announce-address` | Public address for peer discovery, repeatable | + +By default the command uses the KaleidoSwap signet services. For a scripted unlock, pass the password explicitly and disable prompts: + +```bash +kaleido --agent node unlock --password +``` ## Inspect And Lock diff --git a/mintlify-docs/cli/troubleshooting.mdx b/mintlify-docs/cli/troubleshooting.mdx new file mode 100644 index 0000000..f66ed66 --- /dev/null +++ b/mintlify-docs/cli/troubleshooting.mdx @@ -0,0 +1,476 @@ +--- +title: "KaleidoCLI Troubleshooting" +sidebarTitle: "Troubleshooting" +description: "Diagnose common KaleidoCLI errors — installation, Docker environments, node connectivity, assets, channels, and swaps — with the exact message and the fix for each" +--- + +## Installation Issues + + + + **Symptoms:** the install finished, but the shell cannot find `kaleido` + + **Cause:** the directory holding the launcher is not on your `PATH`. The installer says so on its last line: `If 'kaleido' is not found yet, add to your PATH and restart your shell.` + + **Solutions:** + 1. Restart the shell first — a new entry on `PATH` is not visible to an already-running session + 2. For a `uv` install, confirm the tool directory is on `PATH`: `uv tool dir` and `uv tool list` + 3. For the bootstrap installer, add the printed directory to `PATH` in your shell profile (`~/.bashrc`, `~/.zshrc`) + 4. On Windows, use WSL — the shell bootstrap targets macOS, Linux, and WSL + + + + **Symptoms:** `ERROR: Could not find a version that satisfies the requirement kaleido-cli` + + **Cause:** the CLI is not published on PyPI. It installs from source only. + + **Solution:** + + ```bash + uv tool install git+https://github.com/kaleidoswap/kaleido-cli.git + ``` + + Or use the bootstrap installer, which prefers `uv` and falls back to an isolated virtual environment. See [Installation](/cli/installation). + + + + **Symptoms:** the installer stops with that message + + **Solutions:** + 1. Check what you have: `python3 --version` + 2. Install a newer Python, or let `uv` manage it: `uv python install 3.12` + 3. Re-run the installer once `python3` resolves to 3.10 or newer + + + +## Setup And Environments + + + + **Symptoms:** that message from any `node` lifecycle command, or from bare `kaleido setup` + + **Cause:** the CLI shells out to `docker compose`, so both the binary and a running daemon are required. + + **Solutions:** + 1. Verify the client and the daemon: `docker version` — the "Server" block must be present + 2. Start Docker Desktop, or `sudo systemctl start docker` on Linux + 3. Confirm the Compose v2 plugin is available: `docker compose version` + 4. If you do not want Docker at all, run market-only setup: `kaleido setup --mode market --defaults` + + + + **Symptoms:** `No docker-compose.yml found in `, followed by `Run 'kaleido node create' to generate it.`, or `Environment directory not found: ` + + **Causes:** + - The environment was never created, or was created under a different base directory + - `spawn-dir` in the config points somewhere else than where the environment lives + + **Solutions:** + 1. List what the CLI can actually see: `kaleido node list` + 2. Check the base directory: `kaleido config show` — environments live under `spawn-dir`, default `~/.kaleido` + 3. Recreate it: `kaleido node create ` + + + + **Symptoms:** a lifecycle command refuses and lists the available environments + + **Cause:** the environment name is auto-detected only when exactly one exists. + + **Solution:** name it explicitly. + + ```bash + kaleido node list + kaleido node up testenv + kaleido node logs testenv --service rgb_node_1 + ``` + + The related message `No environments found. Run 'kaleido node create' first.` means the opposite problem — nothing has been created yet. + + + + **Symptoms:** `kaleido setup` stops with that message and `Choose a different environment name with --env-name to create a new node.` + + **Solutions:** + 1. Reuse the existing environment: `kaleido node up ` then `kaleido node use ` + 2. Or create a separate one: `kaleido setup --env-name taker-2` + + The interactive `kaleido node create` offers to overwrite the compose file instead, which leaves the data volumes untouched. + + + + **Symptoms:** `node up` succeeds, `node info` fails + + **Solutions:** + 1. Check container state: `kaleido node ps ` + 2. Read the node's own logs: `kaleido node logs --service rgb_node_1 --no-follow` + 3. Look for a port conflict — node 1 binds 3001 and 9735, node 2 binds 3002 and 9736. If something else holds those ports, recreate the environment with different base ports through `kaleido node create` + 4. Give the node a moment after `up`: it has to open its database before serving requests + + + +## Node Connectivity + + + + **Symptoms:** that message plus `Use --node-url or: kaleido config set node-url http://localhost:3001` + + **Cause:** the command needs a node, and no node URL was found in flags, environment, or config. + + **Solutions:** + 1. Point at an environment's node: `kaleido node use ` + 2. Or set it directly: `kaleido config set node-url http://localhost:3001` + 3. Or override for one command: `kaleido --node-url http://localhost:3002 wallet balance` + + + + **Symptoms:** a connection error from `wallet`, `asset`, `channel`, or `payment`, or balances that belong to a different node + + **Causes:** + - The containers are not running + - `node-url` still points at the node you used last + - `KALEIDO_NODE_URL` is exported in the shell and silently overrides the stored config + + **Solutions:** + 1. Confirm which node is active: `kaleido config show`, and `kaleido node list` — the active one is marked `●` + 2. Start the environment: `kaleido node up ` + 3. Check for a stale override: `echo $KALEIDO_NODE_URL` + 4. Remember the precedence: flag, then environment variable, then config + + + + **Symptoms:** `kaleido node use --node 2` refuses + + **Cause:** `--node` is a 1-based index into the nodes the compose file actually defines. + + **Solution:** run `kaleido node list` to see how many nodes the environment has. To get more, recreate it and answer the node-count prompt with a higher number. + + The related `No nodes found in environment ''. Is the compose file present?` means the compose file exists but defines no `rgb_node_*` service. + + + + **Symptoms:** `Error unlocking wallet: …`, or node commands failing right after a restart + + **Causes:** + - The node was restarted and never unlocked — `unlock` is needed every time + - The bitcoind or indexer the unlock request points at is unreachable + - The wallet was never initialised on this node + + **Solutions:** + 1. Unlock it: `kaleido node unlock` + 2. If the services are the problem, follow the chain from the indexer instead of a bitcoind: + + ```bash + kaleido node unlock --chain-sync transaction --indexer-url https://esplora.signet.kaleidoswap.com + ``` + 3. If it was never initialised, run `kaleido node init` once first + 4. Confirm the result with `kaleido node info` + + + + **Symptoms:** `Error initializing wallet: …` + + **Causes:** + - The wallet was already initialised on this node — `init` runs once per node, not once per session + - A restore was attempted with an invalid `--mnemonic` + + **Solutions:** + 1. If the node is already initialised, skip straight to `kaleido node unlock` + 2. To start over from a clean node, `kaleido node clean ` deletes the volumes — irreversibly — and then `init` can run again + 3. When restoring, quote the mnemonic so the shell does not split it: `--mnemonic "word1 word2 …"` + + + +## Wallet And Assets + + + + **Symptoms:** an insufficient-funds error from `wallet send` or `asset send` + + **Causes:** + - The balance is not confirmed yet + - There are no spare UTXOs to allocate for the RGB assignment + - The fee could not be covered on top of the amount + + **Solutions:** + 1. Check what is actually spendable: `kaleido wallet balance` and `kaleido wallet utxos` + 2. Create colored UTXOs before RGB operations: `kaleido wallet create-utxos --num 10 --size 3000` + 3. Fund the node from the [Mutiny faucet](https://faucet.mutinynet.com/) on signet, using an address from `kaleido wallet address` + 4. Check the going rate with `kaleido wallet estimate-fee --blocks 6` and pass `--fee-rate` explicitly + + + + **Symptoms:** `kaleido asset transfers ` shows a transfer that never settles + + **Solutions:** + 1. Advance pending transfers: `kaleido asset refresh` + 2. Resynchronise the RGB wallet: `kaleido asset sync` + 3. Inspect the state again: `kaleido asset transfers ` + 4. Only if a transfer is genuinely dead, release its allocations: `kaleido asset fail-transfers --batch-idx ` + + If you have been passing `--skip-sync`, drop it: the command is returning cached state on purpose. + + + + **Symptoms:** `File not found: ` or `Invalid JSON: …` + + **Cause:** `asset send-batch` takes a path to a JSON file describing the recipients, not inline flags. + + **Solution:** + + ```bash + kaleido asset send-batch ./transfers.json + ``` + + Check the path relative to your current directory, and validate the file before retrying. + + + + **Symptoms:** `wallet backup` or `wallet restore` refuses under `--agent` + + **Cause:** the destination path is a positional argument, and prompts are disabled. + + **Solution:** pass it explicitly, along with the password. + + ```bash + kaleido --agent wallet backup ~/kaleido-backup.zip --password + ``` + + Restore overwrites the current node data, so run it deliberately. + + + +## Channels And LSP Orders + + + + **Symptoms:** `channel open` or `peer connect` refuses + + **Cause:** the peer was passed as a bare pubkey. Interactively the CLI asks for the address; non-interactively it requires the full form. + + **Solutions:** + 1. Use the complete peer string: `kaleido channel open 03abc...@peer.host:9735 --capacity 100000` + 2. Connect first and confirm reachability: `kaleido peer connect 03abc...@peer.host:9735` then `kaleido peer list` + + Related non-interactive refusals: `PEER argument is required in non-interactive mode.` and `--capacity is required in non-interactive mode.` + + + + **Symptoms:** a colored-channel command refuses before contacting the node + + **Cause:** asset amounts are meaningless without the asset they refer to. The same rule applies to `--push-asset-amount`, and to `--lsp-asset-amount` / `--client-asset-amount` on LSP orders. + + **Solution:** + + ```bash + kaleido channel open 03abc...@peer.host:9735 \ + --capacity 100000 \ + --asset-id rgb:abc... \ + --asset-amount 5000 + ``` + + On LSP orders, `--lsp-asset-amount is required when --asset-id is set.` and `--client-asset-amount must be less than or equal to --lsp-asset-amount.` are the two constraints to respect. + + + + **Symptoms:** `channel close ` refuses + + **Cause:** closing needs both the channel ID and the peer pubkey. + + **Solution:** + + ```bash + kaleido channel list + kaleido channel close --peer 03abc... + ``` + + Add `--force` only when the peer is unresponsive: a unilateral close locks funds until the timelock expires. + + + + **Symptoms:** `channel order create` or `estimate-fees` refuses the asset + + **Cause:** the LSP only opens colored channels for the assets it supports. + + **Solution:** list what it offers and use one of those asset IDs. + + ```bash + kaleido channel lsp info + ``` + + `LSP did not report a connection URL.` points at the other side of the same conversation — the LSP metadata came back without a peer address, so the order cannot proceed. + + + + **Symptoms:** `channel order pay` returns `This order is not awaiting a wallet payment. Current payment state: ` + + **Causes:** + - The order was already paid + - It expired before funding + - It is waiting on a rate decision rather than a payment + + **Solutions:** + 1. Read the current state: `kaleido channel order get --access-token ` + 2. If it is waiting on a rate, decide: `kaleido channel order decide --accept` + 3. If it expired, create a new order — `--funding-within` and `--expiry-blocks` control those windows + 4. Non-interactively, pick the funding source explicitly, or you will get `Specify exactly one of --onchain or --offchain in non-interactive mode.` + + + +## Market And Swaps + + + + **Symptoms:** `Pair 'BTC/USD' not found. Use 'kaleido market pairs' to list available pairs.` + + **Causes:** + - A typo, or a ticker that is not listed + - The pair is written the wrong way round — order matters + + **Solutions:** + 1. List them: `kaleido market pairs` + 2. Use the exact `BASE/QUOTE` ticker from that output + + `No trading pairs are currently available.` is different: the maker returned an empty list, so the problem is upstream rather than in your command. + + + + **Symptoms:** a quote or swap command refuses, or `Provide --from-amount or --to-amount in non-interactive mode.` + + **Cause:** a quote is anchored on one side only — you fix what you send or what you receive, and the maker prices the other. + + **Solutions:** + 1. Pass exactly one of the two + 2. Remember these are **display units**: `--from-amount 0.001` is 0.001 BTC, not 1000 sat + 3. If the amount is rejected as invalid, check the pair's limits in `kaleido market pairs` + + + + **Symptoms:** that message, or `Swapstring fields must not be empty or whitespace.`, or `Swapstring contains invalid numeric fields.` + + **Cause:** the swapstring was truncated or mangled. Its shape is: + + ```text + ///// + ``` + + **Solutions:** + 1. Copy the whole string from the `swap atomic init` output, without wrapping it across lines + 2. Quote it, so the shell does not touch it: `--swapstring '30/rgb:abc.../10/rgb:def.../600/'` + 3. Or skip the manual step entirely with `kaleido swap atomic run ` + + + + **Symptoms:** `Auto-whitelist validation failed: …`, or messages like `Swapstring from_amount 30 does not match quote amount 31.` + + **Cause:** before whitelisting on your node, the CLI checks the swapstring against the quote you accepted. A mismatch means the swapstring belongs to a different swap, or the quote moved. + + **Solutions:** + 1. Re-run `swap atomic init` and use the swapstring and payment hash from that same response — never mix them across runs + 2. Do not reuse an old swapstring after a re-quote + 3. `Maker returned no swap payload for --payment-hash; refusing to auto-whitelist.` means the maker has no swap for that payment hash: check it with `kaleido swap atomic status ` + + + + **Symptoms:** `swap atomic init` succeeded, `swap atomic execute` fails + + **Cause:** the taker node has to accept the swap before the maker can settle it, and that step runs against your node, not the maker. + + **Solution:** the three steps must run in order. + + ```bash + kaleido swap atomic init BTC/USDT --to-amount 5 + kaleido node swap whitelist --swapstring '' + kaleido swap atomic execute --swapstring '' --taker-pubkey --payment-hash + ``` + + Or let the CLI do it: add `--auto-whitelist` to `execute`, or use `kaleido swap atomic run `. + + + + **Symptoms:** `execute` returned, but the assets have not arrived + + **Solutions:** + 1. Poll the maker's view: `kaleido swap atomic status ` + 2. Poll your node's view: `kaleido node swap status --taker` + 3. List what the node knows: `kaleido node swap list` + 4. Advance pending RGB transfers: `kaleido asset refresh` + + Insufficient outbound capacity on the leg you are sending is the usual cause. Check `kaleido channel list` for capacity on that specific asset, not just the total balance. + + + +## Scripting And Automation + + + + **Symptoms:** a script stalls with no output + + **Cause:** the command is waiting on an interactive prompt that nothing will answer. + + **Solution:** run it with `--agent`, which turns every prompt into an error instead: + + ```bash + kaleido --agent --json wallet balance + ``` + + You will then get an explicit refusal such as `PAIR argument is required in non-interactive mode.` or ` + + + **Symptoms:** one of `--yes is required in non-interactive mode to accept the quoted price.`, `… to accept the RFQ price.`, `… to pay the order.`, or the JSON-mode variants + + **Cause:** anything that spends money or accepts a price asks for confirmation, and there is no one to ask. + + **Solutions:** + 1. Add `--yes` once you are satisfied with the parameters + 2. Price-check first with `kaleido market quote` or `kaleido channel order estimate-fees`, then execute with `--yes` + 3. `kaleido node clean` and `kaleido config reset` take `--yes` too + + + + **Symptoms:** `Must specify exactly one of --accept or --reject`, `Must specify at most one of --taker or --maker`, or `Specify exactly one of --onchain or --offchain in non-interactive mode.` + + **Cause:** these pairs are choices, not toggles, and the CLI refuses to guess when neither or both are given. + + **Solution:** pass exactly one. Interactively, omitting both makes the CLI prompt instead. + + + +## Debugging + +When a command fails and the message is not enough, work outward from the CLI's own view of the world: + +```bash +kaleido config show # which API and node URL are in use +kaleido node list # environments, and which node is active +kaleido node ps # container state +kaleido node logs --service rgb_node_1 --no-follow +kaleido node info # is the node reachable and unlocked +kaleido --json # the raw API response +``` + +Check `echo $KALEIDO_NODE_URL` and `echo $KALEIDO_API_URL` as well: an exported variable overrides the stored config and is easy to forget. + +## Get Help + +Check the [FAQ](/cli/faq) for questions rather than errors, and [Additional Resources](/cli/additional-resources) for upstream documentation and links. + +For anything else, report a problem through your preferred channel from the options below, including: + +1. How you installed the CLI, and the output of `uv tool list` (there is no `--version` flag) +2. Python version (`python --version`) and your operating system +3. The exact command you ran, plus its output with `--json` added +4. Whether the node is a local Docker environment or a remote one, and the network +5. `kaleido config show` and `kaleido node ps` output, with passwords removed + + + + Ask the community. + + + Report a bug on the relevant repository. + + + Direct support for urgent issues. + + diff --git a/mintlify-docs/cli/wallet-assets-payments.mdx b/mintlify-docs/cli/wallet-assets-payments.mdx index a5b5bbd..14a55a5 100644 --- a/mintlify-docs/cli/wallet-assets-payments.mdx +++ b/mintlify-docs/cli/wallet-assets-payments.mdx @@ -1,5 +1,6 @@ --- title: 'Wallet, Assets, And Payments' +sidebarTitle: 'Wallet & Assets' description: 'Manage bitcoin, Bitcoin L2 assets, Lightning invoices, and node backups through the KaleidoCLI' --- @@ -12,6 +13,10 @@ kaleido node use default kaleido node unlock ``` + + **Units on this page.** `wallet` amounts are satoshis, and `asset` and `payment` amounts are raw integer units, where the asset's precision decides the conversion — check it with `kaleido asset metadata `. Display amounts such as `--from-amount 0.001` appear only on [market and swap commands](/cli/market-and-swaps). + + ## BTC Wallet ### Common wallet commands @@ -28,23 +33,42 @@ kaleido node unlock | `kaleido wallet backup ` | Create an encrypted wallet backup | | `kaleido wallet restore ` | Restore from a backup archive | | `kaleido wallet change-password` | Rotate the wallet password | +`balance`, `utxos`, and `transactions` accept `--skip-sync` to return cached state without syncing first. + ### Examples ```bash kaleido wallet address kaleido wallet balance -kaleido wallet send 50000 bc1q... +kaleido wallet send 50000 bc1q... --fee-rate 2 +kaleido wallet estimate-fee --blocks 6 +``` + +### Colored UTXOs + +RGB assignments live on specific Bitcoin outputs, so the node needs spare UTXOs before it can issue, receive, or send an asset: + +```bash kaleido wallet create-utxos --num 10 --size 3000 ``` +| Option | Purpose | +|--------|---------| +| `--num`, `-n` | How many UTXOs to create | +| `--size` | Size of each UTXO in satoshis | +| `--up-to` | Treat `--num` as a total to top up to, rather than a count to add | +| `--fee-rate` | On-chain fee rate in sat/vbyte | +| `--skip-sync` | Skip the blockchain sync before creating them | + ### Backup and restore ```bash kaleido wallet backup ~/kaleido-backup.zip kaleido wallet restore ~/kaleido-backup.zip +kaleido wallet change-password --old-password --new-password ``` -Both commands accept `--password`. Restore overwrites the current node data, so use it deliberately. +`backup` and `restore` both accept `--password`, `-p`. Restore overwrites the current node data, so use it deliberately. ## RGB Assets @@ -57,7 +81,7 @@ Both commands accept `--password`. Restore overwrites the current node data, so | `kaleido asset metadata ` | Show asset metadata | | `kaleido asset invoice ` | Create an RGB invoice | | `kaleido asset send ` | Send RGB assets | -| `kaleido asset send-batch` | Send to multiple RGB recipients in one transaction | +| `kaleido asset send-batch ` | Send to multiple RGB recipients in one transaction, from a JSON file | | `kaleido asset transfers ` | Inspect transfer history | | `kaleido asset refresh` | Refresh pending transfers | | `kaleido asset sync` | Synchronize the RGB wallet | @@ -80,6 +104,8 @@ Use: - `cfa` for collectible fungible assets - `uda` for unique digital assets +All three accept `--precision` for the number of decimal places, and `--supply` is expressed in the smallest raw unit. `cfa` and `uda` also accept `--description`. + ### Asset invoice and send examples ```bash @@ -93,8 +119,27 @@ Notable `asset send` options: - `--min-confirmations` - `--donation` - `--transport-endpoint` +- `--witness-amount-sat` and `--witness-blinding` - `--skip-sync` +### Batch sends + +`asset send-batch` takes a path to a JSON file describing the recipients, not inline flags: + +```bash +kaleido asset send-batch ./transfers.json +``` + +### Keeping transfers moving + +```bash +kaleido asset refresh +kaleido asset sync +kaleido asset transfers rgb:abc123... +``` + +Run `refresh` to advance pending transfers and `sync` to resynchronise the RGB wallet. Only when a transfer is genuinely dead should you release its allocations with `kaleido asset fail-transfers`, which accepts `--batch-idx` to target one batch, `--no-asset-only` to limit it to transfers with no asset, and `--skip-sync`. + ## Lightning And RGB+LN Payments ### Payment commands @@ -133,4 +178,4 @@ When paying zero-amount invoices, provide `--amount-msat`. For RGB+LN payments, - Use `--skip-sync` only when stale wallet or transfer state is acceptable. - Create extra UTXOs before heavy RGB activity to avoid running out of usable colored outputs. -See [Channels And LSP Flows](/cli/channels-lsp) next if you are managing channels or ordering inbound liquidity. +See [Channels And LSP Flows](/cli/channels-lsp) next if you are managing channels or ordering inbound liquidity, or [Troubleshooting](/cli/troubleshooting#wallet-and-assets) if a balance, transfer, or send is not behaving. diff --git a/mintlify-docs/cn/ai-tools/additional-resources.mdx b/mintlify-docs/cn/ai-tools/additional-resources.mdx index f60abe6..44ed165 100644 --- a/mintlify-docs/cn/ai-tools/additional-resources.mdx +++ b/mintlify-docs/cn/ai-tools/additional-resources.mdx @@ -23,16 +23,6 @@ description: "KaleidoSwap AI 工具的相关链接：各个源码仓库、MCP -### 单域 MCP 服务器 - -| 仓库 | 工具前缀 | 领域 | -|-----------|-------------|--------| -| [wdk-wallet-mcp](https://github.com/kaleidoswap/wdk-wallet-mcp) | `wdk_*` | RGB Lightning Node 钱包、通道、原子交换接单方 | -| [wdk-wallet-spark-mcp](https://github.com/kaleidoswap/wdk-wallet-spark-mcp) | `spark_*` | Spark 钱包、闪电网络、代币转账、BTC 桥接 | -| [wdk-wallet-liquid-mcp](https://github.com/kaleidoswap/wdk-wallet-liquid-mcp) | `liquid_*` | Liquid 钱包、L-BTC 与资产余额、保密发送 | -| [kaleidoswap-mcp](https://github.com/kaleidoswap/kaleidoswap-mcp) _（已归档）_ | `kaleidoswap_*` | 已被 kaleido-mcp 中的 `kaleidoswap_*` 工具取代 | -| [l402-gateway-mcp](https://github.com/kaleidoswap/l402-gateway-mcp) _（已归档）_ | `mpp_*`、`l402_*` | 已被 kaleido-mcp 中的 `mpp_*` / `l402_*` 工具取代 | - ## 协议规范 @@ -50,42 +40,32 @@ description: "KaleidoSwap AI 工具的相关链接：各个源码仓库、MCP -## KaleidoSwap 参考文档 +## 获取帮助 -先读这几篇，代理工具会好理解得多，因为那些工具只是它们之上的一层薄封装。 +如果遇到的是报错，请查看[故障排查](/cn/ai-tools/troubleshooting)；如果是疑问，请查看[常见问题](/cn/ai-tools/faq)。 - - - 原子 HTLC 流程如何结算，也就是交换工具所编排的那套流程。 - - - `kaleidoswap_lsp_*` 背后的通道下单接口端点。 - - - KaleidoAgent 调用的那个可执行文件，也是节点生命周期工具的来源。 - - - 直接从 TypeScript 或 Python 调用交换基础设施，跳过代理这一层。 - - +其他情况请通过下面任一渠道反馈问题，并附上： -## 产品与社区 +1. 使用的接入方式与版本（MCP 服务器名称、KaleidoAgent 提交号，或桌面应用版本） +2. 你所在的网络（regtest、signet 或主网） +3. 失败的工具名称和报错文本 +4. 宿主与运行时版本（MCP 客户端、Node.js） +5. 你的配置，并移除其中的种子和所有密钥 - - - 产品概览，以及每个 skill 的可阅读与可下载版本。 + + + 向社区提问。 - - 社区支持与讨论。 - - - Issue、Pull Request 和完整源码。 + + 在相关仓库提交缺陷报告。 紧急问题的直接支持渠道。 - - 反馈某个 AI 接入方式的问题时，请附上失败的工具名称、你所在的网络，以及移除了种子和所有 API 密钥的配置。请先查看[故障排查](/cn/ai-tools/troubleshooting)。 - +--- + + + 产品概览，以及每个 skill 的可阅读与可下载版本。 + diff --git a/mintlify-docs/cn/ai-tools/faq.mdx b/mintlify-docs/cn/ai-tools/faq.mdx index 5c12177..28c9f43 100644 --- a/mintlify-docs/cn/ai-tools/faq.mdx +++ b/mintlify-docs/cn/ai-tools/faq.mdx @@ -94,7 +94,9 @@ description: "关于 KaleidoSwap AI 工具的常见问题：托管方式、种 ## 获取帮助 -如果遇到的是报错而不是疑问，请查看[故障排查](/cn/ai-tools/troubleshooting)。其他情况请通过下面任一渠道反馈问题，并附上： +如果遇到的是报错而不是疑问，请查看[故障排查](/cn/ai-tools/troubleshooting)；上游文档与相关链接见[更多资源](/cn/ai-tools/additional-resources)。 + +其他情况请通过下面任一渠道反馈问题，并附上： 1. 使用的接入方式与版本（MCP 服务器名称、KaleidoAgent 提交号，或桌面应用版本） 2. 你所在的网络（regtest、signet 或主网） diff --git a/mintlify-docs/cn/ai-tools/getting-started.mdx b/mintlify-docs/cn/ai-tools/getting-started.mdx index b81db17..97bfbba 100644 --- a/mintlify-docs/cn/ai-tools/getting-started.mdx +++ b/mintlify-docs/cn/ai-tools/getting-started.mdx @@ -1,10 +1,10 @@ --- title: "AI 工具：快速上手" sidebarTitle: "快速上手" -description: "把 AI 代理接入比特币：从测试网络上的第一次只读工具调用，到验证过一笔报价之后再开启真实执行。" +description: "选择把 AI 代理接入比特币的方式：MCP 服务器、KaleidoAgent 还是 KaleidoMind，以及每一种的前置条件和花费把关机制。" --- -这是从「装好工具」到「验证一笔交换」的完整路径。顺序是先只读，再报价，最后执行 —— 因为除第一步之外，每一步都会动用真实价值。 +四种接入方式把同一套比特币工具交给模型，区别主要在于谁来跑代理循环、以及什么东西拦住一笔花费。这一页负责在它们之间做选择：先要准备什么、哪一种适合你，以及每一种如何为动用资金的调用把关。 ## 开始之前 @@ -26,87 +26,9 @@ description: "把 AI 代理接入比特币：从测试网络上的第一次只 | 在本地端通过聊天或语音操作钱包 | [KaleidoMind](/cn/ai-tools/kaleido-mind) | | 不改代码就调整代理行为 | [Skills](/cn/ai-tools/skills) | -## 首次运行：MCP 服务器 +无论你选择哪一种接入方式，首次运行都遵循同样的顺序：先只读调用，再钱包调用，然后报价，最后才是执行。这个顺序既是谨慎，也是诊断手段。只读那一步失败说明是连接问题，钱包那一步失败说明是种子或网络问题，而能走到报价的，这两类问题都已经排除了。 - - - 把 `kaleido-mcp` 配置块加入你的 MCP 宿主配置，将 `KALEIDOSWAP_API_URL` 指向测试环境，并把 `SPARK_NETWORK` 设为 `REGTEST`。完整 JSON 见 [MCP 服务器页面](/cn/ai-tools/mcp-servers#client-configuration)。 - - - - MCP 宿主只在启动时读取配置。已经在运行的客户端不会自动识别新服务器，必须重启。 - - - - 先从不会动用资金的操作开始。请求行情数据，它既不需要种子也不需要节点： - - ``` - What is the current Bitcoin price and the Fear and Greed index? - ``` - - 这会触发 `l402_get_price` 和 `l402_get_sentiment`。只要有回答，连接就是通的。 - - - - 接着确认钱包工具能正常解析： - - ``` - Show me my Spark balance and my Spark address. - ``` - - 这会调用 `spark_get_balance` 和 `spark_get_address`。这一步报错说明是种子或网络问题，而不是连接问题。 - - - - 只询价，不下单： - - ``` - Quote 100000 sats of BTC into USDT. Do not place an order. - ``` - - `kaleidoswap_get_quote` 会返回一个 `rfq_id`、原始数量、费用和过期时间。请仔细核对原始数量：它们以资产的最小单位计价，不是显示单位。 - - - - 一笔原子交换需要 DEX 工具和钱包工具配合，并且节点必须在通道中持有该资产。[跨服务器调用顺序](/cn/ai-tools/mcp-servers#atomic-swap-across-servers)按顺序列出了每一次调用。 - - - -## 首次运行：KaleidoAgent - - - - `agent.config.json` 中的 `portfolio.dry_run` 默认为 `true`。先别动它。代理会完成推理、决策并汇报一笔交易，但不会真正提交。 - - - - ```bash - npm start - ``` - - 这会同时启动代理和监听 `http://localhost:4242` 的状态 API。若要使用仪表盘，另外运行 `npm run dev:webapp` 并打开 `http://localhost:5173`。 - - - - 不必等定时任务，可以直接让状态 API 跑一轮： - - ```bash - curl -X POST http://localhost:4242/run \ - -H 'Content-Type: application/json' \ - -d '{"task_id":"rebalance"}' - ``` - - 然后读取 `GET /status`，查看它的决策、它看到的余额，以及 token 开销。 - - - - 确认 `max_swap_usd`、`min_btc_reserve_sats` 和 `stop_loss_btc_sats` 与你在测试网络上能接受的损失相符。每笔交换提交之前都会校验这些参数。 - - - - 当连续几轮的 dry-run 决策都看起来正确后，再把 `portfolio.dry_run` 设为 `false`。 - - +每种接入方式都有自己的操作指引：[MCP 服务器](/cn/ai-tools/mcp-servers#first-run)和 [KaleidoAgent](/cn/ai-tools/kaleido-agent#first-run)。KaleidoMind 是嵌入宿主运行的库，本身不独立运行，所以它的首次运行就是[桌面应用的安装流程](/cn/desktop-app/getting-started/installation)。[Skills](/cn/ai-tools/skills) 改变的是代理在这些接入方式上的行为，它本身不是一种接入方式。 ## 确认机制长什么样 @@ -114,9 +36,9 @@ description: "把 AI 代理接入比特币：从测试网络上的第一次只 | 接入方式 | 把关机制 | |---------|------| -| **KaleidoMind** | 结构性把关。每个会动用资金的工具都标记了 `requiresConfirmation`，引擎会暂停并等待宿主的确认面板。模型无法绕过 | -| **KaleidoAgent** | 策略性把关。`dry_run` 加上 `agent.config.json` 中的风险上限，在提交前校验 | -| **通用宿主中的 MCP 服务器** | 取决于你的宿主客户端。多数 MCP 客户端会为每次工具调用弹出确认，但那是客户端的行为，不是服务器的 | +| **[KaleidoMind](/cn/ai-tools/kaleido-mind)** | 结构性把关。每个会动用资金的工具都标记了 `requiresConfirmation`，引擎会暂停并等待宿主的确认面板。模型无法绕过 | +| **[KaleidoAgent](/cn/ai-tools/kaleido-agent)** | 策略性把关。`dry_run` 加上 `agent.config.json` 中的风险上限，在提交前校验 | +| **[MCP 服务器](/cn/ai-tools/mcp-servers)** | 取决于你的宿主客户端。多数 MCP 客户端会为每次工具调用弹出确认，但那是客户端的行为，不是服务器的 | 通用 MCP 宿主是保护最弱的一条路径。如果你的客户端自动批准工具调用，LLM 就能不经询问地从配置的钱包中花钱。在完全弄清客户端如何处理批准之前，请只使用测试网络种子。 diff --git a/mintlify-docs/cn/ai-tools/installation.mdx b/mintlify-docs/cn/ai-tools/installation.mdx index 0d6a55d..f7f2a02 100644 --- a/mintlify-docs/cn/ai-tools/installation.mdx +++ b/mintlify-docs/cn/ai-tools/installation.mdx @@ -8,15 +8,15 @@ description: "安装 KaleidoSwap AI 工具：MCP 服务器网关、KaleidoAgent | 接入方式 | 安装路径 | 前置条件 | |---------|-------------|---------------| -| **[MCP 服务器](/cn/ai-tools/mcp-servers)** | 网关用 `npx`，专用服务器需本地构建 | Node.js 20+，一个 MCP 宿主客户端 | -| **[KaleidoAgent](/cn/ai-tools/kaleido-agent)** | 克隆仓库并从源码构建 | Node.js 20+、KaleidoCLI、Nanobot、一个 LLM API 密钥 | -| **[KaleidoMind](/cn/ai-tools/kaleido-mind)** | 随桌面应用一起提供，或构建仓库用于开发 | 桌面应用，或 pnpm 与 QVAC SDK | +| **[MCP 服务器](#mcp-servers)** | 网关用 `npx`，专用服务器需本地构建 | Node.js 20+，一个 MCP 宿主客户端 | +| **[KaleidoAgent](#kaleidoagent)** | 克隆仓库并从源码构建 | Node.js 20+、KaleidoCLI、Nanobot、一个 LLM API 密钥 | +| **[KaleidoMind](#kaleidomind)** | 随桌面应用一起提供，或构建仓库用于开发 | 桌面应用，或 pnpm 与 QVAC SDK | 这里的每一种接入方式都会使用真实的 BIP-39 助记词签名，或直接驱动一个运行中的节点。请先在测试网络上起步，在配置验证通过之前保持 `dry_run` 开启，并且永远不要把主网种子写入会被提交或分享的文件。 -## MCP 服务器 +## MCP 服务器 {#mcp-servers} `kaleido-mcp` 是跑通工具调用的最快路径，已发布到 npm，无需本地构建： @@ -38,11 +38,11 @@ node dist/index.js `kaleidoswap-mcp` 和 `l402-gateway-mcp` 已归档，它们各自的 README 也建议集成方改用 `kaleido-mcp`。新项目请不要再克隆或构建它们。 -完整的环境变量参考、stdio 与 HTTP 传输方式的对比、工具清单，以及每个服务器的客户端配置 JSON，都在 [MCP 服务器页面](/cn/ai-tools/mcp-servers#installation-and-configuration)。 +完整的环境变量参考、stdio 与 HTTP 传输方式的对比、按领域划分的工具清单，以及每个服务器的客户端配置 JSON，请查看 [MCP 服务器页面](/cn/ai-tools/mcp-servers)。 -## KaleidoAgent +## KaleidoAgent {#kaleidoagent} -前置条件：Node.js 20 或更高版本、位于 `$PATH` 中的 [KaleidoCLI](/cn/cli/getting-started)、[Nanobot](https://nanobot.dev) 运行时，以及一个 Anthropic 或 OpenAI API 密钥。 +前置条件：Node.js 20 或更高版本、位于 `$PATH` 中的 [KaleidoCLI](/cn/cli/installation)、[Nanobot](https://nanobot.dev) 运行时，以及一个 Anthropic 或 OpenAI API 密钥。 ```bash git clone https://github.com/kaleidoswap/kaleido-agent.git @@ -50,9 +50,9 @@ cd kaleido-agent npm run install:all ``` -之后的步骤 —— 设置 API 密钥、在 `agent.config.json` 中配置钱包、启动仪表盘 —— 以及容器部署方案，都在 [KaleidoAgent 页面](/cn/ai-tools/kaleido-agent#run-it)逐步说明。 +设置 API 密钥、在 `agent.config.json` 中配置钱包、启动仪表盘，以及容器部署方案，请查看 [KaleidoAgent 页面](/cn/ai-tools/kaleido-agent#run-it)。 -## KaleidoMind +## KaleidoMind {#kaleidomind} KaleidoMind 是嵌入宿主应用中的引擎，而不是一个独立安装的程序。 @@ -86,3 +86,5 @@ npx tsx src/index.ts skills # 列出已安装的 Skills ```bash pnpm play "pay bob 3 eur" ``` + +分层漏斗如何路由一次请求、跨传输方式共享的工具契约、引擎加载的 skills，以及它在桌面、手机和配对设备上的运行方式，请查看 [KaleidoMind 页面](/cn/ai-tools/kaleido-mind)。 diff --git a/mintlify-docs/cn/ai-tools/introduction.mdx b/mintlify-docs/cn/ai-tools/introduction.mdx index 2cb69bf..3e88265 100644 --- a/mintlify-docs/cn/ai-tools/introduction.mdx +++ b/mintlify-docs/cn/ai-tools/introduction.mdx @@ -25,9 +25,9 @@ KaleidoSwap 通过开源软件，把交换、钱包和节点基础设施开放 - + 这里的每一种接入方式都会使用真实的 BIP-39 助记词签名，或直接驱动一个运行中的节点。请参阅[安装](/cn/ai-tools/installation)，了解如何把测试种子与主网种子分开保管。 - + ## 我该选哪一个？ diff --git a/mintlify-docs/cn/ai-tools/kaleido-agent.mdx b/mintlify-docs/cn/ai-tools/kaleido-agent.mdx index 6afd7ed..6f555ba 100644 --- a/mintlify-docs/cn/ai-tools/kaleido-agent.mdx +++ b/mintlify-docs/cn/ai-tools/kaleido-agent.mdx @@ -8,9 +8,9 @@ description: "运行一个非托管的自主代理：用原子交换再平衡比 它管理闪电与 RGB 钱包、在 KaleidoSwap DEX 上执行原子 HTLC 交换、运行投资组合再平衡与 DCA 策略、维持闪电通道流动性健康，同时还能作为交互式的钱包助手聊天使用 —— 所有这些都由一个 LLM（Claude 或 OpenAI）基于 [KaleidoCLI](/cn/cli/introduction) 和 MCP 工具调用进行推理来驱动。 - + KaleidoAgent 是一个独立的常驻服务。它目前**没有**嵌入 [KaleidoMind](/cn/ai-tools/kaleido-mind) 的 `Engine`，而是运行自己的代理循环。关于正在考虑的收敛路径，请见 [KaleidoMind 的关系说明](/cn/ai-tools/kaleido-mind#relationship-to-kaleidoagent)。 - + ## 能力 @@ -74,7 +74,7 @@ KaleidoAgent 把 `kaleido-mcp`（[统一的 MCP 服务器](/cn/ai-tools/mcp-serv 每个循环都由一个 [skill](/cn/ai-tools/skills) 驱动。 -## 风险控制 +## 风险控制 {#risk-controls} 风险上限位于 `agent.config.json` 的 `portfolio` 之下。每笔交换提交之前都会校验它们。 @@ -109,7 +109,7 @@ KaleidoAgent 把 `kaleido-mcp`（[统一的 MCP 服务器](/cn/ai-tools/mcp-serv ## 运行起来 {#run-it} -前置条件：Node.js 20 或更高版本、位于 `$PATH` 中的 [KaleidoCLI](/cn/cli/getting-started)、[Nanobot](https://nanobot.dev) 运行时，以及一个 Anthropic 或 OpenAI API 密钥。 +前置条件：Node.js 20 或更高版本、位于 `$PATH` 中的 [KaleidoCLI](/cn/cli/installation)、[Nanobot](https://nanobot.dev) 运行时，以及一个 Anthropic 或 OpenAI API 密钥。 @@ -158,6 +158,36 @@ docker compose --env-file .env.container -f docker-compose.container.yml up -d `agent.config.json` 中保存着真实的 BIP-39 助记词。请先在测试网络上起步，在配置验证通过之前保持 `dry_run` 开启，并且永远不要提交或分享这个文件。 +## 首次运行 {#first-run} + +代理跑起来之后，先手动触发一轮循环、读清楚它的决策，再让它真正开始交易。 + + + + `agent.config.json` 中的 `portfolio.dry_run` 默认为 `true`。先别动它。代理会完成推理、决策并汇报一笔交易，但不会真正提交。 + + + + 不必等定时任务，可以直接让[状态 API](#status-api) 跑一轮： + + ```bash + curl -X POST http://localhost:4242/run \ + -H 'Content-Type: application/json' \ + -d '{"task_id":"rebalance"}' + ``` + + 然后读取 `GET /status`，查看它的决策、它看到的余额，以及 token 开销。如果你启动了仪表盘，`http://localhost:5173` 上会显示同一轮运行。 + + + + 确认 `max_swap_usd`、`min_btc_reserve_sats` 和 `stop_loss_btc_sats` 与你在测试网络上能接受的损失相符。每笔交换提交之前都会校验这些参数，见上面的[风险控制](#risk-controls)。 + + + + 当连续几轮的 dry-run 决策都看起来正确后，再把 `portfolio.dry_run` 设为 `false`。 + + + ## 状态 API {#status-api} 代理在端口 `4242` 上提供一个仅限本机访问的控制 API，供仪表盘使用，也可以直接调用。 diff --git a/mintlify-docs/cn/ai-tools/kaleido-mind.mdx b/mintlify-docs/cn/ai-tools/kaleido-mind.mdx index 3473fed..78e904e 100644 --- a/mintlify-docs/cn/ai-tools/kaleido-mind.mdx +++ b/mintlify-docs/cn/ai-tools/kaleido-mind.mdx @@ -8,9 +8,9 @@ description: "驱动 KaleidoSwap 代理式钱包的本地端推理引擎：分 它的设计出发点是一个硬性约束：本地端的小模型在多步规划上既慢又不可靠。KaleidoMind 索性不让它们做这件事。 - + KaleidoMind 不会独立运行，它是一个由宿主嵌入的库：[Rate 移动钱包](https://github.com/kaleidoswap/Rate)（React Native，完全本地端 QVAC）、[桌面应用](/cn/desktop-app/getting-started/introduction)的 Tauri sidecar，或者一套评测与基准测试框架。**[KaleidoAgent](/cn/ai-tools/kaleido-agent) 目前并未使用这个库**，它有自己独立的代理循环。详见下文[与 KaleidoAgent 的关系](#relationship-to-kaleidoagent)。 - + ## 分层漏斗 diff --git a/mintlify-docs/cn/ai-tools/mcp-servers.mdx b/mintlify-docs/cn/ai-tools/mcp-servers.mdx index e2f5d8a..b33111d 100644 --- a/mintlify-docs/cn/ai-tools/mcp-servers.mdx +++ b/mintlify-docs/cn/ai-tools/mcp-servers.mdx @@ -281,6 +281,58 @@ PORT=3010 WDK_SEED="word1 word2 ..." node dist/index.js ``` +## 首次运行 {#first-run} + +顺序是先只读，再报价，最后执行 —— 因为除第一步之外，每一步都会动用真实价值。 + + + + 把 `kaleido-mcp` 配置块加入你的 MCP 宿主配置，将 `KALEIDOSWAP_API_URL` 指向测试环境，并把 `SPARK_NETWORK` 设为 `REGTEST`。完整 JSON 见上面的[客户端配置](#client-configuration)。 + + + + MCP 宿主只在启动时读取配置。已经在运行的客户端不会自动识别新服务器，必须重启。 + + + + 先从不会动用资金的操作开始。请求行情数据，它既不需要种子也不需要节点： + + ``` + What is the current Bitcoin price and the Fear and Greed index? + ``` + + 这会触发 `l402_get_price` 和 `l402_get_sentiment`。只要有回答，连接就是通的。 + + + + 接着确认钱包工具能正常解析： + + ``` + Show me my Spark balance and my Spark address. + ``` + + 这会调用 `spark_get_balance` 和 `spark_get_address`。这一步报错说明是种子或网络问题，而不是连接问题。 + + + + 只询价，不下单： + + ``` + Quote 100000 sats of BTC into USDT. Do not place an order. + ``` + + `kaleidoswap_get_quote` 会返回一个 `rfq_id`、原始数量、费用和过期时间。请仔细核对原始数量：它们以资产的最小单位计价，不是显示单位。 + + + + 一笔原子交换需要 DEX 工具和钱包工具配合，并且节点必须在通道中持有该资产。下面的[跨服务器调用顺序](#atomic-swap-across-servers)按顺序列出了每一次调用。 + + + + + 通用 MCP 宿主是保护最弱的一条路径。`kaleido-mcp` 不编码确认标志，所以如果你的客户端自动批准工具调用，LLM 就能不经询问地从配置的钱包中花钱。在完全弄清客户端如何处理批准之前，请只使用测试网络种子。 + + ## 跨服务器的原子交换 {#atomic-swap-across-servers} 一笔原子交换需要 DEX 工具和钱包工具配合。`kaleido-mcp` 用它的 `kaleidoswap_*` 工具与做市方通信，并用 `wdk_*` 工具驱动接单方节点。任何一步都不涉及托管，HTLC 在闪电网络上结算。 diff --git a/mintlify-docs/cn/ai-tools/troubleshooting.mdx b/mintlify-docs/cn/ai-tools/troubleshooting.mdx index 99ae5a7..919e000 100644 --- a/mintlify-docs/cn/ai-tools/troubleshooting.mdx +++ b/mintlify-docs/cn/ai-tools/troubleshooting.mdx @@ -91,7 +91,7 @@ description: "解决 KaleidoSwap AI 工具的常见问题：MCP 连接失败、 **解决办法**： 1. 确认它能被解析：`kaleido --version` 2. 在服务器或代理配置中把 `KALEIDO_BIN` 设为该可执行文件的绝对路径。 - 3. 如果尚未安装，请按 [CLI 快速上手](/cn/cli/getting-started)安装。 + 3. 如果尚未安装，请按 [CLI 安装](/cn/cli/installation)安装。 @@ -196,7 +196,9 @@ description: "解决 KaleidoSwap AI 工具的常见问题：MCP 连接失败、 ## 获取帮助 -如果遇到的是疑问而不是报错，请查看[常见问题](/cn/ai-tools/faq)。其他情况请通过下面任一渠道反馈问题，并附上： +如果遇到的是疑问而不是报错，请查看[常见问题](/cn/ai-tools/faq)；上游文档与相关链接见[更多资源](/cn/ai-tools/additional-resources)。 + +其他情况请通过下面任一渠道反馈问题，并附上： 1. 使用的接入方式与版本（MCP 服务器名称、KaleidoAgent 提交号，或桌面应用版本） 2. 你所在的网络（regtest、signet 或主网） diff --git a/mintlify-docs/cn/api-reference/additional-resources.mdx b/mintlify-docs/cn/api-reference/additional-resources.mdx new file mode 100644 index 0000000..57df854 --- /dev/null +++ b/mintlify-docs/cn/api-reference/additional-resources.mdx @@ -0,0 +1,111 @@ +--- +title: "比特币交换 API：更多资源" +sidebarTitle: "更多资源" +description: "面向 KaleidoSwap API 集成方的链接汇总：OpenAPI 规范、SDK 与命令行工具、节点与协议参考、测试网络以及支持渠道。" +--- + +## 规范与客户端 + + + + KaleidoSwap API 的带版本规范，每次发布时更新。直接对比两个版本，而不是在运行时才发现变化。 + + + + 由这些规范生成的类型化客户端，把 Maker API 和你的节点分别封装在 `client.maker.*` 与 `client.rln.*` 之后。 + + + + 从终端驱动节点、取报价、做交换 —— 在动手写客户端之前手动摸清 API 的好办法。 + + + + 基础 URL、认证、请求格式、版本管理与速率限制。 + + + +## 协议参考 + + + + 完整的原子 HTLC 流程，附时序图以及每一步所用的接口端点。 + + + + 提供 RLN API 并负责把 swapstring 加入白名单的节点。这是 KaleidoSwap 的分支；[上游项目](https://github.com/RGB-Tools/rgb-lightning-node)由 RGB Tools 维护。 + + + + 我们的[通道订单接口端点](/cn/api-reference/rgb-lsps1-apis)所实现的 Channel Requests 规范，并在此基础上扩展了 RGB 资产分配。 + + + + 客户端校验、资产接口，以及 API 返回的 `rgb:` 合约 ID 背后的规范本身。 + + + +## 环境与测试 + +上主网之前请先在 signet 上集成。目前无需 API 密钥，匿名请求仍会被正常处理。 + +| 环境 | 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}`（即将推出） | + +资产 ID 在不同环境之间不通用 —— 请从 `GET /api/v1/market/assets` 读取，并按环境区分配置。 + + + + 获取 signet 比特币，用于给节点充值和开通测试通道。 + + + + 在链上确认交换是否已结算、通道开启是否已确认。 + + + + 交换接口端点所需的 RGB Lightning Node 的部署方案。 + + + +## 相关文档 + + + + 三种错误信封、状态码语义、重试策略，以及每种症状对应的修复方法。 + + + + 原子交换流程的端到端代码 —— 如果你更愿意读能跑的代码而不是接口表格。 + + + + 做市方、LSP 和你的节点各自处在什么位置。 + + + + RFQ、swapstring、HTLC、层，以及这些接口端点默认你已经知道的其他术语。 + + + +## 获取帮助 + +如果遇到的是报错，请查阅[故障排查](/cn/api-reference/troubleshooting)；如果是疑问，请看[常见问题](/cn/api-reference/faq)。 + +其他情况请从下面的渠道中选择一个反馈问题，并附上： + +1. 请求 URL 与 HTTP 方法 +2. 请求负载（请隐去 API 密钥） +3. 完整的错误响应，包含 `request_id` +4. 请求的时间戳 +5. 运行环境（signet / 主网） + + + + 向社群提问。 + + + 紧急问题的直接支持渠道。 + + diff --git a/mintlify-docs/cn/api-reference/error-handling.mdx b/mintlify-docs/cn/api-reference/error-handling.mdx deleted file mode 100644 index ae29048..0000000 --- a/mintlify-docs/cn/api-reference/error-handling.mdx +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: "交换 API 错误处理" -sidebarTitle: "错误处理" -description: "了解 KaleidoSwap API 如何报告错误：HTTP 状态码、错误响应格式，以及构建高可用集成的处理策略与重试建议。" ---- - -KaleidoSwap API 使用标准 HTTP 状态码和详细的错误信息来传达 API 请求的结果。本节概述常见错误类型以及有效的处理方式。 - ---- - -## HTTP 状态码 - -### 2xx：成功 -- **200 OK**：请求成功，服务器返回了预期的响应。 - -### 4xx：客户端错误 -这类错误表示客户端请求存在问题： -- **400 Bad Request**：请求格式错误或包含无效参数。 -- **401 Unauthorized**：Bearer API 密钥缺失或无效（在 API 密钥强制校验开启后返回）。 -- **403 Forbidden**：客户端无权访问所请求的资源。 -- **404 Not Found**：找不到所请求的资源。 -- **429 Too Many Requests**：客户端已超出允许的速率限制。 - -### 5xx：服务器错误 -这类错误表示服务端存在问题： -- **500 Internal Server Error**：服务器发生了意外错误。 -- **502 Bad Gateway**：服务器从上游服务器收到了无效响应。 -- **503 Service Unavailable**：服务暂时不可用，可能因维护或过载导致。 - ---- - -## 错误响应格式 - -API 会根据请求失败的位置返回**三种不同的错误信封**。 - -### 应用错误 - -业务与应用错误（参数无效、资源缺失、冲突、速率限制、服务器错误）返回结构化信封： - -```json -{ - "error_code": "PAIR_NOT_FOUND", - "message": "Trading pair not found: BTC/USDT", - "details": {}, - "request_id": "req_01HV8Q9X7G0Q7Y3Z" -} -``` - -- `error_code`（`string`）：稳定的、机器可读的错误码（例如 `PAIR_NOT_FOUND`、`VALIDATION_ERROR`、`NOT_FOUND`、`RATE_LIMIT_EXCEEDED`、`INTERNAL_ERROR`）。 -- `message`（`string`）：错误的可读描述。 -- `details`（`object`）：关于该错误的可选结构化上下文（可能为空）。 -- `request_id`（`string`）：请求关联标识符 —— 联系支持团队时请一并提供。 - -### 请求校验错误（HTTP 422） - -在到达应用逻辑*之前*就未通过 schema 校验的请求，会返回 FastAPI 的校验信封，HTTP 状态码为 `422`： - -```json -{ - "detail": [ - { - "loc": ["body", "rfq_id"], - "msg": "Field required", - "type": "missing" - } - ] -} -``` - -- `detail`（`array`）：每个校验失败对应一个条目。 - - `loc`（`array<(string | integer)>`）：出错字段的路径。 - - `msg`（`string`）：校验错误信息。 - - `type`（`string`）：FastAPI/Pydantic 校验错误类型。 - -### 遗留错误 - -少数接口端点的部分 `400` 响应仍是一个裸的 detail 对象，**不含** `error_code` 或 `request_id` —— 例如 `POST /market/quote` 上不受支持的路由，或 `GET /market/pairs` 上格式错误的 `pair_ticker` 过滤条件： - -```json -{ - "detail": "Route not supported for this pair. From: BTC_LN, To: RGB_LN" -} -``` - -- `detail`（`string`）：错误的可读描述。 - -处理 `400` 响应的客户端应同时兼容结构化信封和这种遗留形式。 - ---- - -## 常见错误 -以下是一些典型错误及其解决办法： - -### 400 Bad Request -- **原因**：请求中参数缺失或无效。 -- **解决办法**：核对请求载荷，确保所有必填字段都已提供且数据有效。 - -### 404 Not Found -- **原因**：请求的接口端点或资源不存在。 -- **解决办法**：检查接口端点 URL 和资源标识符。 - -### 429 Too Many Requests -- **原因**：客户端在短时间内发送了过多请求。 -- **解决办法**：在客户端应用中实现速率限制，并在指定的等待时间（如有提供）后重试。 - -### 500 Internal Server Error -- **原因**：服务器发生了意外错误。 -- **解决办法**：稍后重试请求。如果问题持续存在，请携带请求详情联系支持团队。 - ---- - -## WebSocket 错误处理 -对于 WebSocket 连接，错误以 JSON 消息形式传达。如果发生严重错误，服务器可能会关闭连接。 - -### 重连策略 -如果 WebSocket 连接意外关闭： - -1. 等待数秒（例如 5-10 秒）。 -2. 重新建立连接。 -3. 重新发送所有待处理的 `quote_request` 消息，以获取最新报价。 - ---- - -### 调试建议 -1. **查看日志**：监控应用日志，获取失败请求的详细信息。 -2. **校验输入**：确保所有请求参数和载荷都符合 API 要求。 -3. **联系支持**：对于持续出现或原因不明的错误，请提供以下信息： - - 请求 URL - - HTTP 方法 - - 请求载荷 - - 错误发生的时间戳 - - API 返回的完整错误响应 - ---- - -## 最佳实践 -1. **优雅处理错误**：在应用中实现完善的错误处理逻辑，避免崩溃或影响用户体验。 -2. **速率限制**：遵守 API 速率限制，避免出现 `429 Too Many Requests` 错误。 -3. **重试机制**：对于瞬时错误（例如 500 Internal Server Error），请实现带指数退避的重试机制。 - ---- - -关于错误码和故障排查的更多细节，请参阅 API 文档。 diff --git a/mintlify-docs/cn/api-reference/faq.mdx b/mintlify-docs/cn/api-reference/faq.mdx new file mode 100644 index 0000000..f20ecab --- /dev/null +++ b/mintlify-docs/cn/api-reference/faq.mdx @@ -0,0 +1,124 @@ +--- +title: "比特币交换 API 常见问题" +sidebarTitle: "常见问题" +description: "关于 KaleidoSwap 交换 API 的常见问题：认证、Maker API 与节点 API 的区别、金额单位、报价有效期、WebSocket 报价以及浏览器端调用。" +--- + +## 常见问题 + + + + **目前不需要。** 所有 Maker API 接口端点仍然接受匿名请求，因此你可以立即开始集成。Bearer 密钥（`Authorization: Bearer `）目前已被**接受并记录归属** —— 密钥携带作用域，例如市场数据与报价用的 `quote:read`，以及交换发起与执行用的 `swap:execute`。 + + 强制校验正在逐步上线。一旦开启，缺失或无效的密钥将返回 `401`，所以请现在就开始发送密钥，而不是事后补上。详见[总览](/cn/api-reference/introduction#authentication)。 + + + + 它们是两台不同的服务器，其中只有一台是我们的。 + + | API | 部署位置 | 覆盖范围 | + |-----|----------------|--------| + | **Maker API** | `https://api.signet.kaleidoswap.com/api/v1` | 市场数据、报价、交换的发起/执行/状态、LSPS1 通道订单 | + | **RLN API** | **你自己**节点的根路径，例如 `http://:3001/` | 钱包与 RGB 资产、通道、发票、交换白名单 | + + 本标签页「接口端点」下记录的全部内容都属于 Maker API。RLN API 由你自己运行的 [RGB Lightning Node](https://github.com/kaleidoswap/rgb-lightning-node) 提供 —— 不存在由 KaleidoSwap 托管的 RLN 地址可供调用。[总览](/cn/api-reference/introduction)中的表格把每个目标对应到正确的 API。 + + + + **只取市场数据的话，不需要。** 资产、交易对、路由和报价都是对做市方的普通 HTTP 调用。 + + **做原子交换的话，需要。** 白名单 `swapstring` 和路由 HTLC 都发生在你的节点上。这正是做市方永远不托管资金的原因 —— 协议中没有任何一步让它持有你的资金。部署方式见[节点托管](/cn/desktop-app/getting-started/node-hosting)。 + + + + signet（MutinyNet）目前已上线；主网即将推出。 + + | 环境 | 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}`（即将推出） | + + 接口端点页面上的交互式演练场运行在 signet。 + + + + **BTC 一侧使用毫聪（msat）。** `POST /api/v1/swaps/init` 明确说明了这一点，报价示例也遵循同样的约定：BTC 一侧的 `1000000` 表示 1,000 聪。 + + **RGB 资产一侧使用原始最小单位**，由该资产自身的 `precision` 决定，可从 `GET /api/v1/market/assets` 获取。精度因资产而异 —— USDT 的精度为 `6`，因此 `1000000` 表示 1.00 USDT。 + + 不要硬编码换算系数。逐个资产读取 `precision`，并把 `precision` 当作展示用的元数据，而不是你所发送金额的单位。 + + + + `price` 是**一个完整单位**的 `from_asset` 的价格，以 `to_asset` 的**最小单位**表示。它不是展示用价格，也不是你将收到的金额。 + + 你实际会收到的金额已经在响应的资产一侧给出 —— `to_asset.amount` —— 并且已经把手续费计入其中。面向用户的展示请使用它；只有在你确实需要汇率本身时才用 `price`。 + + + + 到它的 `expires_at`（unix 时间）为止 —— 这是一个很短的窗口，以数十秒计。一个报价对应一次 `POST /api/v1/swaps/init`。 + + 不要让 `rfq_id` 跨越用户思考的时间。先取报价，然后迅速完成发起、白名单和执行；如果用户停在某个确认界面上，等他继续时再请求一个新报价。 + + + + 都可以 —— 两者返回的报价结构相同。 + + WebSocket 是**请求/响应式的，不是发布/订阅式的**：你发送一条 `quote_request`，服务器回复这一条消息。它没有订阅机制，所以只有不断询问，价格才会保持新鲜。请定期发送 `ping` 消息以维持连接健康。 + + 当你要展示不断变化的价格、又想避免每次请求的 HTTP 开销时，用 WebSocket；一次性的交换用 `POST /api/v1/market/quote` 即可。参见[交换协议](/cn/api-reference/swap-protocol)。 + + + + `/swaps/init` 返回的 `swapstring` 编码了这笔交换的确切条款 —— 两侧金额、两侧资产以及 payment hash。在你自己的节点上把它加入白名单，就是**你**对这些确切条款的授权。 + + 这是该协议非托管性的关键：做市方无法转移你的资产，它只能提供一个你的节点已经同意履行的 HTLC。白名单是通过你 RGB Lightning Node 的 `/taker` API 完成的，而不是通过 Maker API。 + + + + `access_token` 是单笔交换的凭证，**只在发起时返回一次**。你需要它连同 `payment_hash` 一起去轮询 `POST /api/v1/swaps/atomic/status`。 + + 没有它，状态接口会返回统一的 `404 Swap not found` —— 这是刻意设计的，这样该接口就无法被用来探测别人的 payment hash。发起返回的那一刻就把 token 和 payment hash 一起持久化。LSPS1 通道订单同理：`create_order` 会返回单笔订单的 `access_token`，`get_order` 和 `rate_decision` 都需要它。 + + + + 不可靠。大多数 Maker API 接口端点关闭了 CORS，因此纯浏览器应用需要自己的后端来代理调用。无论如何都要把 API 密钥保留在服务端 —— 一旦强制校验开启，发到浏览器的密钥就等于公开的密钥。 + + + + 默认值为：单 IP 每分钟 600 次请求、单接口端点每分钟 300 次、全局每分钟 1,000 次。它们可按部署配置，因此请把这些数字视为起点而非承诺。 + + 每个响应都带有 `X-RateLimit-Limit`、`X-RateLimit-Remaining` 和 `X-RateLimit-Reset` —— 请读取它们，不要靠猜。资产和交易对请在本地缓存，它们很少变化。 + + + + 版本写在路径里：`v1`，例如 `https://api.signet.kaleidoswap.com/api/v1`。带版本的 OpenAPI 规范发布在[规范仓库](https://github.com/kaleidoswap/specs)中，并在每次发布时更新，因此你可以直接对比两个版本，而不是在运行时才发现变化。 + + + + 对大多数集成来说，是的。[TypeScript 和 Python SDK](/cn/sdk/introduction) 的类型由同一份 OpenAPI 规范生成，把 Maker API 和你的节点分别封装在 `client.maker.*` 与 `client.rln.*` 之后，并提供带重试提示的类型化错误层级。 + + 当你使用的语言尚无 SDK，或者你需要客户端所抽象掉的那部分控制权时，再直接调用 REST。此外还有一个[命令行工具](/cn/cli/introduction)，可以从终端驱动节点。 + + + +## 获取帮助 + +如果遇到的是报错而不是疑问，请查阅[故障排查](/cn/api-reference/troubleshooting)；规范与上游链接见[更多资源](/cn/api-reference/additional-resources)。 + +其他情况请从下面的渠道中选择一个反馈问题，并附上： + +1. 请求 URL 与 HTTP 方法 +2. 请求负载（请隐去 API 密钥） +3. 完整的错误响应，包含 `request_id` +4. 请求的时间戳 +5. 运行环境（signet / 主网） + + + + 向社群提问。 + + + 紧急问题的直接支持渠道。 + + diff --git a/mintlify-docs/cn/api-reference/getting-started.mdx b/mintlify-docs/cn/api-reference/getting-started.mdx index 95ef8e5..d7b6701 100644 --- a/mintlify-docs/cn/api-reference/getting-started.mdx +++ b/mintlify-docs/cn/api-reference/getting-started.mdx @@ -138,23 +138,4 @@ API 返回标准 HTTP 状态码来表示请求结果： - **400**：请求错误（例如参数无效） - **404**：资源不存在 - **500**：服务器内部错误 -关于错误处理的更多信息，见[错误处理](/cn/api-reference/error-handling)。 - ---- - -## 下一步 - - - - 在调用交换接口端点之前，先了解完整的接单方-做市方交换生命周期 - - - 获取资产、交易对和报价 - - - 创建并跟踪交换订单 - - - 订购通道并管理流动性 - - +完整的状态码列表、错误响应格式以及按症状排查的修复方法，见[故障排查](/cn/api-reference/troubleshooting)。 diff --git a/mintlify-docs/cn/api-reference/introduction.mdx b/mintlify-docs/cn/api-reference/introduction.mdx index 3a75b25..2ec5d8f 100644 --- a/mintlify-docs/cn/api-reference/introduction.mdx +++ b/mintlify-docs/cn/api-reference/introduction.mdx @@ -105,7 +105,7 @@ HTTP 状态码遵循标准约定： | `500` | 服务器内部错误 | | `503` | 服务不可用 —— 做市方或 LSP 节点暂时无法访问 | -完整的错误码列表见[错误处理](/cn/api-reference/error-handling)。 +完整的错误码列表以及每种故障的修复方法见[故障排查](/cn/api-reference/troubleshooting)。 --- @@ -117,14 +117,8 @@ HTTP 状态码遵循标准约定： ## 使用 SDK -除了直接调用 REST API，你也可以使用官方 KaleidoSDK 库，它们对这些接口端点做了封装，提供类型安全和便捷方法： +除了直接调用 REST API，你也可以使用官方 KaleidoSDK 库：它们对这些接口端点做了封装，在 TypeScript 和 Python 中都提供类型安全和便捷方法。 - - - 从 OpenAPI 规范自动生成的类型化客户端，提供 `client.maker.*` 和 `client.rln.*` 子客户端 - - - - 同步 Python 客户端，使用 Pydantic 模型，采用相同的子客户端架构 - - + + 由同一份 OpenAPI 规范生成的类型化客户端，提供 `client.maker.*` 和 `client.rln.*` 子客户端。 + diff --git a/mintlify-docs/cn/api-reference/market-apis.mdx b/mintlify-docs/cn/api-reference/market-apis.mdx index 074e9cc..ec658e3 100644 --- a/mintlify-docs/cn/api-reference/market-apis.mdx +++ b/mintlify-docs/cn/api-reference/market-apis.mdx @@ -386,7 +386,3 @@ description: 从 KaleidoSwap 做市方获取资产、交易对、路由与报价 - `expires_at` 字段表明该报价从何时起不再可用于发起交换。 - 费用已计入所计算出的腿数量中。 - 在过期之前，`rfq_id` 可用于后续的交换发起请求或 LSPS1 订单请求。 - ---- - -关于交换操作的更多细节，请继续阅读[交换 API](/cn/api-reference/swap-apis)。 diff --git a/mintlify-docs/cn/api-reference/rgb-lsps1-apis.mdx b/mintlify-docs/cn/api-reference/rgb-lsps1-apis.mdx index c43bb41..d68f60c 100644 --- a/mintlify-docs/cn/api-reference/rgb-lsps1-apis.mdx +++ b/mintlify-docs/cn/api-reference/rgb-lsps1-apis.mdx @@ -311,7 +311,3 @@ RGB LSPS1 API 让客户端能够向闪电服务提供商（LSP）订购带 RGB ``` 对不处于 `PENDING_RATE_DECISION` 状态的订单调用该接口端点会返回 `400` 错误。当申请退款并处理完成后，`refund_txid` 会携带链上交易 ID。 - ---- - -关于交易和市场操作的更多细节，请继续阅读[市场 API](/cn/api-reference/market-apis)。 diff --git a/mintlify-docs/cn/api-reference/swap-apis.mdx b/mintlify-docs/cn/api-reference/swap-apis.mdx index 3613d87..f566c34 100644 --- a/mintlify-docs/cn/api-reference/swap-apis.mdx +++ b/mintlify-docs/cn/api-reference/swap-apis.mdx @@ -293,7 +293,3 @@ description: 用于发起、执行和查询原子 HTLC 交换的接口端点 — - **`Succeeded`**：交换已成功完成。 - **`Expired`**：交换在要求的时间内未完成。 - **`Failed`**：交换遇到错误，未能成功完成。 - ---- - -错误详情请参阅[错误处理](/cn/api-reference/error-handling)。 diff --git a/mintlify-docs/cn/api-reference/swap-protocol.mdx b/mintlify-docs/cn/api-reference/swap-protocol.mdx index 20745e1..908826c 100644 --- a/mintlify-docs/cn/api-reference/swap-protocol.mdx +++ b/mintlify-docs/cn/api-reference/swap-protocol.mdx @@ -117,20 +117,3 @@ client.maker.enable_websocket("wss://api.signet.kaleidoswap.com/api/v1/market/ws # 完整的原子交换流程见 sdk/examples ``` - ---- - - - - 原子交换 init 与 execute 的接口端点 - - - 报价与市场数据的接口端点 - - - 原子交换流程的端到端代码示例 - - - 处理交换失败与边界情况 - - diff --git a/mintlify-docs/cn/api-reference/troubleshooting.mdx b/mintlify-docs/cn/api-reference/troubleshooting.mdx new file mode 100644 index 0000000..08c0043 --- /dev/null +++ b/mintlify-docs/cn/api-reference/troubleshooting.mdx @@ -0,0 +1,424 @@ +--- +title: "交换 API 错误与故障排查" +sidebarTitle: "故障排查" +description: "KaleidoSwap API 如何报告错误以及如何修复：三种错误信封、HTTP 状态码、按症状排查的解决方法以及重试策略。" +--- + +KaleidoSwap API 使用标准 HTTP 状态码和结构化错误响应体来报告请求结果。本页说明如何读懂一个错误、每个状态码的含义，以及集成方实际会遇到的那些故障该怎么修。如果是疑问而不是故障，请看[常见问题](/cn/api-reference/faq)。 + +--- + +## 错误响应格式 + +API 会根据请求在哪一环失败，返回**三种不同的错误信封**。能处理全部三种的客户端，就永远不需要靠猜。 + +### 应用错误 + +业务与应用错误（参数无效、资源缺失、冲突、速率限制、服务器错误）返回结构化信封： + +```json +{ + "error_code": "PAIR_NOT_FOUND", + "message": "Trading pair not found: BTC/USDT", + "details": {}, + "request_id": "req_01HV8Q9X7G0Q7Y3Z" +} +``` + +- `error_code`（`string`）：稳定的、机器可读的错误码（例如 `PAIR_NOT_FOUND`、`VALIDATION_ERROR`、`NOT_FOUND`、`RATE_LIMIT_EXCEEDED`、`INTERNAL_ERROR`）。 +- `message`（`string`）：人类可读的错误描述。 +- `details`（`object`）：关于该错误的可选结构化上下文（可能为空）。 +- `request_id`（`string`）：请求关联标识符 —— 联系支持时请附上。 + +请基于 `error_code` 分支判断，不要基于 `message`。错误码是稳定的，文案不是。 + +### 请求校验错误（HTTP 422） + +在进入应用逻辑*之前*就没通过 schema 校验的请求，会返回 FastAPI 的校验信封，HTTP 状态码为 `422`： + +```json +{ + "detail": [ + { + "loc": ["body", "rfq_id"], + "msg": "Field required", + "type": "missing" + } + ] +} +``` + +- `detail`（`array`）：每个校验失败项一条。 + - `loc`（`array<(string | integer)>`）：出错字段的路径。 + - `msg`（`string`）：校验错误信息。 + - `type`（`string`）：FastAPI/Pydantic 的校验错误类型。 + +### 遗留错误 + +少数接口端点的部分 `400` 响应仍是一个裸的 detail 对象，**不含** `error_code` 或 `request_id` —— 例如 `POST /market/quote` 上不受支持的路由，或 `GET /market/pairs` 上格式错误的 `pair_ticker` 过滤条件： + +```json +{ + "detail": "Route not supported for this pair. From: BTC_LN, To: RGB_LN" +} +``` + +- `detail`（`string`）：人类可读的错误描述。 + +处理 `400` 响应的客户端应同时兼容结构化信封和这种遗留结构。 + +--- + +## HTTP 状态码 + +| 状态码 | 含义 | 可重试？ | +|--------|---------|--------| +| `200` | 成功 —— 请求已完成并返回预期响应 | —— | +| `400` | 请求错误 —— 请求格式有误或参数无效 | 否，修正请求 | +| `401` | 未授权 —— Bearer API 密钥缺失或无效（开启强制校验后返回） | 否，附上有效密钥 | +| `403` | 禁止访问 —— 该密钥不允许从此来源使用 | 否 | +| `404` | 资源不存在 —— 接口端点或资源不存在 | 否 | +| `422` | 无法处理的实体 —— schema 校验失败 | 否，同样的负载永远失败 | +| `429` | 请求过多 —— 超出速率限制 | 是，退避之后 | +| `500` | 服务器内部错误 —— 服务端出现意外错误 | 是，带退避 | +| `502` | 网关错误 —— 服务器从上游服务器收到了无效响应 | 是，带退避 | +| `503` | 服务不可用 —— 做市方或 LSP 节点暂时无法访问，或正在维护/过载 | 是，带退避 | + +`4xx` 类表示请求本身需要修改；`5xx` 类表示请求没问题，是上游出了状况。只有 `5xx` 类加上 `429` 值得重试 —— 见[重试与健壮性](#retry-and-resilience)。 + +--- + +## 请求与认证 + + + + **现象：** 返回 `400`，响应体可能是 `error_code` 信封，也可能是一个裸的 `detail` 字符串 + + **原因：** 请求中的参数缺失或无效。 + + **解决方法：** + 1. 核对负载，确认每个必填字段都存在且取值合法 + 2. 让处理逻辑同时兼容**两种** `400` 结构 —— 有 `error_code` 就读它，否则回退到 `detail` + 3. 对于 `{"detail": "Route not supported for this pair..."}`，用 `POST /api/v1/market/pairs/routes` 查询该交易对实际支持的 `routes`，并发送其中出现过的 `from_asset.layer` → `to_asset.layer` 组合 + 4. 对于交易对过滤，`pair_ticker` 必须是 `BASE/QUOTE` 格式（例如 `BTC/USDT`），且单一交易对标识符之间互斥 + + + + **现象：** 原本正常的请求开始返回 `401`，或首次带密钥调用就返回 `401` + + **原因：** + - 你所在环境已开启 API 密钥强制校验，而请求未携带有效密钥 + - 请求头格式有误 —— 必须是 `Authorization: Bearer `，而不是裸 token + - 密钥缺少该接口端点所需的作用域（市场数据需要 `quote:read`，交换发起/执行需要 `swap:execute`） + + **解决方法：** + 1. 打印客户端实际发出的 `Authorization` 请求头，检查是否漏了 `Bearer ` 前缀或多了换行符 + 2. 如果调用的是交换发起或执行，确认密钥带有 `swap:execute` 而不只是 `quote:read` + 3. 确认密钥有效且未被吊销 + 4. 如果你还没有密钥：signet 上匿名访问仍然可用 —— 收到 `401` 说明强制校验对你已经生效 + + + + **现象：** 某个接口端点返回 `403`，而同一密钥在别处可用 + + **原因：** 密钥本身有效，但不允许从此来源使用。 + + **解决方法：** 换用允许的来源调用，或申请把该来源加入允许列表。当为后端签发的密钥被从浏览器或一台新的部署主机上使用时，就会遇到这种失败 —— 另见[常见问题](/cn/api-reference/faq)中关于 CORS 的说明。 + + + + **现象：** 返回 `422`，且 `detail` 是一个**数组**而不是 `error_code` + + **原因：** 请求在进入业务逻辑之前就没通过 schema 校验，因此没有产生业务错误。 + + **解决方法：** 读 `detail[].loc` —— 它就是出错字段的确切路径。`["body", "rfq_id"]` 配合 `"type": "missing"` 说明你完全没传 `rfq_id`；`"type"` 为 `int_parsing` 通常意味着金额被当作字符串发送了。不要把 `422` 当作可重试错误：同样的负载永远会失败。 + + + + **现象：** 返回 `PAIR_NOT_FOUND`、`NOT_FOUND`，或你确知受支持的 ticker 返回了空的 `assets` 数组 + + **原因：** + - 接口端点 URL 或某个资源标识符有误 + - 该资产或交易对处于非活跃状态，而 `GET /market/pairs` 默认只返回活跃交易对（`active_only=true`） + - 你用 `asset_id` 过滤，但做市方要求完全一致的 RGB 合约 ID，包括 `rgb:` 前缀 + - 你连到了错误的环境 —— 资产 ID 在 signet 和主网之间**不通用** + + **解决方法：** + 1. 检查接口端点路径和资源标识符，包括 `/api/v1` 前缀 + 2. 用 `active_only=false` 重新查询，看该交易对是否存在但被停用 + 3. 从 `GET /api/v1/market/assets` 动态发现 ID，不要硬编码，并按环境区分配置 + 4. 检查响应里的 `total` —— 它是全部匹配项的数量，因此 `total` 大于你的分页大小说明你看到的是分页，而不是「不存在」 + + + + **现象：** 返回 `RATE_LIMIT_EXCEEDED`，通常发生在轮询价格时 + + **原因：** 短时间内发送了过多请求。 + + **解决方法：** + 1. 读取 `X-RateLimit-Remaining` 和 `X-RateLimit-Reset`，在被切断之前就主动退避，而不是等 `429` 才反应 + 2. 如果响应给出了等待时间，请在该时间之后重试 + 3. 不要循环轮询 `POST /market/quote` —— 打开 WebSocket，在确实需要新价格时再发 `quote_request` + 4. 缓存 `market/assets` 和 `market/pairs`；两者都可安全缓存，且很少变化 + 5. 记住限制是**同时**按 IP、按接口端点和按全局计算的，所以同一 NAT 后面一个吵闹的邻居可能会吃掉你的额度 + + + + **现象：** 返回 `INTERNAL_ERROR`，或者一分钟前还正常的接口端点返回 `503` + + **原因：** + - `500` —— 服务端出现意外错误 + - `502` —— 从上游服务器收到了无效响应 + - `503` —— 做市方或 LSP 节点暂时无法访问、正在维护或已过载 + + 这几种都不表示你的请求格式有误。 + + **解决方法：** + 1. 使用带抖动的指数退避重试；这类失败属于瞬时故障 + 2. 超时后**不要**盲目重试 `/swaps/execute` —— 先轮询 `POST /api/v1/swaps/atomic/status`，确认这笔调用是否其实已经生效 + 3. 如果持续出现，请附上错误体中的 `request_id` 反馈给我们 + + + +--- + +## 报价与金额 + + + + **现象：** `/swaps/init` 拒绝了一个片刻之前还有效的 `rfq_id` + + **原因：** 报价的 `expires_at` 已过。这个窗口以数十秒计，不是数分钟。 + + **解决方法：** + 1. 尽可能晚地取报价 —— 紧贴发起之前，绝不要在用户可能久留的确认界面之前 + 2. 让发起 → 白名单 → 执行整条链路保持紧凑；它们全都基于同一个报价 + 3. 如果用户犹豫，丢弃这个 `rfq_id`，等他继续时再请求新报价 + + + + **现象：** 返回 `VALIDATION_ERROR`，或一个提到金额的 `400` + + **原因：** + - 低于该**层**的 `min_amount` 或高于 `max_amount` —— 这些限制按层存放在每个资产的 `endpoints` 数组里，而不在资产本身上 + - 发送了展示单位而不是原始单位 + - 两侧都填了金额，或两侧都没填 + + **解决方法：** + 1. 从你所路由的那一层对应的 `endpoints` 条目中读取限制 + 2. BTC 一侧用毫聪，RGB 一侧用该资产 `precision` 对应的原始单位 —— 见[常见问题](/cn/api-reference/faq) + 3. `from_asset.amount`（正向报价）和 `to_asset.amount`（反向报价）中恰好填一个 + + + + **现象：** 报价在算术上「不对」，差了 1,000 倍或 1 亿倍 + + **原因：** + - BTC 一侧被当作聪处理，而 API 指的是毫聪 + - 把一个资产的精度用在了另一个资产上 —— 精度是按资产定义的，BTC 和 USDT 并不共用一个 + - 把 `price` 当成了展示汇率；它是一个完整单位的 `from_asset` 以 `to_asset` 最小单位表示的价格 + + **解决方法：** + 1. 展示响应中的 `to_asset.amount` —— 手续费已经计入其中 —— 而不要用 `price` 反算 + 2. 从 `GET /api/v1/market/assets` 逐个资产读取 `precision`，绝不硬编码换算系数 + 3. 在把换算逻辑接入界面之前，先在 signet 上用一笔小额报价做一次往返验证 + + + +--- + +## 交换 + + + + **现象：** `init` 返回了 `swapstring`，但 `execute` 失败 + + **原因：** 这个 `swapstring` 从未在你自己的节点上加入白名单，因此接单方一侧无法履行 HTLC。这是最常见的集成故障，因为中间那一步并不是 Maker API 调用。 + + **解决方法：** 三个步骤必须按顺序执行，且分布在两台不同的服务器上： + + 1. 在 **Maker API** 上调用 `POST /api/v1/swaps/init` → 返回 `swapstring`、`payment_hash`、`access_token` + 2. 通过**你自己的 RGB Lightning Node** 的 `/taker` API 把 `swapstring` 加入白名单 + 3. 在 **Maker API** 上调用 `POST /api/v1/swaps/execute`，带上 `swapstring`、`taker_pubkey` 和 `payment_hash` + + 同时确认 `taker_pubkey` 是你节点的 pubkey，且 `payment_hash` 与发起时返回的一致。参见[交换协议](/cn/api-reference/swap-protocol)。 + + + + **现象：** 对一笔你确知存在的交换，`POST /api/v1/swaps/atomic/status` 返回 `404` + + **原因：** `access_token` 缺失或无效。这个 `404` 是刻意统一的 —— 它不区分「token 错误」和「不存在这笔交换」，这样该接口就无法被用来探测 payment hash。 + + **解决方法：** + 1. 同时发送 `payment_hash` **和** `/swaps/init` 返回的 `access_token` + 2. 如果 token 当时没有保存下来，它无法找回 —— 它只返回一次。请在发起时就把它和 payment hash 一起存好 + 3. 确认你轮询的环境与这笔交换创建时所在的环境一致 + + + + **现象：** `execute` 返回了 `200`，但状态一直是 `Pending`，资产也没到账 + + **原因：** + - HTLC 还在途中 —— `execute` 返回并不等于结算完成 + - 资产一侧没有容量足够的路由 + - 你节点上待处理的 RGB 转账尚未推进 + + **解决方法：** + 1. 继续轮询 `/swaps/atomic/status`；终态是 `Succeeded`、`Expired` 和 `Failed` + 2. 在你的节点上刷新转账，并检查该资产的出向容量 —— 不要只看总余额 + 3. 用交换对象上的 `expires_at` 与当前时间对比，判断 HTLC 还剩多少时间 + + + + **现象：** 状态变为 `Expired` 或 `Failed` + + **原因：** + - `Expired` —— 双方完成之前 HTLC 超时已过，通常是白名单或执行来得太晚 + - `Failed` —— HTLC 无法路由或结算，通常是容量或流动性问题 + + **解决方法：** + 1. 你的资金没有风险：未完成的原子交换会自动把双方资金退回。不要手动重新打款 + 2. 用**新的报价**重试 —— 旧的 `rfq_id` 和 `swapstring` 已经作废 + 3. 如果同一交易对反复失败，检查该资产通道上的容量，并通过 [LSPS1](/cn/api-reference/rgb-lsps1-apis) 订购更多流动性 + + + +--- + +## WebSocket + +WebSocket 的错误不是 HTTP 响应 —— 它们以 JSON 消息的形式抵达已打开的连接；遇到严重错误时，服务器可能直接关闭连接。 + + + + **现象：** 连接已打开、`quote_request` 已发出，但没有 `quote_response` 返回 + + **原因：** 请求失败了。失败会以带 `error` 字段的消息返回，而不是 `quote_response`，因此只监听 `quote_response` 的客户端看到的就是「一片安静」。 + + **解决方法：** + 1. 打印所有入站帧，而不只是你期待的那些，并处理 `error` 结构 + 2. 检查常见原因：未知资产、该交易对不支持的路由、超出按层限制的金额 + 3. 确认 `from_amount` / `to_amount` 中恰好设置了一个 + + + + **现象：** 第一条报价到了，之后就再没有变化 + + **原因：** 这个协议是请求/响应式的 —— 没有订阅机制。服务器只回答你发出的那条消息，不会主动推送更新。 + + **解决方法：** 每当你需要当前价格时就发一条新的 `quote_request`，由你自己的定时器或用户操作来驱动。 + + + + **现象：** 连接意外关闭，有时发生在流程中途 + + **重连策略** —— 当连接意外关闭时： + + 1. 等待几秒（5–10 秒） + 2. 重新建立连接 + 3. 重新发送所有待处理的 `quote_request` 以获取新报价 —— 报价不会跨越重连留存 + + **另外检查：** + - 定期发送 `ping` 并期待 `pong`；经过代理的空闲连接就是一条即将被关闭的连接 + - 每个会话使用一个新的唯一 `{client_id}`，并确认 URL 是 `wss://` 而不是 `ws://` + - 如果你处在会剥离 WebSocket 升级的企业代理之后，请退回到 `POST /market/quote` + + + +--- + +## 通道订单（LSPS1） + + + + **现象：** 一旦带上 `client_asset_amount`，调用就失败 + + **原因：** 当 `client_asset_amount > 0` 时，客户端是在*购买*资产，因此需要一个来自 `POST /api/v1/market/quote` 的新鲜 `rfq_id` 来定价。 + + **解决方法：** + 1. 先取报价，再把这个 `rfq_id` 传给 `estimate_fees` / `create_order` + 2. 如果报价在两次调用之间过期了，重新取一次 + 3. 如果你只想要 LSP 一侧的流动性，就完全不要传 `client_asset_amount` —— 那种情况下不需要报价 + + + + **现象：** `create_order` 在余额或资产数量上校验失败 + + **原因：** 请求超出了 LSP 公布的限制。 + + **解决方法：** + 1. 读取 `GET /api/v1/lsps1/get_info` 返回的 `options`，把参数控制在 `min_channel_balance_sat` / `max_channel_balance_sat`、初始余额上下界以及 `max_channel_expiry_blocks` 之内 + 2. 检查同一响应中按资产给出的上限 —— `min_initial_lsp_amount` / `max_initial_lsp_amount` 是按资产定义的，且可能为 `0`，那表示该资产不支持这一侧 + 3. 下单之前先连接 `lsp_connection_url` 对应的 peer，这样通道才有地方开 + + + + **现象：** 通道始终没有开通，而 `order_state` 是 `PENDING_RATE_DECISION` + + **原因：** 付款结算之前市场汇率出现了明显变动，因此 LSP 暂停了订单，而不是按过时价格开通通道。它在等你决定。 + + **解决方法：** 调用 `POST /api/v1/lsps1/rate_decision`，带上 `order_id`、该订单的 `access_token` 和 `accept_new_rate` —— `true` 表示按当前汇率继续，`false` 表示触发退款到 `refund_onchain_address`。退款会返回 `refund_txid`。对处于其他状态的订单调用该接口会返回 `400`。 + + + + **现象：** 你无法读回自己创建的订单 + + **原因：** 与交换不同，这两种情况是可区分的 —— `access_token` 无效返回 `400`，`order_id` 不存在返回 `404`。 + + **解决方法：** 把 `create_order` 返回的 `access_token` 和 `order_id` 一起保存；它只在创建时返回，而 `get_order` 和 `rate_decision` 都需要它。如果想要一层兜底提醒，可以在下单时设置 `email`。 + + + + **现象：** 付款已结算，`order_state` 为 `CHANNEL_OPENING` + + **解决方法：** + 1. 继续轮询 `get_order` —— 它可以安全轮询，且在通道存在之前 `channel` 一直是 `null` + 2. 用 `GET /api/v1/lsps1/network_info` 返回的当前高度与 `required_channel_confirmations` 对比 + 3. 注意付款的过期时间在 `payment.bolt11.expires_at` 和 `payment.onchain.expires_at` 下，通道自身的过期时间在 `channel.expires_at` 下 —— 顶层没有 `expires_at` 可读 + + + +--- + +## 重试与健壮性 {#retry-and-resilience} + +把客户端设计成「坏响应是一种已处理的情况」，而不是一次崩溃。 + +1. **优雅地处理错误。** 解析全部三种信封，基于 `error_code` 分支判断，并给出可操作的提示，而不是把原始故障直接抛给用户。 +2. **只重试值得重试的。** 瞬时故障 —— `500`、`502`、`503` 和 `429` —— 值得再试一次，请使用**带抖动的指数退避**。客户端错误（`400`、`401`、`403`、`404`、`422`）无论发多少次，结果都一样。 +3. **尊重速率限制。** 读取 `X-RateLimit-*` 请求头，主动待在上限之内，而不是靠撞上限来发现它。缓存资产、交易对之类的静态数据。 +4. **把交换执行当作非幂等操作。** `/swaps/execute` 超时并不能证明它失败了 —— 在重新发送任何东西之前，先轮询 `/swaps/atomic/status`。 +5. **限制总重试次数。** 面对 `503` 的无限重试循环，会变成你对自己发起的拒绝服务。 + +--- + +## 反馈之前 + +一份可复现的报告通常一个来回就能定位。 + +1. **查看日志**中完整的错误响应，而不只是状态码 —— 应用错误会带上 `request_id`，它把你的请求和我们的日志关联起来。 +2. **校验输入**：确认每个参数和负载字段都符合该接口端点的要求，且金额使用的是原始单位。 +3. **用 `curl` 复现**，并隐去 API 密钥。 +4. **确认基础 URL** 包含 `/api/v1`，并且指向你以为的那个环境。 +5. **试一下接口端点页面的交互式演练场**（运行在 signet）—— 如果同样的调用在那里成功，差异就在你的客户端里。 + +## 获取帮助 + +如果是疑问而不是报错，请查看[常见问题](/cn/api-reference/faq)；规范与上游链接见[更多资源](/cn/api-reference/additional-resources)。 + +其他情况请从下面的渠道中选择一个反馈问题，并附上： + +1. 请求 URL 与 HTTP 方法 +2. 请求负载（请隐去 API 密钥） +3. 完整的错误响应，包含 `request_id` +4. 请求的时间戳 +5. 运行环境（signet / 主网） + + + + 向社群提问。 + + + 紧急问题的直接支持渠道。 + + diff --git a/mintlify-docs/cn/cli/additional-resources.mdx b/mintlify-docs/cn/cli/additional-resources.mdx new file mode 100644 index 0000000..d6dbddd --- /dev/null +++ b/mintlify-docs/cn/cli/additional-resources.mdx @@ -0,0 +1,73 @@ +--- +title: "KaleidoCLI：更多资源" +sidebarTitle: "更多资源" +description: "面向 KaleidoCLI 用户的资源汇总：本地节点相关工具、协议参考、测试网络，以及技术支持渠道" +--- + +## 工具链 {#tooling} + + + + `uv tool install` 背后的 Python 工具管理器，也是让 `kaleido` 保持隔离与最新的最简单方式。 + + + + `kaleido node` 底层驱动的工具。需要手工检查已生成的环境时会用到。 + + + +## 协议参考 + + + + `kaleido-mcp` 调用的正是同一个 `kaleido` 二进制文件，把节点生命周期与交易暴露为 LLM 可调用的工具。 + + + + `channel order` 与 `channel lsp` 背后的通道订购接口。 + + + + 所有 `node`、`wallet`、`asset`、`channel`、`payment` 命令驱动的节点。这是 KaleidoSwap 的分支；[上游项目](https://github.com/RGB-Tools/rgb-lightning-node)由 RGB Tools 维护。 + + + + 客户端验证、资产接口，以及 `asset issue` 所写入的 `nia` / `cfa` / `uda` 方案。 + + + +## 开发与测试 + + + + 领取 signet 比特币，为节点充值并开通测试通道。配合 `kaleido wallet address` 使用。 + + + + 查询 `wallet transactions` 与 `asset transfers` 背后的交易。 + + + +## 获取帮助 + +如果遇到的是报错，请查阅[故障排查](/cn/cli/troubleshooting)；如果是疑问，请查阅[常见问题](/cn/cli/faq)。 + +其他情况请通过下面你偏好的渠道反馈问题，并附上： + +1. CLI 的安装方式，以及 `uv tool list` 的输出（没有 `--version` 标志） +2. Python 版本（`python --version`）与操作系统 +3. 你执行的完整命令，以及加上 `--json` 后的输出 +4. 节点是本地 Docker 环境还是远程节点，以及所在网络 +5. `kaleido config show` 与 `kaleido node ps` 的输出，去掉其中的密码 + + + + 向社区提问。 + + + 在相应的仓库中报告缺陷。 + + + 紧急问题的直接支持渠道。 + + diff --git a/mintlify-docs/cn/cli/channels-lsp.mdx b/mintlify-docs/cn/cli/channels-lsp.mdx index bb3959b..ce5eee5 100644 --- a/mintlify-docs/cn/cli/channels-lsp.mdx +++ b/mintlify-docs/cn/cli/channels-lsp.mdx @@ -1,5 +1,6 @@ --- title: '通道与 LSP 流程' +sidebarTitle: '通道与 LSP' description: '在 KaleidoCLI 中直接开通闪电通道，或使用 KaleidoSwap 闪电服务提供商（LSP）的通道订单流程获取入向流动性' --- @@ -11,9 +12,9 @@ description: '在 KaleidoCLI 中直接开通闪电通道，或使用 KaleidoSwap |--------|---------| | `kaleido channel list` | 列出当前通道 | | `kaleido channel open ` | 向某个对等节点开通通道 | -| `kaleido channel close ` | 关闭通道 | +| `kaleido channel close --peer ` | 关闭通道 | -对等节点参数使用 `pubkey@host:port` 格式。 +对等节点参数使用 `pubkey@host:port` 格式。关闭通道同时需要通道 ID 和 `--peer`；只有在对端无响应时才加 `--force` 做单方面关闭，因为它会把资金锁定到时间锁到期为止。 ## 开通通道 @@ -50,9 +51,9 @@ kaleido channel open 03abc...@peer.host:9735 \ | 命令 | 用途 | |--------|---------| -| `kaleido channel order create ` | 创建通道订单 | +| `kaleido channel order create [client-pubkey]` | 创建通道订单，默认使用本地节点公钥 | | `kaleido channel order get ` | 获取订单状态与详情 | -| `kaleido channel order pay ` | 用本地钱包资金支付订单 | +| `kaleido channel order pay ` | 用本地钱包资金支付订单（`--onchain` 或 `--offchain`） | | `kaleido channel order decide ` | 提交费率决定 | | `kaleido channel order estimate-fees` | 估算开通费用 | @@ -64,17 +65,28 @@ kaleido channel order create 03abc... \ --client-balance 500000 ``` +公钥是可选的，默认使用你的本地节点，因此为自己订购时，`kaleido channel order create --lsp-balance 1000000 --client-balance 500000` 是等价写法。 + 常用选项： -- `--confirmations` -- `--funding-within` -- `--expiry-blocks` -- `--refund-address` +- `--confirmations`，默认 6 +- `--funding-within`，默认 144 个区块 +- `--expiry-blocks`，至少为 1 +- `--refund-address`，默认使用本地节点的地址 - `--announce` 或 `--private` - `--asset-id` -- `--lsp-asset-amount` -- `--client-asset-amount` +- `--lsp-asset-amount`，与 `--asset-id` 同时使用时必填 +- `--client-asset-amount`，不得超过 `--lsp-asset-amount` - `--email` +- `--yes`、`-y` 接受获取到的 RFQ 价格，非交互模式下必需 + +### 支付订单 + +```bash +kaleido channel order pay --access-token --offchain +``` + +用 `--onchain` 或 `--offchain` 选择资金来源；交互模式下 CLI 会询问，但在 `--agent` 或 `--json` 模式下必须恰好指定其一，并同时传入 `--yes`。链上支付可用 `--fee-rate` 指定 sat/vbyte。 染色通道订单示例： @@ -107,4 +119,4 @@ kaleido channel order estimate-fees --lsp-balance 1000000 --client-balance 50000 kaleido channel order create 03abc... --lsp-balance 1000000 --client-balance 500000 ``` -服务端交易流程通常与通道和流动性管理同时进行，详见[市场与交换](/cn/cli/market-and-swaps)。 +服务端交易流程通常与通道和流动性管理同时进行，详见[市场与交换](/cn/cli/market-and-swaps)；通道或订单无法完成时，请查阅[故障排查](/cn/cli/troubleshooting#channels-and-lsp-orders)。 diff --git a/mintlify-docs/cn/cli/command-reference.mdx b/mintlify-docs/cn/cli/command-reference.mdx index 32ebf5f..fee63f4 100644 --- a/mintlify-docs/cn/cli/command-reference.mdx +++ b/mintlify-docs/cn/cli/command-reference.mdx @@ -1,5 +1,6 @@ --- title: '命令参考' +sidebarTitle: '命令' description: 'KaleidoCLI 的完整命令地图，包含嵌套命令组和最重要的标志，涵盖节点、钱包、资产、通道、市场与交换操作' --- @@ -20,6 +21,8 @@ kaleido [global options] [subcommand] [args] | `--install-completion` | 安装 shell 补全 | | `--show-completion` | 打印 shell 补全内容 | +CLI 没有 `--version` 标志。全局标志必须放在子命令之前：`kaleido --json market pairs`，而不是 `kaleido market pairs --json`。 + ## 顶层命令 | 命令 | 说明 | @@ -63,7 +66,7 @@ kaleido [global options] [subcommand] [args] | `kaleido node info` | 显示节点详情 | | `kaleido node network` | 显示网络信息 | | `kaleido node init` | 初始化钱包 | -| `kaleido node unlock` | 解锁钱包 | +| `kaleido node unlock` | 解锁钱包（`--chain-sync block\|transaction`、`--bitcoind-*`、`--indexer-url`、`--proxy-endpoint`、`--announce-alias`、`--announce-address`） | | `kaleido node lock` | 锁定钱包 | | `kaleido node shutdown` | 优雅关闭节点 | @@ -74,7 +77,7 @@ kaleido [global options] [subcommand] [args] | `kaleido node swap pubkey` | 打印接单方公钥 | | `kaleido node swap init` | 启动本地的做市方初始化交换流程（`--from-asset`、`--qty-from`、`--to-asset`、`--qty-to`、`--timeout`） | | `kaleido node swap whitelist --swapstring ''` | 在接单方一侧将某个交换加入白名单 | -| `kaleido node swap execute` | 执行本地节点交换 | +| `kaleido node swap execute` | 执行本地节点交换（`--swapstring`、`--payment-secret`、`--taker-pubkey`） | | `kaleido node swap status ` | 查询本地节点交换状态（`--taker` 或 `--maker`） | | `kaleido node swap list` | 列出节点已知的交换 | @@ -83,14 +86,14 @@ kaleido [global options] [subcommand] [args] | 命令 | 说明 | |--------|---------| | `kaleido wallet address` | 新的 BTC 存入地址 | -| `kaleido wallet balance` | BTC 余额 | -| `kaleido wallet send
` | 发送 BTC | -| `kaleido wallet utxos` | 列出 UTXO | -| `kaleido wallet create-utxos` | 创建供 RGB 使用的 UTXO（`--up-to`、`--fee-rate`、`--skip-sync`） | +| `kaleido wallet balance` | BTC 余额（`--skip-sync`） | +| `kaleido wallet send
` | 发送 BTC（`--fee-rate`、`--skip-sync`） | +| `kaleido wallet utxos` | 列出 UTXO（`--skip-sync`） | +| `kaleido wallet create-utxos` | 创建供 RGB 使用的 UTXO（`--num/-n`、`--size`、`--up-to`、`--fee-rate`、`--skip-sync`） | | `kaleido wallet transactions` | 交易历史 | | `kaleido wallet backup ` | 备份钱包数据 | | `kaleido wallet restore ` | 恢复钱包数据 | -| `kaleido wallet change-password` | 修改钱包密码 | +| `kaleido wallet change-password` | 修改钱包密码（`--old-password`、`--new-password`） | | `kaleido wallet estimate-fee` | 估算费率（`--blocks/-b`，默认 6） | ## `asset` @@ -100,14 +103,14 @@ kaleido [global options] [subcommand] [args] | `kaleido asset list` | 列出资产 | | `kaleido asset balance ` | 资产余额 | | `kaleido asset metadata ` | 资产元数据 | -| `kaleido asset invoice ` | 创建 RGB 发票 | -| `kaleido asset send ` | 发送 RGB 资产 | -| `kaleido asset send-batch` | 向多个接收方发送 | +| `kaleido asset invoice ` | 创建 RGB 发票（`--amount/-a`、`--min-confirmations`、`--duration`、`--transport-endpoint`） | +| `kaleido asset send ` | 发送 RGB 资产（`--fee-rate`、`--min-confirmations`、`--donation`、`--transport-endpoint`、`--witness-amount-sat`、`--witness-blinding`、`--skip-sync`） | +| `kaleido asset send-batch ` | 依据 JSON 文件向多个接收方发送 | | `kaleido asset transfers ` | 转账历史 | -| `kaleido asset refresh` | 刷新待处理的转账 | +| `kaleido asset refresh` | 刷新待处理的转账（`--skip-sync`） | | `kaleido asset sync` | 同步 RGB 钱包 | -| `kaleido asset fail-transfers` | 将待处理的转账标记为失败 | -| `kaleido asset media` | 获取资产媒体 | +| `kaleido asset fail-transfers` | 将待处理的转账标记为失败（`--batch-idx`、`--no-asset-only`、`--skip-sync`） | +| `kaleido asset media ` | 按 SHA-256 摘要获取资产媒体 | ### `asset issue` @@ -117,15 +120,15 @@ kaleido [global options] [subcommand] [args] | `kaleido asset issue cfa` | 发行可收藏的同质化资产 | | `kaleido asset issue uda` | 发行独一无二的数字资产 | -所有 `issue` 子命令都接受 `--precision`，用于指定小数位数。 +所有 `issue` 子命令都接受 `--precision` 指定小数位数，且 `--supply` 以最小的原始单位表示。`cfa` 与 `uda` 还接受 `--description` 和 `--file`。 ## `channel` | 命令 | 说明 | |--------|---------| | `kaleido channel list` | 列出通道 | -| `kaleido channel open ` | 开通通道 | -| `kaleido channel close ` | 关闭通道（需要 `--peer `） | +| `kaleido channel open ` | 开通通道（`--capacity/-c`、`--push-msat`、`--asset-id`、`--asset-amount`、`--push-asset-amount`、`--public/--private`、`--with-anchors`、`--fee-base-msat`、`--fee-proportional-millionths`、`--temporary-channel-id`） | +| `kaleido channel close ` | 关闭通道（需要 `--peer `；`--force` 为单方面关闭） | ### `channel order` @@ -135,7 +138,7 @@ kaleido [global options] [subcommand] [args] | `kaleido channel order get ` | 获取订单状态（`--access-token`） | | `kaleido channel order pay ` | 支付通道订单（`--access-token`；非交互式使用时传入 `--onchain` 或 `--offchain`，以及 `--fee-rate` 和 `--yes`） | | `kaleido channel order decide ` | 提交费率决定（`--accept` 或 `--reject`、`--access-token`） | -| `kaleido channel order estimate-fees` | 估算通道订单费用 | +| `kaleido channel order estimate-fees` | 估算通道订单费用（`--lsp-balance`、`--client-balance`、`--asset-id`、`--lsp-asset-amount`、`--client-asset-amount`、`--expiry-blocks`、`--token`、`--rfq-id`） | ### `channel lsp` @@ -170,7 +173,7 @@ kaleido [global options] [subcommand] [args] |--------|---------| | `kaleido market assets` | 列出资产 | | `kaleido market pairs` | 列出交易对 | -| `kaleido market quote ` | 请求报价 | +| `kaleido market quote ` | 请求报价（`--from-amount`/`--to-amount`、`--from-layer`、`--to-layer`） | | `kaleido market info` | 做市商节点信息 | | `kaleido market routes ` | 可用路由 | @@ -180,7 +183,7 @@ kaleido [global options] [subcommand] [args] | 命令 | 说明 | |--------|---------| -| `kaleido swap atomic init ` | 初始化原子交换 | +| `kaleido swap atomic init ` | 初始化原子交换（`--from-amount`/`--to-amount`、`--from-layer`、`--to-layer`、`--yes/-y`） | | `kaleido swap atomic execute` | 执行交换（`--swapstring`、`--taker-pubkey`、`--payment-hash`，省略时会提示输入；`--auto-whitelist` 会先在本地节点上加入白名单） | | `kaleido swap atomic status ` | 原子交换状态 | | `kaleido swap atomic run ` | 运行完整的原子交换流程 | @@ -191,11 +194,34 @@ kaleido [global options] [subcommand] [args] |--------|---------| | `kaleido config show` | 打印当前配置 | | `kaleido config set ` | 更新单个配置键 | -| `kaleido config reset` | 将配置重置为默认值 | +| `kaleido config reset` | 将配置重置为默认值（`--yes/-y`） | | `kaleido config path` | 打印配置文件路径 | 有效的配置键：`node-url`、`api-url`、`network`、`spawn-dir` +## 金额与分层 + +| 命令 | 金额单位 | +|------|----------| +| `market quote`、`swap atomic init`、`swap atomic run` | 显示单位 —— `--from-amount 0.001` 表示 0.001 BTC | +| `asset invoice`、`asset send`、`payment *` | 原始整数单位，由资产精度决定 | +| `wallet send`、`wallet create-utxos`、`channel open --capacity` | 聪（satoshi） | + +分层取值也因命令而异：`market quote` 接受 `BTC_LN`、`RGB_LN` 和 `BTC_ONCHAIN`，而 `swap atomic init` 与 `swap atomic run` 接受 `BTC_L1`、`BTC_LN`、`RGB_L1` 和 `RGB_LN`。 + +## 短选项别名 + +| 别名 | 选项 | 适用命令 | +|------|------|----------| +| `-p` | `--password` | `node init`、`node unlock`、`wallet backup`、`wallet restore` | +| `-y` | `--yes` | `node clean`、`config reset`、`channel order create`、`channel order pay`、`swap atomic init`、`swap atomic run` | +| `-n` | `--node` / `--num` | `node use` / `wallet create-utxos` | +| `-s` | `--service` | `node logs` | +| `-c` | `--capacity` | `channel open` | +| `-a` | `--amount` / `--amount-msat` | `asset invoice` / `payment invoice` | +| `-e` | `--expiry` | `payment invoice` | +| `-b` | `--blocks` | `wallet estimate-fee` | + ## 机器可读模式 每个命令组都可以与 `--json` 组合使用： @@ -204,3 +230,5 @@ kaleido [global options] [subcommand] [args] kaleido --json wallet balance kaleido --json market quote BTC/USDT --from-amount 0.001 ``` + +在脚本中请同时使用 `--agent`，让缺少参数时立即报错而不是卡在提示上；对任何花钱或接受价格的操作再加上 `--yes`。详见[故障排查](/cn/cli/troubleshooting#scripting-and-automation)。 diff --git a/mintlify-docs/cn/cli/faq.mdx b/mintlify-docs/cn/cli/faq.mdx new file mode 100644 index 0000000..c10da29 --- /dev/null +++ b/mintlify-docs/cn/cli/faq.mdx @@ -0,0 +1,203 @@ +--- +title: "KaleidoCLI 常见问题" +sidebarTitle: "常见问题" +description: "关于 KaleidoCLI 的常见问题：Docker 依赖、金额单位、交换范围、密钥保管、配置优先级，以及在脚本与自动化场景中的用法" +--- + +## 常见问题 + + + + 只有需要连接节点的命令才需要。 + + | 命令组 | 是否需要节点 | + |--------|--------------| + | `market`、`config`、`channel lsp`、`channel order get` / `decide` | 不需要 —— 它们只访问 KaleidoSwap API | + | `node`、`wallet`、`asset`、`channel`、`peer`、`payment`、`swap atomic` | 需要 | + + 只装一个 CLI，就可以浏览交易对并请求报价： + + ```bash + kaleido setup --mode market --defaults + kaleido market pairs + ``` + + Docker 只用于 `node` 管理的本地环境。如果你已经在别处运行 RGB 闪电节点，用 `--node-url` 指过去即可，完全不需要 Docker。 + + + + `setup` 是首次使用的入口，`node create` 是创建更多环境的向导。 + + - **`kaleido setup`** 把 API 和节点默认值写入 `~/.kaleido/config.json`；在 `local` 模式下还会用默认端口创建并启动一个环境。不带参数的 `kaleido setup` 以非交互方式运行，因此 Docker 必须已经在运行。 + - **`kaleido node create [name]`** 会依次询问基础目录、名称、节点数量、网络和基础端口。需要第二个环境或非默认端口时用它。 + + 详见[快速开始](/cn/cli/getting-started)与[节点环境](/cn/cli/node-environments)。 + + + + 因为不同命令使用两套不同的单位约定。 + + | 命令 | 单位 | + |------|------| + | `market quote`、`swap atomic init`、`swap atomic run` | **显示单位** —— `--from-amount 0.001` 表示 0.001 BTC | + | `asset invoice`、`asset send`、`payment invoice`、`payment send`、`payment keysend` | **原始整数单位** —— 由资产精度决定换算关系 | + | `wallet send`、`wallet create-utxos`、`channel open --capacity` | 聪（satoshi） | + + 所以报价用 `--from-amount 0.001` 是对的，而 `kaleido asset send rgb:abc... 100 rgb:invoice...` 发送的是 100 个原始单位，不是 100 个显示单位。发送前先用 `kaleido asset metadata ` 确认精度。 + + + + 它们是同一套协议的两种作用范围。 + + | 范围 | maker 一侧 | 适用场景 | + |------|-----------|----------| + | `kaleido swap atomic …` | 远端的 KaleidoSwap maker | 真实交易，用本地节点作为 taker | + | `kaleido node swap …` | 你自己的节点 | 调试、演示，以及逐步手动执行协议步骤 | + + 日常交易用 `kaleido swap atomic run ` 即可，它把 init、whitelist 和 execute 合并成一条命令。详见[市场与交换](/cn/cli/market-and-swaps)。 + + + + 可接受的取值取决于具体命令： + + - `market quote` —— `BTC_LN`、`RGB_LN`、`BTC_ONCHAIN` + - `swap atomic init` 与 `swap atomic run` —— `BTC_L1`、`BTC_LN`、`RGB_L1`、`RGB_LN` + + `--from-layer` 和 `--to-layer` 都是可选的：省略时，layer 由请求的交易对方向推导。需要指定具体路径时再显式传入，例如通过闪电发送、通过 RGB on Lightning 接收： + + ```bash + kaleido market quote BTC/USDT --from-amount 0.001 --from-layer BTC_LN --to-layer RGB_LN + ``` + + + + **不会。** CLI 只是两套 HTTP API 之上的终端客户端。助记词在你运行 `kaleido node init` 时于 RGB 闪电节点内部生成，所有签名也都在节点里完成。CLI 无法转移节点未授权的任何资金。 + + 用 `--password` 传入的钱包密码会留在 shell 历史里 —— 重要场景请使用交互式输入，并把 `kaleido wallet backup` 的备份妥善保存。 + + + + 节点的密钥在静态时是加密的，因此启动后处于锁定状态。`kaleido node init` 每个节点只需运行一次，`kaleido node unlock` 则每次重启后都要运行。 + + 解锁同时决定节点使用哪些比特币服务。交互模式下 CLI 会提供三种配置档 —— signet 默认值、regtest 默认值或自定义 —— 并询问节点如何跟随链： + + - `--chain-sync block`（默认）通过 RPC 从 bitcoind 读取区块 + - `--chain-sync transaction` 只依赖索引器跟随链，完全不需要 bitcoind + + 使用 `--chain-sync transaction` 时，`--bitcoind-*` 选项会被忽略。详见[节点环境](/cn/cli/node-environments#initialize-and-unlock)。 + + + + 优先级从高到低： + + 1. 命令行标志：`--node-url`、`--api-url` + 2. 环境变量：`KALEIDO_NODE_URL`、`KALEIDO_API_URL` + 3. `~/.kaleido/config.json` 中保存的配置 + + 用 `kaleido config show` 查看已保存的配置，用 `kaleido config path` 查看文件路径。注意 `kaleido node use ` 写入的是保存的配置，因此对同时传了 `--node-url` 的命令不起作用。 + + + + 可以。每个环境都是独立的 Docker Compose 项目，拥有自己的 compose 文件、数据卷和端口，而且一个环境内可以有多个节点。 + + ```bash + kaleido node create testenv # 在向导的节点数量提示处填 2 + kaleido node list # ● 标记当前生效的节点 + kaleido node use testenv --node 2 + ``` + + 节点 1 使用守护进程端口 3001 和对等端口 9735，节点 2 使用 3002 和 9736，依此类推。只有一个环境时，`up`、`stop`、`logs`、`clean` 等命令会自动识别；有多个时必须指定名称。 + + + + 区别在于删除的范围： + + | 命令 | 容器 | 网络 | 数据卷 | + |------|------|------|--------| + | `kaleido node stop` | 停止 | 保留 | 保留 | + | `kaleido node down` | 删除 | 删除 | 保留 | + | `kaleido node clean` | 删除 | 删除 | **删除** | + + `clean` 不可撤销：它会先关停环境，再删除数据卷，钱包也在其中。如果节点里还有你需要的东西，先执行 `kaleido wallet backup`。 + + + + RGB 的分配绑定在特定的比特币输出上，因此节点需要空闲的「有色」UTXO 才能发行、接收或发送资产。链上余额即使充足，如果只集中在一个大 UTXO 上也不够用。 + + ```bash + kaleido wallet create-utxos --num 10 --size 3000 + ``` + + 在大量 RGB 操作之前一次性准备好，不要用一个建一个。`--up-to` 会把 `--num` 的含义从「新建这么多个」改为「补齐到总共这么多个」。 + + + + 三个标志就够了： + + - `--json` 返回原始 JSON 而不是表格，便于交给 `jq` + - `--agent` 关闭所有交互提示，缺少参数时直接报错而不是阻塞 + - `--yes` 自动确认报价、付款和破坏性操作 + + ```bash + kaleido --json --agent market quote BTC/USDT --from-amount 0.001 | jq '.to_asset.amount' + kaleido --agent swap atomic run BTC/USDT --from-amount 0.001 --yes + ``` + + 非交互模式下 CLI 宁可报错也不会猜测，例如 `--yes is required in non-interactive mode to accept the quoted price.`。详见[故障排查](/cn/cli/troubleshooting#scripting-and-automation)。 + + + + 是的 —— 它封装了 Python 版 SDK（`kaleido-sdk`），这也是命令输出与 API 模型高度一致的原因。实际影响有三点： + + - 请求使用 30 秒超时，最多重试 3 次 + - 错误以 `Error: ` 的形式呈现，来自底层 SDK 异常，因此 [SDK 错误参考](/cn/sdk/troubleshooting#error-reference)解释了失败的含义 + - `market quote` 的显示金额使用与 SDK 相同的精度换算工具 + + 如果你要开发应用而不是执行命令，请直接使用 [KaleidoSDK](/cn/sdk/introduction)。 + + + + | 工具 | 最适合 | + |------|--------| + | [KaleidoCLI](/cn/cli/introduction) | 在终端运行节点、编写脚本、CI 以及 agent 驱动的流程 | + | [KaleidoSDK](/cn/sdk/introduction) | 用 TypeScript 或 Python 开发应用 | + | [桌面应用](/cn/desktop-app/getting-started/introduction) | 提供同样交易与通道功能的图形化钱包 | + + 三者驱动的是同一套 API，所以用 CLI 创建的节点也能从 SDK 使用，反之亦然。 + + + + CLI 从源码安装 —— 它没有发布到 PyPI，因此 `pip install kaleido-cli` 找不到这个包。请使用引导安装脚本或 `uv`： + + ```bash + curl -fsSL https://raw.githubusercontent.com/kaleidoswap/kaleido-cli/master/install.sh | sh + uv tool install git+https://github.com/kaleidoswap/kaleido-cli.git + ``` + + 重新执行同一条命令即可更新，`uv` 安装会替换已有的工具。CLI 没有 `kaleido --version` 标志，因此请以 `uv tool list` 的输出或安装时的提交号来说明版本。完整方式见[安装](/cn/cli/installation)。 + + + +## 获取帮助 + +如果遇到的是报错而不是疑问，请查阅[故障排查](/cn/cli/troubleshooting)；上游文档与相关链接见[更多资源](/cn/cli/additional-resources)。 + +其他情况请通过下面你偏好的渠道反馈问题，并附上： + +1. CLI 的安装方式，以及 `uv tool list` 的输出（没有 `--version` 标志） +2. Python 版本（`python --version`）与操作系统 +3. 你执行的完整命令，以及加上 `--json` 后的输出 +4. 节点是本地 Docker 环境还是远程节点，以及所在网络 +5. `kaleido config show` 与 `kaleido node ps` 的输出，去掉其中的密码 + + + + 向社区提问。 + + + 在相应的仓库中报告缺陷。 + + + 紧急问题的直接支持渠道。 + + diff --git a/mintlify-docs/cn/cli/getting-started.mdx b/mintlify-docs/cn/cli/getting-started.mdx index 73a22a4..892c121 100644 --- a/mintlify-docs/cn/cli/getting-started.mdx +++ b/mintlify-docs/cn/cli/getting-started.mdx @@ -1,38 +1,10 @@ --- title: "KaleidoCLI：快速开始" sidebarTitle: "快速开始" -description: '安装 KaleidoCLI，完成首次运行设置，并配置默认的 API 与节点端点，几分钟内即可在终端使用比特币分层协议交易' +description: '完成 KaleidoCLI 首次运行设置，保存默认的 API 与节点端点，并执行第一批市场与节点命令' --- -## 环境要求 - -- Python 3.10 或更高版本 -- 推荐使用 [`uv`](https://docs.astral.sh/uv/)，也可以使用 `pip` -- 使用 `node` 命令以及任何本地 RLN 工作流都需要 Docker 与 Docker Compose - -## 安装 - -### 使用 `uv` 全局安装 - -```bash -uv tool install git+https://github.com/kaleidoswap/kaleido-cli.git -``` - -这种方式无需先克隆仓库即可安装 `kaleido` 可执行文件。 - -### 从本地代码副本安装 - -```bash -git clone https://github.com/kaleidoswap/kaleido-cli -cd kaleido-cli -make install -``` - -### 从代码副本引导安装 - -```bash -python install.py -``` +这是从装好 CLI 到跑通第一批命令的路径。如果还没有安装，请先阅读[安装](/cn/cli/installation)。 ## 首次运行设置 @@ -124,20 +96,6 @@ kaleido node info kaleido wallet address ``` -## Shell 补全 - -为当前 shell 安装补全： - -```bash -kaleido --install-completion -``` - -或者打印补全脚本以便手动安装： - -```bash -kaleido --show-completion -``` - ## 何时覆盖配置 已存储的配置适用于你的默认环境。需要时可以按命令覆盖： diff --git a/mintlify-docs/cn/cli/installation.mdx b/mintlify-docs/cn/cli/installation.mdx new file mode 100644 index 0000000..c0306b4 --- /dev/null +++ b/mintlify-docs/cn/cli/installation.mdx @@ -0,0 +1,67 @@ +--- +title: "KaleidoCLI：安装" +sidebarTitle: "安装" +description: '通过一行式安装脚本、uv 或本地代码副本安装 KaleidoCLI，并附环境要求与 shell 补全设置' +--- + +CLI 从源码安装。它没有发布到 PyPI，因此 `pip install kaleido-cli` 找不到这个包。 + +## 环境要求 + +- Python 3.10 或更高版本 +- 使用 `node` 命令以及任何本地 RLN 工作流都需要 Docker 与 Docker Compose +- `curl` 或 `wget`，仅在使用一行式 shell 安装脚本时需要 + +## 安装 CLI {#install-the-cli} + +### 一行式安装脚本 + +适用于 macOS、Linux 与 WSL： + +```bash +curl -fsSL https://raw.githubusercontent.com/kaleidoswap/kaleido-cli/master/install.sh | sh +``` + +只有 Python、没有 `curl` 或 `wget` 时： + +```bash +python3 -c "import urllib.request; exec(urllib.request.urlopen('https://raw.githubusercontent.com/kaleidoswap/kaleido-cli/master/install.py').read())" +``` + +安装脚本优先使用 `uv tool install`，否则会创建一个隔离的 Kaleido 虚拟环境，并把 `kaleido` 启动器写入用户脚本目录。它不会向系统 Python 安装任何包。 + +### 使用 `uv` 全局安装 + +```bash +uv tool install git+https://github.com/kaleidoswap/kaleido-cli.git +``` + +这种方式无需先克隆仓库即可安装 `kaleido` 可执行文件。重新执行同一条命令即可更新。 + +### 从本地代码副本安装 + +```bash +git clone https://github.com/kaleidoswap/kaleido-cli +cd kaleido-cli +./install.sh +``` + +`make install` 通过 `uv tool` 完成同样的事，`python install.py` 则是适用于 Windows 的跨平台方式。 + +如果安装后 shell 找不到 `kaleido`，安装脚本会打印需要加入 `PATH` 的目录 —— 详见[故障排查](/cn/cli/troubleshooting#installation-issues)。 + +## Shell 补全 {#shell-completion} + +为当前 shell 安装补全： + +```bash +kaleido --install-completion +``` + +或者打印补全脚本以便手动安装： + +```bash +kaleido --show-completion +``` + +`kaleido` 进入 `PATH` 之后，请继续阅读[快速开始](/cn/cli/getting-started)完成首次运行设置。 diff --git a/mintlify-docs/cn/cli/introduction.mdx b/mintlify-docs/cn/cli/introduction.mdx index ee35122..36d360e 100644 --- a/mintlify-docs/cn/cli/introduction.mdx +++ b/mintlify-docs/cn/cli/introduction.mdx @@ -13,23 +13,6 @@ description: '使用 KaleidoCLI 在终端管理本地多资产闪电节点，并 同一个二进制文件既支持交互式终端使用，也支持脚本化自动化。 -## 为什么使用它 - - - - 在同一个设置流程中，选择仅市场模式或搭建本地节点环境。 - - - 让多套本地节点栈相互隔离，并用一条命令切换当前活动节点。 - - - 处理 BTC、RGB 资产、发票、转账、备份和闪电支付。 - - - 查询交易对与报价，并执行原子交换或本地节点交换流程。 - - - ## 全局标志 所有命令组都继承同一组根标志： @@ -64,6 +47,8 @@ CLI 还会读取以下环境变量： ## 命令组 +全部功能分为十个命令组。每一组都在[命令](/cn/cli/command-reference)中逐个子命令展开，并列出参数与标志 —— 下面这张表就是那部分内容的索引。 + | 组 | 用途 | |------|---------| | `setup` | 首次运行设置，用于仅市场模式或本地节点模式 | @@ -86,9 +71,3 @@ kaleido --json market quote BTC/USDT --from-amount 0.001 ``` 当命令应当在缺少输入时直接失败、而不是弹出提示时，请使用 `--agent`。 - -## 后续步骤 - -- 如果你是第一次安装 CLI，请从[快速开始](/cn/cli/getting-started)开始。 -- 如果你需要本地 RLN 节点栈，请参阅[节点环境](/cn/cli/node-environments)。 -- 完整的命令地图请查看[命令参考](/cn/cli/command-reference)。 diff --git a/mintlify-docs/cn/cli/market-and-swaps.mdx b/mintlify-docs/cn/cli/market-and-swaps.mdx index db3834f..465be31 100644 --- a/mintlify-docs/cn/cli/market-and-swaps.mdx +++ b/mintlify-docs/cn/cli/market-and-swaps.mdx @@ -1,6 +1,7 @@ --- title: '市场与交换' -description: '在 CLI 中浏览 KaleidoSwap 市场、请求报价，并跨比特币分层协议执行订单、原子交换或本地节点交换流程' +sidebarTitle: '市场与交换' +description: '在 CLI 中浏览 KaleidoSwap 市场、请求报价，并跨比特币分层协议执行原子交换或本地节点交换流程' --- ## 市场数据 @@ -24,11 +25,24 @@ kaleido market quote BTC/USDT --to-amount 500 --from-layer BTC_LN --to-layer RGB 重要的报价选项： -- `--from-amount` 或 `--to-amount` +- `--from-amount` 或 `--to-amount` —— 二者只能传其一，因为报价只锚定一侧 - `--from-layer` - `--to-layer` -市场报价支持的分层值包括 `BTC_LN`、`RGB_LN` 和 `BTC_ONCHAIN`。 + + **这里的金额是显示单位。** `--from-amount 0.001` 表示 0.001 BTC，而不是 1000 聪。[钱包、资产与支付](/cn/cli/wallet-assets-payments)中描述的原始整数单位适用于 `asset` 与 `payment` 命令，不适用于报价和交换。 + + +### 分层取值 + +可接受的取值取决于具体命令： + +| 命令 | 分层 | +|------|------| +| `market quote` | `BTC_LN`、`RGB_LN`、`BTC_ONCHAIN` | +| `swap atomic init`、`swap atomic run` | `BTC_L1`、`BTC_LN`、`RGB_L1`、`RGB_LN` | + +两个选项都是可选的：省略时，分层由请求的交易对方向推导。 ## 交换的两种范围 @@ -47,7 +61,7 @@ kaleido market quote BTC/USDT --to-amount 500 --from-layer BTC_LN --to-layer RGB | 命令 | 用途 | |--------|---------| -| `kaleido swap atomic init ` | 初始化原子交换 | +| `kaleido swap atomic init ` | 初始化原子交换（`--yes` 接受报价，非交互模式下必需） | | `kaleido swap atomic execute` | 执行已初始化的交换（`--swapstring`、`--taker-pubkey`、`--payment-hash`，省略时会提示输入；`--auto-whitelist`） | | `kaleido swap atomic status ` | 跟踪原子交换状态 | | `kaleido swap atomic run ` | 用一条命令依次完成 init、whitelist 和 execute | @@ -79,6 +93,14 @@ kaleido swap atomic run BTC/USDT --to-amount 5 当你希望把每个步骤单独暴露出来时，这条路径适合调试、演示和更底层的协议操作。 +swapstring 由六个用斜杠分隔的字段组成，CLI 在加入白名单前会先校验： + +```text +///// +``` + +在命令行上务必加引号，让 shell 原样传递。校验报错的含义见[故障排查](/cn/cli/troubleshooting#market-and-swaps)。 + ## 推荐的交易流程 ### 浏览市场（无需节点） diff --git a/mintlify-docs/cn/cli/node-environments.mdx b/mintlify-docs/cn/cli/node-environments.mdx index ae5ad51..febdea4 100644 --- a/mintlify-docs/cn/cli/node-environments.mdx +++ b/mintlify-docs/cn/cli/node-environments.mdx @@ -1,5 +1,6 @@ --- title: '节点环境' +sidebarTitle: '环境' description: '用 KaleidoCLI 创建、运行、切换和维护命名的本地多资产闪电节点环境，为比特币分层协议开发与测试提供隔离的节点栈' --- @@ -17,19 +18,25 @@ description: '用 KaleidoCLI 创建、运行、切换和维护命名的本地多 ```text ~/.kaleido/ +├── config.json ├── default/ │ ├── docker-compose.yml │ └── volumes/ -└── staging/ +│ └── dataldk0/ +└── testenv/ ├── docker-compose.yml └── volumes/ + ├── dataldk0/ + └── dataldk1/ ``` +环境中的每个节点都是一个 `rgb_node_` 服务，各自拥有数据卷。本地运行的只有节点本身：bitcoind、索引器和 RGB 代理都是远程服务。 + ## 创建环境 ```bash kaleido node create -kaleido node create staging +kaleido node create testenv ``` 向导会依次询问： @@ -62,12 +69,14 @@ kaleido node create staging ```bash kaleido node use default -kaleido node use staging --node 2 +kaleido node use testenv --node 2 ``` +节点 1 使用守护进程端口 3001 和对等端口 9735，节点 2 使用 3002 和 9736，依此类推，起点是创建时选定的基础端口。`kaleido node list` 会用 `●` 标记当前生效的节点。 + 它是 Docker 管理的环境与所有依赖节点的命令（如 `wallet`、`asset`、`channel` 和 `payment`）之间的桥梁。 -## 初始化与解锁 +## 初始化与解锁 {#initialize-and-unlock} 新环境启动后，对钱包执行一次初始化： @@ -86,19 +95,39 @@ kaleido node init kaleido node unlock ``` -值得关注的解锁选项： +解锁同时决定节点使用哪些比特币服务。交互模式下运行时，它会先让你选择服务配置档 —— signet 默认值、regtest 默认值或自定义 —— 再询问节点如何跟随链。 + +### 跟链模式 + +| 模式 | 行为 | +|------|------| +| `--chain-sync block`（默认） | 通过 RPC 从 bitcoind 读取区块 | +| `--chain-sync transaction` | 只依赖索引器跟随链，完全不需要 bitcoind | + +使用 `transaction` 时，所有 `--bitcoind-*` 选项都会被忽略： + +```bash +kaleido node unlock --chain-sync transaction --indexer-url https://esplora.signet.kaleidoswap.com +``` + +### 解锁选项 -- `--password` -- `--bitcoind-user` -- `--bitcoind-pass` -- `--bitcoind-host` -- `--bitcoind-port` -- `--indexer-url` -- `--proxy-endpoint` -- `--announce-alias` -- `--announce-address` +| 选项 | 用途 | +|------|------| +| `--password`、`-p` | 钱包密码，省略时会安全提示输入 | +| `--chain-sync` | 如上，取值 `block` 或 `transaction` | +| `--bitcoind-user`、`--bitcoind-pass` | bitcoind RPC 凭据 | +| `--bitcoind-host`、`--bitcoind-port` | bitcoind RPC 端点 | +| `--indexer-url` | Esplora（`https://…`）或 Electrum（`host:port`） | +| `--proxy-endpoint` | RGB 代理端点 | +| `--announce-alias` | 对外公告的闪电节点别名 | +| `--announce-address` | 用于对等发现的公网地址，可重复传入 | -默认情况下，该命令使用 CLI 提供的 KaleidoSwap signet 服务。 +默认情况下，该命令使用 KaleidoSwap 的 signet 服务。脚本化解锁时请显式传入密码并关闭提示： + +```bash +kaleido --agent node unlock --password +``` ## 查看状态与上锁 diff --git a/mintlify-docs/cn/cli/troubleshooting.mdx b/mintlify-docs/cn/cli/troubleshooting.mdx new file mode 100644 index 0000000..0ab9226 --- /dev/null +++ b/mintlify-docs/cn/cli/troubleshooting.mdx @@ -0,0 +1,476 @@ +--- +title: "KaleidoCLI 故障排查" +sidebarTitle: "故障排查" +description: "定位并解决 KaleidoCLI 的常见报错：安装、Docker 环境、节点连接、资产、通道与交换，每一项都给出确切的报错文本与对应的修复步骤" +--- + +## 安装问题 {#installation-issues} + + + + **症状：** 安装已完成，但 shell 找不到 `kaleido` + + **原因：** 存放启动器的目录不在 `PATH` 中。安装脚本的最后一行已经提示过：`If 'kaleido' is not found yet, add to your PATH and restart your shell.` + + **解决办法：** + 1. 先重启 shell —— 已经运行中的会话看不到新加入 `PATH` 的条目 + 2. 若使用 `uv` 安装，确认工具目录在 `PATH` 中：`uv tool dir` 和 `uv tool list` + 3. 若使用引导安装脚本，把它打印的目录写进 shell 配置文件（`~/.bashrc`、`~/.zshrc`） + 4. Windows 上请使用 WSL —— shell 引导脚本面向 macOS、Linux 和 WSL + + + + **症状：** `ERROR: Could not find a version that satisfies the requirement kaleido-cli` + + **原因：** CLI 没有发布到 PyPI，只能从源码安装。 + + **解决办法：** + + ```bash + uv tool install git+https://github.com/kaleidoswap/kaleido-cli.git + ``` + + 也可以使用引导安装脚本，它优先调用 `uv`，否则回退到隔离的虚拟环境。详见[安装](/cn/cli/installation)。 + + + + **症状：** 安装脚本以这条信息终止 + + **解决办法：** + 1. 查看当前版本：`python3 --version` + 2. 安装更新的 Python，或交给 `uv` 管理：`uv python install 3.12` + 3. 待 `python3` 指向 3.10 或更高版本后重新执行安装 + + + +## 设置与环境 {#setup-and-environments} + + + + **症状：** 任何 `node` 生命周期命令、或不带参数的 `kaleido setup` 报出这条信息 + + **原因：** CLI 通过 `docker compose` 执行操作，因此二进制文件和运行中的守护进程缺一不可。 + + **解决办法：** + 1. 同时确认客户端与守护进程：`docker version` —— 必须出现 "Server" 部分 + 2. 启动 Docker Desktop，Linux 上执行 `sudo systemctl start docker` + 3. 确认 Compose v2 插件可用：`docker compose version` + 4. 如果完全不想用 Docker，可以只做市场模式设置：`kaleido setup --mode market --defaults` + + + + **症状：** `No docker-compose.yml found in `，随后是 `Run 'kaleido node create' to generate it.`，或者 `Environment directory not found: ` + + **原因：** + - 环境从未创建过，或创建在了另一个基础目录下 + - 配置里的 `spawn-dir` 指向的位置与环境实际所在的位置不一致 + + **解决办法：** + 1. 先看 CLI 实际能识别哪些环境：`kaleido node list` + 2. 检查基础目录：`kaleido config show` —— 环境位于 `spawn-dir` 下，默认为 `~/.kaleido` + 3. 重新创建：`kaleido node create ` + + + + **症状：** 生命周期命令拒绝执行，并列出可用的环境 + + **原因：** 只有当环境恰好只有一个时，名称才会被自动识别。 + + **解决办法：** 显式指定名称。 + + ```bash + kaleido node list + kaleido node up testenv + kaleido node logs testenv --service rgb_node_1 + ``` + + 相关的 `No environments found. Run 'kaleido node create' first.` 则是相反的问题 —— 还没有创建过任何环境。 + + + + **症状：** `kaleido setup` 以这条信息终止，并提示 `Choose a different environment name with --env-name to create a new node.` + + **解决办法：** + 1. 复用已有环境：`kaleido node up `，然后 `kaleido node use ` + 2. 或者另建一个：`kaleido setup --env-name taker-2` + + 交互式的 `kaleido node create` 则会询问是否覆盖 compose 文件，这不会影响数据卷。 + + + + **症状：** `node up` 成功，`node info` 失败 + + **解决办法：** + 1. 查看容器状态：`kaleido node ps ` + 2. 读取节点自身的日志：`kaleido node logs --service rgb_node_1 --no-follow` + 3. 排查端口冲突 —— 节点 1 绑定 3001 与 9735，节点 2 绑定 3002 与 9736。若这些端口被占用，用 `kaleido node create` 以不同的基础端口重建环境 + 4. `up` 之后稍等片刻：节点需要先打开数据库才能对外提供服务 + + + +## 节点连接 {#node-connectivity} + + + + **症状：** 这条信息，外加 `Use --node-url or: kaleido config set node-url http://localhost:3001` + + **原因：** 该命令需要节点，但标志、环境变量和配置里都没有节点 URL。 + + **解决办法：** + 1. 指向某个环境的节点：`kaleido node use ` + 2. 或直接设置：`kaleido config set node-url http://localhost:3001` + 3. 或只为这一条命令覆盖：`kaleido --node-url http://localhost:3002 wallet balance` + + + + **症状：** `wallet`、`asset`、`channel`、`payment` 报连接错误，或者余额属于另一个节点 + + **原因：** + - 容器没有在运行 + - `node-url` 仍指向你上次使用的节点 + - shell 里导出了 `KALEIDO_NODE_URL`，静默覆盖了保存的配置 + + **解决办法：** + 1. 确认当前生效的节点：`kaleido config show`，以及 `kaleido node list` —— 生效的节点标记为 `●` + 2. 启动环境：`kaleido node up ` + 3. 检查是否有残留的覆盖：`echo $KALEIDO_NODE_URL` + 4. 记住优先级：标志 → 环境变量 → 配置文件 + + + + **症状：** `kaleido node use --node 2` 被拒绝 + + **原因：** `--node` 是 compose 文件中实际定义的节点的 1 起始索引。 + + **解决办法：** 用 `kaleido node list` 查看环境里有多少个节点。需要更多节点时，重建环境并在节点数量提示处填更大的值。 + + 相关的 `No nodes found in environment ''. Is the compose file present?` 表示 compose 文件存在，但没有定义任何 `rgb_node_*` 服务。 + + + + **症状：** `Error unlocking wallet: …`，或重启后节点命令全部失败 + + **原因：** + - 节点重启后没有解锁 —— 每次重启都需要 `unlock` + - 解锁请求指向的 bitcoind 或索引器不可达 + - 这个节点上的钱包从未初始化 + + **解决办法：** + 1. 解锁：`kaleido node unlock` + 2. 如果问题出在服务上，改用索引器跟随链，而不是 bitcoind： + + ```bash + kaleido node unlock --chain-sync transaction --indexer-url https://esplora.signet.kaleidoswap.com + ``` + 3. 如果从未初始化，先运行一次 `kaleido node init` + 4. 用 `kaleido node info` 确认结果 + + + + **症状：** `Error initializing wallet: …` + + **原因：** + - 这个节点上的钱包已经初始化过 —— `init` 每个节点只做一次，不是每个会话一次 + - 恢复时传入的 `--mnemonic` 无效 + + **解决办法：** + 1. 若节点已初始化，直接执行 `kaleido node unlock` + 2. 想从干净的节点重来，`kaleido node clean ` 会不可逆地删除数据卷，之后才能重新 `init` + 3. 恢复时给助记词加引号，避免被 shell 拆开：`--mnemonic "word1 word2 …"` + + + +## 钱包与资产 {#wallet-and-assets} + + + + **症状：** `wallet send` 或 `asset send` 报余额不足 + + **原因：** + - 余额尚未确认 + - 没有空闲 UTXO 可供 RGB 分配使用 + - 金额之外的手续费无法覆盖 + + **解决办法：** + 1. 查看真正可用的部分：`kaleido wallet balance` 与 `kaleido wallet utxos` + 2. 在 RGB 操作前创建有色 UTXO：`kaleido wallet create-utxos --num 10 --size 3000` + 3. signet 上用 [Mutiny 水龙头](https://faucet.mutinynet.com/)给节点充值，地址来自 `kaleido wallet address` + 4. 用 `kaleido wallet estimate-fee --blocks 6` 查看当前费率，并显式传入 `--fee-rate` + + + + **症状：** `kaleido asset transfers ` 中的转账始终没有完成 + + **解决办法：** + 1. 推进待处理的转账：`kaleido asset refresh` + 2. 重新同步 RGB 钱包：`kaleido asset sync` + 3. 再看一次状态：`kaleido asset transfers ` + 4. 只有在转账确实失效时，才释放它占用的分配：`kaleido asset fail-transfers --batch-idx ` + + 如果你一直在传 `--skip-sync`，请去掉：命令返回的本来就是缓存状态。 + + + + **症状：** `File not found: ` 或 `Invalid JSON: …` + + **原因：** `asset send-batch` 接收的是一个描述收款方的 JSON 文件路径，而不是内联标志。 + + **解决办法：** + + ```bash + kaleido asset send-batch ./transfers.json + ``` + + 确认路径相对于当前目录正确，并在重试前校验该文件。 + + + + **症状：** `--agent` 模式下 `wallet backup` 或 `wallet restore` 被拒绝 + + **原因：** 目标路径是位置参数，而提示已被禁用。 + + **解决办法：** 显式传入路径和密码。 + + ```bash + kaleido --agent wallet backup ~/kaleido-backup.zip --password + ``` + + `restore` 会覆盖当前节点数据，务必谨慎执行。 + + + +## 通道与 LSP 订单 {#channels-and-lsp-orders} + + + + **症状：** `channel open` 或 `peer connect` 被拒绝 + + **原因：** 只传了裸公钥。交互模式下 CLI 会追问地址，非交互模式下必须给出完整格式。 + + **解决办法：** + 1. 使用完整的 peer 字符串：`kaleido channel open 03abc...@peer.host:9735 --capacity 100000` + 2. 先连接并确认可达：`kaleido peer connect 03abc...@peer.host:9735`，然后 `kaleido peer list` + + 相关的非交互模式拒绝还有 `PEER argument is required in non-interactive mode.` 与 `--capacity is required in non-interactive mode.`。 + + + + **症状：** 有色通道命令还没联系节点就被拒绝 + + **原因：** 脱离资产本身，资产数量没有意义。同样的规则适用于 `--push-asset-amount`，以及 LSP 订单上的 `--lsp-asset-amount` / `--client-asset-amount`。 + + **解决办法：** + + ```bash + kaleido channel open 03abc...@peer.host:9735 \ + --capacity 100000 \ + --asset-id rgb:abc... \ + --asset-amount 5000 + ``` + + LSP 订单上还有两条约束：`--lsp-asset-amount is required when --asset-id is set.` 与 `--client-asset-amount must be less than or equal to --lsp-asset-amount.`。 + + + + **症状：** `channel close ` 被拒绝 + + **原因：** 关闭通道同时需要通道 ID 和对端公钥。 + + **解决办法：** + + ```bash + kaleido channel list + kaleido channel close --peer 03abc... + ``` + + 只有在对端无响应时才加 `--force`：单方面关闭会把资金锁定到时间锁到期为止。 + + + + **症状：** `channel order create` 或 `estimate-fees` 拒绝该资产 + + **原因：** LSP 只为它支持的资产开通有色通道。 + + **解决办法：** 先查看它支持哪些资产，再使用其中的资产 ID。 + + ```bash + kaleido channel lsp info + ``` + + `LSP did not report a connection URL.` 是同一次交互的另一面 —— 返回的 LSP 元数据里没有对等地址，订单无法继续。 + + + + **症状：** `channel order pay` 返回 `This order is not awaiting a wallet payment. Current payment state: ` + + **原因：** + - 订单已经支付过 + - 在完成资金确认前就过期了 + - 它在等待费率决定，而不是等待付款 + + **解决办法：** + 1. 查看当前状态：`kaleido channel order get --access-token ` + 2. 若在等待费率，提交决定：`kaleido channel order decide --accept` + 3. 若已过期，重新创建订单 —— `--funding-within` 与 `--expiry-blocks` 控制这两个时间窗 + 4. 非交互模式下必须显式选择付款方式，否则会看到 `Specify exactly one of --onchain or --offchain in non-interactive mode.` + + + +## 市场与交换 {#market-and-swaps} + + + + **症状：** `Pair 'BTC/USD' not found. Use 'kaleido market pairs' to list available pairs.` + + **原因：** + - 拼写错误，或该 ticker 未上线 + - 交易对方向写反了 —— 顺序是有意义的 + + **解决办法：** + 1. 列出所有交易对：`kaleido market pairs` + 2. 使用该输出中确切的 `BASE/QUOTE` ticker + + `No trading pairs are currently available.` 则不同：maker 返回了空列表，问题在上游而不在你的命令。 + + + + **症状：** 报价或交换命令被拒绝，或提示 `Provide --from-amount or --to-amount in non-interactive mode.` + + **原因：** 报价只锚定一侧 —— 你固定发送金额或接收金额，另一侧由 maker 定价。 + + **解决办法：** + 1. 二者只传其一 + 2. 记住这里是**显示单位**：`--from-amount 0.001` 是 0.001 BTC，不是 1000 聪 + 3. 如果金额被判为无效，用 `kaleido market pairs` 查看该交易对的上下限 + + + + **症状：** 这条信息，或 `Swapstring fields must not be empty or whitespace.`、`Swapstring contains invalid numeric fields.` + + **原因：** swapstring 被截断或损坏了。它的结构是： + + ```text + ///// + ``` + + **解决办法：** + 1. 从 `swap atomic init` 的输出中完整复制，不要折行 + 2. 加引号，避免 shell 改动它：`--swapstring '30/rgb:abc.../10/rgb:def.../600/'` + 3. 或者用 `kaleido swap atomic run ` 完全跳过这一步 + + + + **症状：** `Auto-whitelist validation failed: …`，或类似 `Swapstring from_amount 30 does not match quote amount 31.` 的信息 + + **原因：** 在本地节点白名单之前，CLI 会用你接受的报价校验 swapstring。不匹配说明这个 swapstring 属于另一笔交换，或者报价已经变了。 + + **解决办法：** + 1. 重新执行 `swap atomic init`，并使用同一次响应里的 swapstring 与 payment hash —— 不要跨次混用 + 2. 重新报价后不要复用旧的 swapstring + 3. `Maker returned no swap payload for --payment-hash; refusing to auto-whitelist.` 表示 maker 没有该 payment hash 对应的交换：用 `kaleido swap atomic status ` 核对 + + + + **症状：** `swap atomic init` 成功，`swap atomic execute` 失败 + + **原因：** maker 结算之前，taker 节点必须先接受这笔交换，而这一步发生在你的节点上，不在 maker 那边。 + + **解决办法：** 三个步骤必须按顺序执行。 + + ```bash + kaleido swap atomic init BTC/USDT --to-amount 5 + kaleido node swap whitelist --swapstring '' + kaleido swap atomic execute --swapstring '' --taker-pubkey --payment-hash + ``` + + 也可以交给 CLI：给 `execute` 加上 `--auto-whitelist`，或直接用 `kaleido swap atomic run `。 + + + + **症状：** `execute` 已返回，但资产没有到账 + + **解决办法：** + 1. 轮询 maker 一侧：`kaleido swap atomic status ` + 2. 轮询你的节点一侧：`kaleido node swap status --taker` + 3. 列出节点已知的交换：`kaleido node swap list` + 4. 推进待处理的 RGB 转账：`kaleido asset refresh` + + 最常见的原因是你发送那一侧的出向容量不足。用 `kaleido channel list` 检查该资产的容量，而不只是看总余额。 + + + +## 脚本与自动化 {#scripting-and-automation} + + + + **症状：** 脚本停在那里，没有任何输出 + + **原因：** 命令在等待一个没人会回答的交互提示。 + + **解决办法：** 加上 `--agent`，它会把所有提示变成报错： + + ```bash + kaleido --agent --json wallet balance + ``` + + 这样你会得到明确的拒绝信息，例如 `PAIR argument is required in non-interactive mode.` 或 ` + + + **症状：** `--yes is required in non-interactive mode to accept the quoted price.`、`… to accept the RFQ price.`、`… to pay the order.`，或它们的 JSON 模式变体 + + **原因：** 任何花钱或接受价格的操作都会请求确认，而此时没人可以确认。 + + **解决办法：** + 1. 确认参数无误后加上 `--yes` + 2. 先用 `kaleido market quote` 或 `kaleido channel order estimate-fees` 核价，再带 `--yes` 执行 + 3. `kaleido node clean` 与 `kaleido config reset` 同样接受 `--yes` + + + + **症状：** `Must specify exactly one of --accept or --reject`、`Must specify at most one of --taker or --maker`，或 `Specify exactly one of --onchain or --offchain in non-interactive mode.` + + **原因：** 这些是选择而不是开关，两个都不给或都给时，CLI 拒绝猜测。 + + **解决办法：** 只传其中一个。交互模式下两个都省略时，CLI 会改为询问。 + + + +## 调试 + +当报错信息不足以定位问题时，从 CLI 自己的视角逐层向外排查： + +```bash +kaleido config show # 当前使用的 API 与节点 URL +kaleido node list # 有哪些环境，哪个节点生效 +kaleido node ps # 容器状态 +kaleido node logs --service rgb_node_1 --no-follow +kaleido node info # 节点是否可达且已解锁 +kaleido --json <失败的命令> # 原始 API 响应 +``` + +同时检查 `echo $KALEIDO_NODE_URL` 与 `echo $KALEIDO_API_URL`：导出的环境变量会覆盖保存的配置，而且很容易被忘记。 + +## 获取帮助 + +如果遇到的是疑问而不是报错，请查阅[常见问题](/cn/cli/faq)；上游文档与相关链接见[更多资源](/cn/cli/additional-resources)。 + +其他情况请通过下面你偏好的渠道反馈问题，并附上： + +1. CLI 的安装方式，以及 `uv tool list` 的输出（没有 `--version` 标志） +2. Python 版本（`python --version`）与操作系统 +3. 你执行的完整命令，以及加上 `--json` 后的输出 +4. 节点是本地 Docker 环境还是远程节点，以及所在网络 +5. `kaleido config show` 与 `kaleido node ps` 的输出，去掉其中的密码 + + + + 向社区提问。 + + + 在相应的仓库中报告缺陷。 + + + 紧急问题的直接支持渠道。 + + diff --git a/mintlify-docs/cn/cli/wallet-assets-payments.mdx b/mintlify-docs/cn/cli/wallet-assets-payments.mdx index 9e60a6f..c629ac5 100644 --- a/mintlify-docs/cn/cli/wallet-assets-payments.mdx +++ b/mintlify-docs/cn/cli/wallet-assets-payments.mdx @@ -1,5 +1,6 @@ --- title: '钱包、资产与支付' +sidebarTitle: '钱包与资产' description: '通过 KaleidoCLI 管理比特币、比特币二层资产、闪电发票和节点备份，在终端完成余额查询、资产发行与支付操作' --- @@ -12,6 +13,10 @@ kaleido node use default kaleido node unlock ``` + + **本页的单位约定。** `wallet` 的金额以聪为单位，`asset` 与 `payment` 的金额以原始整数单位表示，换算关系由资产精度决定 —— 用 `kaleido asset metadata ` 查看。`--from-amount 0.001` 这类显示单位只出现在[市场与交换命令](/cn/cli/market-and-swaps)中。 + + ## BTC 钱包 ### 常用钱包命令 @@ -28,23 +33,42 @@ kaleido node unlock | `kaleido wallet backup ` | 创建加密的钱包备份 | | `kaleido wallet restore ` | 从备份压缩包恢复 | | `kaleido wallet change-password` | 更换钱包密码 | +`balance`、`utxos` 和 `transactions` 都接受 `--skip-sync`，跳过同步直接返回缓存状态。 + ### 示例 ```bash kaleido wallet address kaleido wallet balance -kaleido wallet send 50000 bc1q... +kaleido wallet send 50000 bc1q... --fee-rate 2 +kaleido wallet estimate-fee --blocks 6 +``` + +### 染色 UTXO + +RGB 的分配绑定在特定的比特币输出上，因此节点必须先有空闲 UTXO，才能发行、接收或发送资产： + +```bash kaleido wallet create-utxos --num 10 --size 3000 ``` +| 选项 | 用途 | +|------|------| +| `--num`、`-n` | 创建多少个 UTXO | +| `--size` | 每个 UTXO 的大小（聪） | +| `--up-to` | 把 `--num` 理解为「补齐到的总数」，而不是「新增的个数」 | +| `--fee-rate` | 链上费率（sat/vbyte） | +| `--skip-sync` | 创建前跳过区块链同步 | + ### 备份与恢复 ```bash kaleido wallet backup ~/kaleido-backup.zip kaleido wallet restore ~/kaleido-backup.zip +kaleido wallet change-password --old-password --new-password ``` -这两条命令都接受 `--password`。恢复会覆盖当前的节点数据，请谨慎使用。 +`backup` 与 `restore` 都接受 `--password`、`-p`。恢复会覆盖当前的节点数据，请谨慎使用。 ## RGB 资产 @@ -57,7 +81,7 @@ kaleido wallet restore ~/kaleido-backup.zip | `kaleido asset metadata ` | 显示资产元数据 | | `kaleido asset invoice ` | 创建 RGB 发票 | | `kaleido asset send ` | 发送 RGB 资产 | -| `kaleido asset send-batch` | 在一笔交易中向多个 RGB 接收方发送 | +| `kaleido asset send-batch ` | 依据 JSON 文件，在一笔交易中向多个 RGB 接收方发送 | | `kaleido asset transfers ` | 查看转账历史 | | `kaleido asset refresh` | 刷新待处理的转账 | | `kaleido asset sync` | 同步 RGB 钱包 | @@ -80,6 +104,8 @@ kaleido asset issue uda --ticker TKT1 --name "Ticket #1" --file ./ticket.png - `cfa` 用于可收藏的同质化资产 - `uda` 用于独一无二的数字资产 +三者都接受 `--precision` 指定小数位数，`--supply` 以最小的原始单位表示。`cfa` 与 `uda` 还接受 `--description`。 + ### 资产发票与发送示例 ```bash @@ -93,8 +119,27 @@ kaleido asset send rgb:abc123... 100 rgb:invoice... - `--min-confirmations` - `--donation` - `--transport-endpoint` +- `--witness-amount-sat` 与 `--witness-blinding` - `--skip-sync` +### 批量发送 + +`asset send-batch` 接收的是一个描述收款方的 JSON 文件路径，而不是内联标志： + +```bash +kaleido asset send-batch ./transfers.json +``` + +### 让转账继续推进 + +```bash +kaleido asset refresh +kaleido asset sync +kaleido asset transfers rgb:abc123... +``` + +用 `refresh` 推进待处理的转账，用 `sync` 重新同步 RGB 钱包。只有当某笔转账确实失效时，才用 `kaleido asset fail-transfers` 释放它占用的分配；该命令接受 `--batch-idx` 指定单个批次、`--no-asset-only` 只处理无资产的转账，以及 `--skip-sync`。 + ## 闪电与 RGB+LN 支付 ### 支付命令 @@ -133,4 +178,4 @@ kaleido payment decode rgb:... - 只有在可以接受钱包或转账状态陈旧时，才使用 `--skip-sync`。 - 在进行大量 RGB 操作之前先创建额外的 UTXO，以免可用的染色输出耗尽。 -如果你要管理通道或订购入向流动性，请接着阅读[通道与 LSP 流程](/cn/cli/channels-lsp)。 +如果你要管理通道或订购入向流动性，请接着阅读[通道与 LSP 流程](/cn/cli/channels-lsp)；如果余额、转账或发送出现异常，请查阅[故障排查](/cn/cli/troubleshooting#wallet-and-assets)。 diff --git a/mintlify-docs/cn/desktop-app/channels/channel-backups.mdx b/mintlify-docs/cn/desktop-app/channels/channel-backups.mdx index fe77df1..3bcdbcf 100644 --- a/mintlify-docs/cn/desktop-app/channels/channel-backups.mdx +++ b/mintlify-docs/cn/desktop-app/channels/channel-backups.mdx @@ -66,9 +66,9 @@ description: "在 KaleidoSwap 桌面应用中创建和恢复闪电通道备份 由于备份包含完整的节点状态，恢复后通道会照常继续运行——既不需要输入助记词，也不会触发强制关闭。 - + 备份文件使用你的节点密码加密。没有这个密码，备份文件无法解密，也无法恢复。 - + --- diff --git a/mintlify-docs/cn/desktop-app/support/additional-resources.mdx b/mintlify-docs/cn/desktop-app/support/additional-resources.mdx index 64041be..1d24943 100644 --- a/mintlify-docs/cn/desktop-app/support/additional-resources.mdx +++ b/mintlify-docs/cn/desktop-app/support/additional-resources.mdx @@ -20,8 +20,37 @@ description: "面向 KaleidoSwap 用户和开发者的实用链接，包括社 获取用于在 Mutinynet 上开发和测试的测试网比特币。 - - 加入社区获取支持并参与讨论。 + + + 查看 signet 上的充值、通道开启或交换是否已确认。 + + + +## 获取帮助 + +如果遇到的是报错，请查看[故障排查](/cn/desktop-app/support/troubleshooting)；如果是疑问，请查看[常见问题](/cn/desktop-app/support/faq)。 + +其他情况请通过下方任一渠道反馈问题，并附上以下信息： + +1. 你的操作系统及版本（macOS、Windows 或 Linux） +2. KaleidoSwap 桌面应用版本 +3. 节点类型（本地或远程）及版本 +4. 复现步骤 +5. 错误信息或截图 +6. 日志文件： + - macOS：`~/Library/Logs/com.kaleidoswap.dev/` + - Windows：`%APPDATA%\com.kaleidoswap.dev\logs` + - Linux：`~/.local/share/com.kaleidoswap.dev/logs` + + + + 向社区提问。 + + + 在对应的代码仓库中反馈 bug。 + + + 紧急问题的直接支持渠道。 diff --git a/mintlify-docs/cn/desktop-app/support/faq.mdx b/mintlify-docs/cn/desktop-app/support/faq.mdx index 987f661..bc3f7ac 100644 --- a/mintlify-docs/cn/desktop-app/support/faq.mdx +++ b/mintlify-docs/cn/desktop-app/support/faq.mdx @@ -97,7 +97,9 @@ description: "关于 KaleidoSwap 桌面应用的常见问题解答，涵盖钱 ## 获取帮助 -如果遇到的是报错而不是疑问，请先查看[故障排查](/cn/desktop-app/support/troubleshooting)。其他情况请通过下方任一渠道反馈问题，并附上以下信息： +如果遇到的是报错而不是疑问，请先查看[故障排查](/cn/desktop-app/support/troubleshooting)；上游文档与相关链接见[更多资源](/cn/desktop-app/support/additional-resources)。 + +其他情况请通过下方任一渠道反馈问题，并附上以下信息： 1. 你的操作系统及版本（macOS、Windows 或 Linux） 2. KaleidoSwap 桌面应用版本 @@ -113,7 +115,7 @@ description: "关于 KaleidoSwap 桌面应用的常见问题解答，涵盖钱 向社区提问。 - + 在对应的代码仓库中反馈 bug。 diff --git a/mintlify-docs/cn/desktop-app/support/settings.mdx b/mintlify-docs/cn/desktop-app/support/settings.mdx index 8e47351..d8cbc65 100644 --- a/mintlify-docs/cn/desktop-app/support/settings.mdx +++ b/mintlify-docs/cn/desktop-app/support/settings.mdx @@ -57,9 +57,9 @@ description: "配置 KaleidoSwap 桌面应用：应用模式、比特币单位 ## 节点连接设置 - + 这些设置需要重启节点才能生效。保存后，应用会提示你 **「重启节点」(Restart Node)**，以便应用新的连接设置。 - + ### 节点连接串 (Node Connection String) diff --git a/mintlify-docs/cn/desktop-app/support/troubleshooting.mdx b/mintlify-docs/cn/desktop-app/support/troubleshooting.mdx index 5a9deb7..60f40e8 100644 --- a/mintlify-docs/cn/desktop-app/support/troubleshooting.mdx +++ b/mintlify-docs/cn/desktop-app/support/troubleshooting.mdx @@ -1,11 +1,9 @@ --- title: "KaleidoSwap 桌面应用故障排查" sidebarTitle: "故障排查" -description: "解决 KaleidoSwap 桌面应用中交易失败、钱包恢复和 LSP 连接等常见问题，提供逐步排查方法，并链接到完整的支持指南。" +description: "解决 KaleidoSwap 桌面应用中交易失败、钱包恢复和 LSP 连接等常见问题，提供逐步排查方法与技术支持渠道。" --- -以下是桌面应用用户最常遇到问题的解决办法。如需了解涵盖各个 KaleidoSwap 组件的安装、节点同步、通道和交换问题，请参见[完整故障排查指南](/cn/whats-kaleidoswap/troubleshooting)。 - ## 交易 @@ -50,8 +48,6 @@ description: "解决 KaleidoSwap 桌面应用中交易失败、钱包恢复和 L 2. 核对 LSP 地址——默认为 `https://api.mutinynet2.kaleidoswap.com/`，位于「设置」(Settings) → 「做市方与 LSP 设置」(Maker & LSP Settings) 3. 检查防火墙/VPN 设置；需要开放的端口为 9735（闪电 P2P）和 3001（节点 API） 4. 查看该 LSP 的状态页面，或在有其他 LSP 可选时切换一个 - - 更多连接问题（包括节点配置和通道容量问题）请参见[完整故障排查指南](/cn/whats-kaleidoswap/troubleshooting)。 @@ -104,7 +100,9 @@ description: "解决 KaleidoSwap 桌面应用中交易失败、钱包恢复和 L ## 获取帮助 -如果遇到的是疑问而不是报错，请查看[常见问题](/cn/desktop-app/support/faq)。其他情况请通过下方任一渠道反馈问题，并附上以下信息： +如果遇到的是疑问而不是报错，请查看[常见问题](/cn/desktop-app/support/faq)；上游文档与相关链接见[更多资源](/cn/desktop-app/support/additional-resources)。 + +其他情况请通过下方任一渠道反馈问题，并附上以下信息： 1. 你的操作系统及版本（macOS、Windows 或 Linux） 2. KaleidoSwap 桌面应用版本 @@ -120,7 +118,7 @@ description: "解决 KaleidoSwap 桌面应用中交易失败、钱包恢复和 L 向社区提问。 - + 在对应的代码仓库中反馈 bug。 diff --git a/mintlify-docs/cn/extensions/kaleidoswap-extension/additional-resources.mdx b/mintlify-docs/cn/extensions/kaleidoswap-extension/additional-resources.mdx index adf03b0..6b9c461 100644 --- a/mintlify-docs/cn/extensions/kaleidoswap-extension/additional-resources.mdx +++ b/mintlify-docs/cn/extensions/kaleidoswap-extension/additional-resources.mdx @@ -42,21 +42,28 @@ description: "KaleidoSwap 扩展用户的常用链接：测试版申请、社群 -## 社群与支持 +## 获取帮助 + +如果是报错，请查看[故障排查](/cn/extensions/kaleidoswap-extension/troubleshooting)；如果是疑问，请查看[常见问题](/cn/extensions/kaleidoswap-extension/faq)。 + +其他情况请从下面的渠道中选择一个反馈问题，并附上： + +1. 浏览器名称和版本 +2. KaleidoSwap 扩展版本（Settings > About） +3. 节点类型和版本 +4. 复现步骤 +5. 错误信息或截图 +6. 控制台日志（右键点击扩展弹出窗口 > Inspect > Console） - - 加入社群，与其他测试者交流并获取支持。 + + 向社群提问。 紧急问题的直接支持渠道。 - - 反馈问题时，请附上浏览器及版本、**设置 > 关于**（Settings > About）中显示的扩展版本、复现步骤，以及控制台日志（右键点击弹出窗口，然后选择 **Inspect > Console**）。请先查看[故障排查](/cn/extensions/kaleidoswap-extension/troubleshooting)。 - - --- diff --git a/mintlify-docs/cn/extensions/kaleidoswap-extension/faq.mdx b/mintlify-docs/cn/extensions/kaleidoswap-extension/faq.mdx index 551aa96..87ebf2b 100644 --- a/mintlify-docs/cn/extensions/kaleidoswap-extension/faq.mdx +++ b/mintlify-docs/cn/extensions/kaleidoswap-extension/faq.mdx @@ -80,7 +80,9 @@ description: "关于 KaleidoSwap 扩展的常见问题：浏览器支持、多 ## 获取帮助 -如果遇到的是报错而不是疑问，请查看[故障排查](/cn/extensions/kaleidoswap-extension/troubleshooting)。其他情况请从下面的渠道中选择一个反馈问题，并附上： +如果遇到的是报错而不是疑问，请查看[故障排查](/cn/extensions/kaleidoswap-extension/troubleshooting)；上游文档与相关链接见[更多资源](/cn/extensions/kaleidoswap-extension/additional-resources)。 + +其他情况请从下面的渠道中选择一个反馈问题，并附上： 1. 浏览器名称和版本 2. KaleidoSwap 扩展版本（Settings > About） diff --git a/mintlify-docs/cn/extensions/kaleidoswap-extension/getting-started.mdx b/mintlify-docs/cn/extensions/kaleidoswap-extension/getting-started.mdx index f1d0456..cd0df5b 100644 --- a/mintlify-docs/cn/extensions/kaleidoswap-extension/getting-started.mdx +++ b/mintlify-docs/cn/extensions/kaleidoswap-extension/getting-started.mdx @@ -54,9 +54,9 @@ description: "在 KaleidoSwap 扩展中创建或导入钱包、备份助记词 KaleidoSwap 扩展设置密码步骤 - + 恢复钱包时，请始终使用 **BIP39 助记词**，而不是 Nostr 密钥。导入的 Nostr 密钥只会替换 Nostr 身份，并不控制资金。 - + 发现云端备份的提示，询问是否从 VSS 备份服务器恢复加密的 RGB 状态，并提供「暂时跳过」选项 diff --git a/mintlify-docs/cn/extensions/kaleidoswap-extension/troubleshooting.mdx b/mintlify-docs/cn/extensions/kaleidoswap-extension/troubleshooting.mdx index 4ca9890..9a413c6 100644 --- a/mintlify-docs/cn/extensions/kaleidoswap-extension/troubleshooting.mdx +++ b/mintlify-docs/cn/extensions/kaleidoswap-extension/troubleshooting.mdx @@ -4,8 +4,6 @@ sidebarTitle: "故障排查" description: "解决 KaleidoSwap 扩展中的节点连接、支付和 DApp 提供方问题，并说明向支持团队反馈缺陷时应该附上哪些信息。" --- -这里汇总了 KaleidoSwap 扩展用户最常遇到的问题及其解决办法。如需覆盖 KaleidoSwap 全部产品的问题排查，请参见[完整故障排查指南](/cn/whats-kaleidoswap/troubleshooting)。 - ## 连接问题 @@ -105,7 +103,9 @@ description: "解决 KaleidoSwap 扩展中的节点连接、支付和 DApp 提 ## 获取帮助 -如果是疑问而不是报错，请查看[常见问题](/cn/extensions/kaleidoswap-extension/faq)。其他情况请从下面的渠道中选择一个反馈问题，并附上： +如果是疑问而不是报错，请查看[常见问题](/cn/extensions/kaleidoswap-extension/faq)；上游文档与相关链接见[更多资源](/cn/extensions/kaleidoswap-extension/additional-resources)。 + +其他情况请从下面的渠道中选择一个反馈问题，并附上： 1. 浏览器名称和版本 2. KaleidoSwap 扩展版本（Settings > About） diff --git a/mintlify-docs/cn/sdk/additional-resources.mdx b/mintlify-docs/cn/sdk/additional-resources.mdx index 89342a2..fe3b1c5 100644 --- a/mintlify-docs/cn/sdk/additional-resources.mdx +++ b/mintlify-docs/cn/sdk/additional-resources.mdx @@ -1,20 +1,12 @@ --- title: "KaleidoSDK：更多资源" sidebarTitle: "更多资源" -description: "面向 KaleidoSDK 开发者的资源汇总：已发布的软件包、OpenAPI 规范、节点与 RGB 协议参考、测试网络，以及技术支持渠道" +description: "面向 KaleidoSDK 开发者的资源汇总：源码仓库、OpenAPI 规范、节点与 RGB 协议参考、测试网络，以及技术支持渠道" --- -## 软件包与源码 +## 源码仓库 - - 已发布的 TypeScript 包。`npm install kaleido-sdk` - - - - 已发布的 Python 包。`pip install kaleido-sdk` - - 两种语言实现的源码、发布记录与问题跟踪。 @@ -27,14 +19,6 @@ description: "面向 KaleidoSDK 开发者的资源汇总：已发布的软件包 ## 协议参考 - - SDK 所驱动的原子 HTLC 流程，逐个接口端点讲解，并附有时序图。 - - - - `client.maker` 的 LSPS1 调用背后的通道下单接口。 - - `client.rln` 所通信的节点。这是 KaleidoSwap 的分支版本；[上游项目](https://github.com/RGB-Tools/rgb-lightning-node)由 RGB Tools 维护。 @@ -46,40 +30,36 @@ description: "面向 KaleidoSDK 开发者的资源汇总：已发布的软件包 ## 开发与测试 -上主网之前请先在测试网络上开发。两个环境都已上线，且都不需要 API key。 - -按下面的写法把它们传入 `baseUrl` / `base_url` —— `/api/v1` 路径由 SDK 自动追加。 - -| 环境 | Base URL | 适用场景 | -|-------------|----------|----------| -| **signet (MutinyNet)** | `https://api.signet.kaleidoswap.com` | 在贴近真实的条件下做集成测试 | - 获取 signet 比特币，用于为节点充值并开通测试通道。 - - Base URL、认证方式、请求格式与速率限制。 + + 查询 `listSwaps` 与 `refreshTransfers` 背后的交易。 -## 社区与支持 +## 获取帮助 - - - 针对 SDK 报告缺陷或提出功能需求。 - +报错请查看[故障排查](/cn/sdk/troubleshooting)，疑问请查看[常见问题](/cn/sdk/faq)。 - - 向社区和团队提问。 - +其他情况请通过下面任一渠道反馈问题，并附上： + +1. SDK 版本（`getVersion()` / `get_version()`） +2. 语言与运行时版本（Node.js / Python） +3. 错误信息和堆栈跟踪 +4. 可复现问题的最小代码 +5. 所在环境（signet / 主网） + + + 向社区提问。 + + + 在对应的代码仓库中反馈 bug。 + 紧急问题的直接支持渠道。 - - - 语言选择、子客户端、密钥保管、版本兼容与金额单位。 - diff --git a/mintlify-docs/cn/sdk/api-reference.mdx b/mintlify-docs/cn/sdk/api-reference.mdx index 95f8584..bb25ed5 100644 --- a/mintlify-docs/cn/sdk/api-reference.mdx +++ b/mintlify-docs/cn/sdk/api-reference.mdx @@ -4,6 +4,15 @@ sidebarTitle: "客户端参考" description: "KaleidoSDK 中 KaleidoClient、MakerClient 与 RlnClient 的完整参考，涵盖各个方法、参数与返回类型。" --- +## 总览 {#overview} + +`KaleidoClient` 是唯一的入口。创建一次之后，通过它的两个子客户端进行操作： + +- **`client.maker`** —— KaleidoSwap 托管的 [Maker API](/cn/sdk/maker-api-compatibility)：市场数据、报价、原子交换、LSPS1 通道订购 +- **`client.rln`** —— 你自己的 [RGB Lightning Node](/cn/sdk/rln-api-compatibility)：钱包、RGB 资产、通道、发票、支付 + +`client.maker` 只需要 `baseUrl`，而 `client.rln` 还需要 `nodeUrl` / `node_url`。下文每个方法都同时给出 TypeScript 与 Python 两种形式。 + ## 客户端初始化 diff --git a/mintlify-docs/cn/sdk/best-practices.mdx b/mintlify-docs/cn/sdk/best-practices.mdx index 920cc87..2c989af 100644 --- a/mintlify-docs/cn/sdk/best-practices.mdx +++ b/mintlify-docs/cn/sdk/best-practices.mdx @@ -8,31 +8,9 @@ description: "用 KaleidoSDK 构建生产级应用的实践指南：客户端初 ### 使用环境变量 -不要把配置写进源码： +不要把配置写进源码。SDK 不会自动加载环境变量 —— 请自行读取后传给 `create()`。 - -```typescript TypeScript -import { KaleidoClient } from 'kaleido-sdk'; - -const client = KaleidoClient.create({ - baseUrl: process.env.KALEIDO_API_URL!, - nodeUrl: process.env.KALEIDO_NODE_URL, - apiKey: process.env.KALEIDO_API_KEY, -}); -``` - -```python Python -import os - -from kaleido_sdk import KaleidoClient - -client = KaleidoClient.create( - base_url=os.environ["KALEIDO_API_URL"], - node_url=os.environ.get("KALEIDO_NODE_URL"), - api_key=os.environ.get("KALEIDO_API_KEY"), -) -``` - +约定的变量名以及两种语言的完整示例见[安装](/cn/sdk/installation#environment-variables)。 ### 使用单例客户端 @@ -77,7 +55,7 @@ def get_client() -> KaleidoClient: ### 始终处理错误 -把 SDK 调用包在 try/catch 中，并针对具体错误类型分别处理。下面给出的是最起码值得区分的几类；完整版本见 [错误处理](/cn/sdk/error-handling#comprehensive-error-handling)。 +把 SDK 调用包在 try/catch 中，并针对具体错误类型分别处理。下面给出的是最起码值得区分的几类；完整版本见[故障排查](/cn/sdk/troubleshooting#comprehensive-error-handling)。 ```typescript TypeScript @@ -118,7 +96,7 @@ except KaleidoError as e: 不要盲目重试。每个错误都提供 `isRetryable()` / `is_retryable()`，其中已经编码了哪些失败在第二次尝试时可能成功 —— 请使用它，而不要自己去匹配状态码。 -完整的异常层级结构、按状态码划分的可重试性表格，以及现成的指数退避封装，见 [错误处理](/cn/sdk/error-handling#retry-patterns)。 +完整的异常层级结构、按状态码划分的可重试性表格，以及现成的指数退避封装，见[故障排查](/cn/sdk/troubleshooting#retry-patterns)。 ## 异步模式 @@ -172,108 +150,29 @@ for name, fn in [ ### 调用 API 时一律使用原始单位 -API 使用原始（最小单位）金额。发送前请先转换展示金额： +API 只接受原始（最小单位）金额，不接受展示金额。构造报价请求前用 `parseRawAmount` / `parse_raw_amount` 转换，展示给用户前再用 `toDisplayAmount` / `to_display_amount` 转换回来。 - -```typescript TypeScript -import { parseRawAmount } from 'kaleido-sdk'; - -// 用户输入 0.001 BTC -const userInput = 0.001; -const rawAmount = parseRawAmount(userInput, 8); // 100000 - -const quote = await client.maker.getQuote({ - from_asset: { asset_id: 'BTC', layer: 'BTC_LN', amount: rawAmount }, - to_asset: { asset_id: 'USDT', layer: 'RGB_LN' } -}); -``` - -```python Python -from kaleido_sdk import Layer, PairQuoteRequest, SwapLegInput, parse_raw_amount - -# 用户输入 0.001 BTC -user_input = 0.001 -raw_amount = parse_raw_amount(user_input, 8) # 100000 - -quote = await client.maker.get_quote(PairQuoteRequest( - from_asset=SwapLegInput(asset_id="BTC", layer=Layer.BTC_LN, amount=raw_amount), - to_asset=SwapLegInput(asset_id="USDT", layer=Layer.RGB_LN) -)) -``` - +这两个函数的说明见[工具函数](/cn/sdk/utilities#amount-conversion)。 ### 多资产应用请使用 PrecisionHandler -处理多种资产时，使用 `PrecisionHandler` 避免精度错误： +一旦涉及多种资产，每次调用都手工传入精度正是舍入错误的来源。`PrecisionHandler` 会从资产元数据中读取精度，让你按资产 ID 转换。 - -```typescript TypeScript -import { createPrecisionHandler } from 'kaleido-sdk'; - -const handler = createPrecisionHandler(mappedAssets); - -// 按资产 ID 安全转换 -const raw = handler.toRawAmount(userInput, assetId); -const display = handler.toDisplayAmount(rawFromApi, assetId); -``` - -```python Python -from kaleido_sdk import create_precision_handler - -handler = create_precision_handler(mapped_assets) -raw = handler.to_raw_amount(user_input, asset_id) -display = handler.to_display_amount(raw_from_api, asset_id) -``` - +如何创建以及完整方法列表见[工具函数](/cn/sdk/utilities#precisionhandler)。 ## 节点操作 -### 使用 RLN 前先检查节点 - -务必确认节点已配置： - - -```typescript TypeScript -if (!client.hasNode()) { - throw new Error('Node URL required for this operation'); -} - -const balance = await client.rln.getBtcBalance(); -``` - -```python Python -if not client.has_node(): - raise RuntimeError("Node URL required for this operation") +只有在创建客户端时提供了节点 URL，`client.rln` 才可用，因此每次节点调用前都要用 `hasNode()` / `has_node()` 做检查。在 Python 中，未配置节点 URL 时访问 `client.rln` 会抛出 `NodeNotConfiguredError`。 -balance = await client.rln.get_btc_balance() -``` - +两种语言的检查写法见[快速上手](/cn/sdk/getting-started#node-configuration-checks)。 ## WebSocket ### 用完后取消订阅 -务必清理 WebSocket 订阅： - - -```typescript TypeScript -const unsubscribe = await client.maker.streamQuotesByTicker( - 'BTC', 'USDT', 100000, onQuote -); - -// 组件卸载或用户离开页面时清理 -unsubscribe(); -``` +`streamQuotes` / `streamQuotesByTicker` 会返回一个取消订阅函数。一旦不再需要报价就立刻调用它 —— 组件卸载时、页面跳转时，或用户关闭该交易对时。不调用会造成内存泄漏，并让无人读取的报价流量持续占用连接。 -```python Python -unsubscribe = await client.maker.stream_quotes_by_ticker( - "BTC", "USDT", 100000, on_quote -) - -# 用完后清理 -unsubscribe() -``` - +这一条以及其他流式订阅的注意事项见 [WebSocket](/cn/sdk/websocket#best-practices)。 ### 处理重连 diff --git a/mintlify-docs/cn/sdk/changelog.mdx b/mintlify-docs/cn/sdk/changelog.mdx index 7de1d69..78c3790 100644 --- a/mintlify-docs/cn/sdk/changelog.mdx +++ b/mintlify-docs/cn/sdk/changelog.mdx @@ -4,7 +4,29 @@ sidebarTitle: "更新日志" description: "KaleidoSDK 的版本历史：每个版本的新增功能、破坏性变更，以及与 RLN 和 Maker API 的兼容性说明" --- -## SDK v0.1.17（当前版本） +## SDK v0.1.18（当前版本） + +**兼容的 API：** 最新 Maker API · RLN (RGB Lightning Node) API **v0.9.0** + + +本版本要求 RGB Lightning Node 至少为 **v0.9.0**。如果你的节点仍在运行 0.8.0 或更早版本，请继续使用 SDK **0.1.17** —— 新的 `/unlock` 请求体会被这些节点拒绝，而它们所需的请求体结构在新版中已无法表达。 + + +### 变更 + +- 将随包提供的 RGB Lightning Node OpenAPI 规范同步到 RLN **v0.9.0**，并重新生成了节点模型（Python + TypeScript）。 + +### 新增 + +- `UnlockRequest` 新增 `ldk_chain_sync`，用于选择 LDK 如何跟踪链上数据：`BlockSync`（通过 bitcoind RPC，即 0.9.0 之前的行为）或 `TransactionSync`（仅使用索引器，不需要 bitcoind）。 +- 新增节点类型 `LdkChainSyncBlockSync` 和 `LdkChainSyncTransactionSync`。TypeScript 还导出了 `LdkChainSync` 联合类型以及 `LdkChainSyncBlockSyncMode` / `LdkChainSyncTransactionSyncMode` 枚举；Python 则以 `LdkBlockSyncConfig` / `LdkTransactionSyncConfig` 导出嵌套配置。 + +### 破坏性变更 + +- **`UnlockRequest` 不再接受 `bitcoind_rpc_username`、`bitcoind_rpc_password`、`bitcoind_rpc_host` 和 `bitcoind_rpc_port`。** 请把它们移入 `ldk_chain_sync.config` 并设置 `mode: "BlockSync"`，或者干脆不用它们，改为传入 `mode: "TransactionSync"` 和 `config.indexer_url`。 +- **`UnlockRequest.indexer_url` 现在是必填项**（此前可选且可为 null）。无论选择哪种链同步模式，RGB 转移都会用到它。 + +## SDK v0.1.17 **兼容的 API：** 最新 Maker API · RLN (RGB Lightning Node) API **v0.8.0** @@ -103,17 +125,17 @@ description: "KaleidoSDK 的版本历史：每个版本的新增功能、破坏 - `ListUnspentsRequest` 现在要求 `settled_only`。RLN 0.7.1 会拒绝旧的只带 `{skip_sync}` 的请求体，返回 `HTTP 400 "Failed to deserialize the JSON body into the target type"`。便捷方法 `list_unspents()` 默认使用 `settled_only=False`；直接构造请求的调用方必须自行设置该字段。 - `POST /sendasset` 已重命名为 `POST /sendrgb`（`SendAssetRequest`/`SendAssetResponse` → `SendRgbRequest`/`SendRgbResponse`）。 - + 这里省略了 0.1.6–0.1.8 版本；完整内容请查看 SDK 仓库中的 [CHANGELOG](https://github.com/kaleidoswap/kaleido-sdk/blob/master/CHANGELOG.md)。 - + ## SDK v0.1.5 **兼容的 API：** 最新 Maker API 与最新 RLN API - + 本条目描述的是 0.1.5 发布时的接口面。下面列出的基于订单的交换方法以及 `waitForSwapCompletion` 后来在 **0.1.13** 中被移除 —— 迁移路径请参见该版本条目。 - + ### 包含内容 @@ -152,7 +174,7 @@ description: "KaleidoSDK 的版本历史：每个版本的新增功能、破坏 **状态：** 稳定。v1 没有计划中的破坏性变更。 -Maker API 的接口端点分组请参见 [Maker API 兼容性](/cn/sdk/maker-api-compatibility)，节点侧的接口面请参见 [RLN API 兼容性](/cn/sdk/rln-api-compatibility)。线上环境及其 WebSocket URL 列在 [快速开始](/cn/sdk/getting-started#available-environments) 中。 +Maker API 的接口端点分组请参见 [Maker API 兼容性](/cn/sdk/maker-api-compatibility)，节点侧的接口面请参见 [RLN API 兼容性](/cn/sdk/rln-api-compatibility)。线上环境及其 WebSocket URL 列在[安装](/cn/sdk/installation#available-environments)中。 --- diff --git a/mintlify-docs/cn/sdk/error-handling.mdx b/mintlify-docs/cn/sdk/error-handling.mdx deleted file mode 100644 index c9086aa..0000000 --- a/mintlify-docs/cn/sdk/error-handling.mdx +++ /dev/null @@ -1,372 +0,0 @@ ---- -title: "SDK 错误处理" -sidebarTitle: "错误处理" -description: "借助 KaleidoSDK 的异常层级处理错误：各类错误的含义、HTTP 状态码映射、可重试性判断与重试模式，以及排查集成问题的思路" ---- - -## 错误层级结构 - -两个 SDK 使用几乎完全一致的错误类层级。所有错误都继承自 `KaleidoError`： - -``` -KaleidoError (基类) -├── APIError (HTTP 400-599) -│ └── RateLimitError (HTTP 429，仅 TypeScript) -├── RateLimitError (HTTP 429，Python —— 直接继承 KaleidoError) -├── NetworkError (连接问题) -├── ValidationError (HTTP 400, 422) -├── TimeoutError (HTTP 408, 504) -├── WebSocketError (WebSocket 问题) -├── NotFoundError (HTTP 404) -├── ConfigError (配置问题) -├── SwapError (交换操作失败) -├── NodeNotConfiguredError (节点未配置) -├── QuoteExpiredError (报价已过期) -└── InsufficientBalanceError (余额不足) -``` - -有一处差异需要注意：在 TypeScript 中 `RateLimitError` 继承 `APIError`，而在 Python 中它直接继承 `KaleidoError` —— Python 里的 `except APIError` 处理块捕获不到速率限制错误。 - -## 基类错误：KaleidoError - -所有 SDK 错误都继承 `KaleidoError`，并带有以下属性： - -| 属性 | 类型 | 说明 | -|----------|------|-------------| -| `code` | `string` | 供程序化处理使用的错误码 | -| `message` | `string` | 可读的错误信息 | -| `statusCode` / `status_code` | `number?` | HTTP 状态码（如适用） | -| `details` | `string?` | 额外的错误细节 | -| `isRetryable()` / `is_retryable()` | `boolean` | 该错误是否可以安全重试 | - - -```typescript TypeScript -import { KaleidoError } from 'kaleido-sdk'; - -try { - await client.maker.listPairs(); -} catch (error) { - if (error instanceof KaleidoError) { - console.log(`Code: ${error.code}`); - console.log(`Message: ${error.message}`); - console.log(`Status: ${error.statusCode}`); - console.log(`Retryable: ${error.isRetryable()}`); - } -} -``` - -```python Python -from kaleido_sdk import KaleidoError - -try: - await client.maker.list_pairs() -except KaleidoError as e: - print(f"Code: {e.code}") - print(f"Message: {e}") - print(f"Status: {e.status_code}") - print(f"Retryable: {e.is_retryable()}") -``` - - -## 各个错误类 - -### APIError - -在发生 HTTP 错误（状态码 400-599）时抛出。 - - -```typescript TypeScript -import { APIError } from 'kaleido-sdk'; -// 属性：code='API_ERROR'、statusCode、message、details -``` - -```python Python -from kaleido_sdk import APIError -# 属性：code='API_ERROR'、status_code、response_body -``` - - -### RateLimitError - -超出速率限制（HTTP 429）时抛出。在 TypeScript 中继承 `APIError`；在 Python 中直接继承 `KaleidoError`。 - - -```typescript TypeScript -import { RateLimitError } from 'kaleido-sdk'; -// 额外属性：retryAfter?: number（秒） - -try { /* ... */ } catch (error) { - if (error instanceof RateLimitError) { - console.log(`Retry after: ${error.retryAfter} seconds`); - } -} -``` - -```python Python -from kaleido_sdk import RateLimitError -# 额外属性：retry_after: int | None - -try: - ... -except RateLimitError as e: - print(f"Retry after: {e.retry_after} seconds") -``` - - -### NetworkError - -在出现网络连接问题（DNS 解析失败、连接被拒等）时抛出。 - -始终可重试（`isRetryable()` 返回 `true`）。 - -### ValidationError - -在校验失败（HTTP 400、422）时抛出。包含对 FastAPI 校验错误的解析。 - -### TimeoutError - -在请求超时（HTTP 408、504）时抛出。 - -始终可重试。 - -### WebSocketError - -在 WebSocket 连接或通信出错时抛出。 - -### NotFoundError - -在资源不存在（HTTP 404）时抛出。 - -### ConfigError - -在 SDK 配置有问题（例如 URL 无效）时抛出。 - -### SwapError - -在交换操作失败时抛出。 - - -```typescript TypeScript -import { SwapError } from 'kaleido-sdk'; -// 额外属性：swapId?: string - -try { /* ... */ } catch (error) { - if (error instanceof SwapError) { - console.log(`Swap failed: ${error.swapId}`); - } -} -``` - -```python Python -from kaleido_sdk import SwapError -# 额外属性：swap_id: str | None -``` - - -### NodeNotConfiguredError - -当在未配置 `node_url` 的情况下执行 RLN 节点操作时，由 Python SDK 抛出。TypeScript 在未提供 `nodeUrl` 却调用 `client.rln.*` 方法时，改为抛出 `ConfigError`（"Node API not configured. Provide \"nodeUrl\" when creating the client."）。 - - -```typescript TypeScript -import { ConfigError } from 'kaleido-sdk'; - -try { - await client.rln.getNodeInfo(); -} catch (error) { - if (error instanceof ConfigError) { - console.log('Configure nodeUrl to use RLN operations'); - } -} -``` - -```python Python -from kaleido_sdk import NodeNotConfiguredError - -try: - await client.rln.get_node_info() -except NodeNotConfiguredError: - print("Configure node_url to use RLN operations") -``` - - -### QuoteExpiredError - -在尝试使用已过期的报价时抛出。 - -### InsufficientBalanceError - -在余额不足以完成所请求的操作时抛出。 - - -```typescript TypeScript -import { InsufficientBalanceError } from 'kaleido-sdk'; -// 属性：requiredAmount: number、availableAmount: number、asset?: string - -try { /* ... */ } catch (error) { - if (error instanceof InsufficientBalanceError) { - console.log(`Need: ${error.requiredAmount}, Have: ${error.availableAmount}`); - } -} -``` - -```python Python -from kaleido_sdk import InsufficientBalanceError -# 属性：required_amount、available_amount、asset - -try: - ... -except InsufficientBalanceError as e: - print(f"Need: {e.required_amount}, Have: {e.available_amount}") -``` - - -## 完整的错误处理 {#comprehensive-error-handling} - - -```typescript TypeScript -import { - KaleidoError, - APIError, - NetworkError, - ValidationError, - TimeoutError, - NotFoundError, - QuoteExpiredError, - ConfigError, - InsufficientBalanceError, - RateLimitError, -} from 'kaleido-sdk'; - -try { - const quote = await client.maker.getQuote({ /* ... */ }); - const swap = await client.maker.initSwap({ /* ... */ }); -} catch (error) { - if (error instanceof QuoteExpiredError) { - // 获取新报价并重试 - } else if (error instanceof InsufficientBalanceError) { - console.log(`Need ${error.requiredAmount}, have ${error.availableAmount}`); - } else if (error instanceof ValidationError) { - console.log(`Invalid request: ${error.message}`); - } else if (error instanceof RateLimitError) { - // 等待后重试 - await new Promise(r => setTimeout(r, (error.retryAfter ?? 5) * 1000)); - } else if (error instanceof NotFoundError) { - console.log('Resource not found'); - } else if (error instanceof TimeoutError) { - console.log('Request timed out, retrying...'); - } else if (error instanceof NetworkError) { - console.log('Network issue, check connectivity'); - } else if (error instanceof ConfigError) { - console.log('Node not configured'); - } else if (error instanceof APIError) { - console.log(`API error (${error.statusCode}): ${error.message}`); - } else if (error instanceof KaleidoError) { - console.log(`SDK error [${error.code}]: ${error.message}`); - } -} -``` - -```python Python -from kaleido_sdk import ( - KaleidoError, - APIError, - NetworkError, - ValidationError, - TimeoutError, - NotFoundError, - QuoteExpiredError, - NodeNotConfiguredError, - InsufficientBalanceError, - RateLimitError, - PairQuoteRequest, - SwapRequest, -) -import asyncio - -try: - quote = await client.maker.get_quote(PairQuoteRequest(...)) - swap = await client.maker.init_swap(SwapRequest(...)) -except QuoteExpiredError: - # 获取新报价并重试 - pass -except InsufficientBalanceError as e: - print(f"Need {e.required_amount}, have {e.available_amount}") -except ValidationError as e: - print(f"Invalid request: {e}") -except RateLimitError as e: - await asyncio.sleep(e.retry_after or 5) -except NotFoundError: - print("Resource not found") -except TimeoutError: - print("Request timed out, retrying...") -except NetworkError: - print("Network issue, check connectivity") -except NodeNotConfiguredError: - print("Node not configured") -except APIError as e: - print(f"API error ({e.status_code}): {e}") -except KaleidoError as e: - print(f"SDK error [{e.code}]: {e}") -``` - - -## 重试模式 {#retry-patterns} - -使用 `isRetryable()` 实现自动重试： - - -```typescript TypeScript -async function withRetry(fn: () => Promise, maxRetries = 3): Promise { - for (let attempt = 0; attempt < maxRetries; attempt++) { - try { - return await fn(); - } catch (error) { - if (error instanceof KaleidoError && error.isRetryable() && attempt < maxRetries - 1) { - const delay = Math.pow(2, attempt) * 1000; - await new Promise(r => setTimeout(r, delay)); - continue; - } - throw error; - } - } - throw new Error('Max retries exceeded'); -} - -const pairs = await withRetry(() => client.maker.listPairs()); -``` - -```python Python -import asyncio - -async def with_retry(fn, max_retries=3): - for attempt in range(max_retries): - try: - return await fn() - except KaleidoError as e: - if e.is_retryable() and attempt < max_retries - 1: - delay = 2 ** attempt - await asyncio.sleep(delay) - continue - raise - raise RuntimeError("Max retries exceeded") - -pairs = await with_retry(lambda: client.maker.list_pairs()) -``` - - -## HTTP 错误映射 - -SDK 通过 `mapHttpError` / `map_http_error` 自动把 HTTP 错误映射为带类型的异常： - -| HTTP 状态码 | 错误类 | 是否可重试 | -|------------|-------------|-----------| -| 400, 422 | `ValidationError` | 否 —— 请求本身就有问题 | -| 404 | `NotFoundError` | 否 | -| 408, 504 | `TimeoutError` | 是，始终可重试 | -| 429 | `RateLimitError` | TypeScript：可以，等待 `retryAfter` 之后重试。Python：`is_retryable()` 返回 `False` —— 需要你自己按 `retry_after` 退避 | -| 500, 502, 503 | `APIError` | 是 —— 服务端故障可能自行恢复 | -| 其他 4xx | `APIError` | 否 | -| 网络故障 | `NetworkError` | 是，始终可重试 | - -不要把这张表硬编码进你自己的重试逻辑，而应调用 `isRetryable()` / `is_retryable()` —— 它精确编码了这些规则，并会随映射关系的演进保持正确。 diff --git a/mintlify-docs/cn/sdk/examples.mdx b/mintlify-docs/cn/sdk/examples.mdx index 3779af8..2a282c7 100644 --- a/mintlify-docs/cn/sdk/examples.mdx +++ b/mintlify-docs/cn/sdk/examples.mdx @@ -59,7 +59,7 @@ const client = KaleidoClient.create({ baseUrl: 'https://api.signet.kaleidoswap.com', }); -client.maker.enableWebSocket('wss://api.signet.kaleidoswap.com/ws/my-client-id'); +client.maker.enableWebSocket('wss://api.signet.kaleidoswap.com/api/v1/market/ws/my-client-id'); const stop = await client.maker.streamQuotesByTicker( 'BTC', @@ -81,7 +81,7 @@ client = KaleidoClient.create( base_url="https://api.signet.kaleidoswap.com" ) -client.maker.enable_websocket("wss://api.signet.kaleidoswap.com/ws/my-client-id") +client.maker.enable_websocket("wss://api.signet.kaleidoswap.com/api/v1/market/ws/my-client-id") stop = await client.maker.stream_quotes_by_ticker( "BTC", diff --git a/mintlify-docs/cn/sdk/faq.mdx b/mintlify-docs/cn/sdk/faq.mdx index 2ab215f..f477973 100644 --- a/mintlify-docs/cn/sdk/faq.mdx +++ b/mintlify-docs/cn/sdk/faq.mdx @@ -8,7 +8,7 @@ description: "关于 KaleidoSDK 的常见问题：语言选择、maker 与 RLN - 看你的技术栈。两者都是独立实现，类型都由同一份 [OpenAPI 规范](https://github.com/kaleidoswap/specs)生成，因此 API 结构、子客户端和错误层级在两者之间几乎完全一致 —— 少数差异（速率限制处理、节点缺失错误）已在[错误处理](/cn/sdk/error-handling)中说明。本文档中的每个示例都同时给出两种语言。 + 看你的技术栈。两者都是独立实现，类型都由同一份 [OpenAPI 规范](https://github.com/kaleidoswap/specs)生成，因此 API 结构、子客户端和错误层级在两者之间几乎完全一致 —— 少数差异（速率限制处理、节点缺失错误）已在[故障排查](/cn/sdk/troubleshooting#error-reference)中说明。本文档中的每个示例都同时给出两种语言。 运行环境要求：TypeScript 需要 **Node.js 18+**，Python 需要 **Python 3.10+**。Rust 核心正在开发中。 @@ -39,7 +39,7 @@ description: "关于 KaleidoSDK 的常见问题：语言选择、maker 与 RLN - **signet** —— `https://api.signet.kaleidoswap.com`，条件贴近真实环境，是上主网前的最佳选择 - 把它作为 `baseUrl` / `base_url` 传入即可；`/api/v1` 由 SDK 自动追加。完整列表见[可用环境](/cn/sdk/getting-started#available-environments)。 + 把它作为 `baseUrl` / `base_url` 传入即可；`/api/v1` 由 SDK 自动追加。完整列表见[可用环境](/cn/sdk/installation#available-environments)。 @@ -79,25 +79,27 @@ description: "关于 KaleidoSDK 的常见问题：语言选择、maker 与 RLN 所有 SDK 异常都继承 `KaleidoError`，因此只捕获这一个类型就能覆盖整个层级。每个错误都提供 `isRetryable()` / `is_retryable()`，用来判断重试是否安全 —— 不要盲目重试，因为有些失败无论重试多少次都不会成功。 - 完整的错误层级和带退避的重试模式见[错误处理](/cn/sdk/error-handling)，如何将其融入生产级客户端见[最佳实践](/cn/sdk/best-practices)。 + 完整的错误层级和带退避的重试模式见[故障排查](/cn/sdk/troubleshooting#error-reference)，如何将其融入生产级客户端见[最佳实践](/cn/sdk/best-practices)。 ## 获取帮助 -如果遇到的是报错而不是疑问，请查阅[故障排查](/cn/sdk/troubleshooting)。其他情况请通过下面你偏好的渠道反馈问题，并附上： +如果遇到的是报错而不是疑问，请查阅[故障排查](/cn/sdk/troubleshooting)；上游文档与相关链接见[更多资源](/cn/sdk/additional-resources)。 + +其他情况请通过下面你偏好的渠道反馈问题，并附上： 1. SDK 版本（`getVersion()` / `get_version()`） 2. 语言与运行时版本（Node.js / Python） 3. 错误信息与堆栈跟踪 4. 可复现问题的最小代码 -5. 运行环境（regtest / signet / 主网） +5. 运行环境（signet / 主网） 向社区提问。 - + 在相应的仓库中报告缺陷。 diff --git a/mintlify-docs/cn/sdk/getting-started.mdx b/mintlify-docs/cn/sdk/getting-started.mdx index 56a0697..f47bb8f 100644 --- a/mintlify-docs/cn/sdk/getting-started.mdx +++ b/mintlify-docs/cn/sdk/getting-started.mdx @@ -1,52 +1,12 @@ --- -title: "KaleidoSDK 快速上手" +title: "KaleidoSDK：快速上手" sidebarTitle: "快速上手" -description: "在 TypeScript 或 Python 中安装并配置 KaleidoSDK，了解客户端、接口端点与环境设置，几分钟内获取你的第一笔交换报价。" +description: "在 TypeScript 或 Python 中创建第一个 KaleidoSDK 客户端，访问 maker 与节点两个子客户端，用几行代码获取一笔交换报价。" --- -`kaleido-sdk`（TypeScript）和 `kaleido_sdk`（Python）由同一份 Maker API 与 RGB Lightning Node 规范生成，并在其上封装了手写客户端： +这是从「装好依赖包」到「拿到第一笔报价」的完整路径。如果你还没有安装 SDK，请先看[安装](/cn/sdk/installation)。 -- `client.maker` 对应 KaleidoSwap 的市场、交换和 LSPS1 接口端点 -- `client.rln` 对应 RGB Lightning Node 的钱包、通道、支付和交换接口端点 - - - 要确认哪个 SDK 版本对应哪个 API 版本，请参阅 [Maker API 兼容性](/cn/sdk/maker-api-compatibility) 和 [RLN API 兼容性](/cn/sdk/rln-api-compatibility)。 - - -## 安装 - - -```bash npm -npm install kaleido-sdk -``` - -```bash pnpm -pnpm add kaleido-sdk -``` - -```bash yarn -yarn add kaleido-sdk -``` - -```bash pip -pip install kaleido-sdk -``` - - -### 环境要求 - - - - - Node.js 18 或更高版本 - - 推荐 TypeScript 5.x - - - - Python 3.10 或更高版本 - - 运行时依赖会自动安装 - - - -## 基础设置 +## 基础设置 {#basic-setup} ```typescript TypeScript @@ -76,102 +36,9 @@ print(f"Found {len(assets.assets)} assets") `KaleidoClient.create()` 在两个 SDK 中都是同步方法。创建客户端时不要使用 `await`。 -## 配置 - -### TypeScript - -`KaleidoClient.create()` 接收一个 `KaleidoConfig` 对象： - -```typescript -import { KaleidoClient, LogLevel } from 'kaleido-sdk'; - -const client = KaleidoClient.create({ - baseUrl: 'https://api.signet.kaleidoswap.com', - nodeUrl: 'http://localhost:3001', - apiKey: process.env.KALEIDO_API_KEY, - timeout: 30, - logLevel: LogLevel.INFO, -}); -``` - -支持的配置字段： - -- `baseUrl?`：Maker API 基础 URL，默认为 `https://api.signet.kaleidoswap.com` -- `nodeUrl?`：RGB Lightning Node 地址 -- `apiKey?`：可选的 API key -- `nodeApiKey?`：可选的 bearer token，用于需要认证的 RLN 节点请求 -- `timeout?`：请求超时时间（秒） -- `logLevel?`：SDK 日志级别 -- `logger?`：自定义日志实现 +`create()` 能接收的全部字段列在[配置](/cn/sdk/installation#configuration)中。 -### Python - -`KaleidoClient.create()` 接收关键字参数： - -```python -import logging -from kaleido_sdk import KaleidoClient - -client = KaleidoClient.create( - base_url="https://api.signet.kaleidoswap.com", - node_url="http://localhost:3001", - api_key=None, - timeout=30.0, - max_retries=3, - cache_ttl=60, - log_level=logging.INFO, -) -``` - -Python 支持相同的连接设置，并额外提供： - -- `max_retries`：HTTP 客户端的重试次数上限 -- `cache_ttl`：缓存 TTL（秒） -- `log_level`：标准 Python 日志级别 - -## 环境变量 - -SDK 不会自动加载环境变量，但示例中使用了以下名称，作为约定也很实用： - -| 变量 | 常见用途 | -|----------|-------------| -| `KALEIDO_API_URL` | Maker API 基础 URL | -| `KALEIDO_NODE_URL` | RGB Lightning Node 地址 | -| `KALEIDO_API_KEY` | API key | - - -```typescript TypeScript -import { KaleidoClient } from 'kaleido-sdk'; - -const client = KaleidoClient.create({ - baseUrl: process.env.KALEIDO_API_URL || 'https://api.signet.kaleidoswap.com', - nodeUrl: process.env.KALEIDO_NODE_URL, - apiKey: process.env.KALEIDO_API_KEY, -}); -``` - -```python Python -import os -from kaleido_sdk import KaleidoClient - -client = KaleidoClient.create( - base_url=os.environ.get("KALEIDO_API_URL", "https://api.signet.kaleidoswap.com"), - node_url=os.environ.get("KALEIDO_NODE_URL"), - api_key=os.environ.get("KALEIDO_API_KEY"), -) -``` - - -## 可用环境 {#available-environments} - -将 API URL 作为 `baseUrl` / `base_url` 传入即可，SDK 会自行拼接 `/api/v1` 路径。在测试网络上无需 API key。 - -| 环境 | API URL | WebSocket URL | 状态 | -|-------------|---------|---------------|--------| -| **signet** | `https://api.signet.kaleidoswap.com` | `wss://api.signet.kaleidoswap.com/ws/{id}` | 已上线（默认） | -| **主网** | `https://api.kaleidoswap.com` | `wss://api.kaleidoswap.com/ws/{id}` | 即将上线 | - -## 子客户端架构 +## 子客户端架构 {#sub-client-architecture} ```typescript TypeScript @@ -225,7 +92,7 @@ else: ``` -## 第一笔报价 +## 第一笔报价 {#first-quote} ```typescript TypeScript @@ -265,3 +132,5 @@ print(quote.rfq_id) print(quote.price) ``` + +报价确认无误之后，[如何交换](/cn/sdk/how-to-swap)会完整走一遍原子交换流程。 diff --git a/mintlify-docs/cn/sdk/how-to-swap.mdx b/mintlify-docs/cn/sdk/how-to-swap.mdx index ec01a5b..bde211f 100644 --- a/mintlify-docs/cn/sdk/how-to-swap.mdx +++ b/mintlify-docs/cn/sdk/how-to-swap.mdx @@ -1,5 +1,5 @@ --- -title: "使用 SDK 创建原子交换" +title: "如何使用 KaleidoSDK 进行交换" sidebarTitle: "如何交换" description: "用 KaleidoSDK 创建并执行比特币原子交换：从询价、初始化、白名单授权到执行与结算跟踪，逐步走通多协议交换的完整流程" --- @@ -182,20 +182,3 @@ print(status.swap.status if status.swap else None) 如果某笔转移待处理的时间超出预期，`client.rln.refreshTransfers()` / `refresh_transfers()` 可以推进待处理的 RGB 转移，而 `client.rln.listSwaps()` 能让你看到节点自身的视图。各类失败情形见 [故障排查](/cn/sdk/troubleshooting#swap-issues)。 - -## 后续步骤 - - - - 异常层级结构，以及围绕每一步的重试模式。 - - - 底层 HTLC 流程，逐个接口端点讲解，并附时序图。 - - - 流式接收实时报价，而不必逐条请求。 - - - `client.maker` 与 `client.rln` 上的全部方法。 - - diff --git a/mintlify-docs/cn/sdk/installation.mdx b/mintlify-docs/cn/sdk/installation.mdx new file mode 100644 index 0000000..3495779 --- /dev/null +++ b/mintlify-docs/cn/sdk/installation.mdx @@ -0,0 +1,146 @@ +--- +title: "KaleidoSDK：安装" +sidebarTitle: "安装" +description: "在 TypeScript 或 Python 中安装 KaleidoSDK：环境要求、客户端配置字段、环境变量，以及可用的 API 环境。" +--- + +`kaleido-sdk`（TypeScript）和 `kaleido_sdk`（Python）由同一份 Maker API 与 RGB Lightning Node 规范生成，并在其上封装了手写客户端： + +- `client.maker` 对应 KaleidoSwap 的市场、交换和 LSPS1 接口端点 +- `client.rln` 对应 RGB Lightning Node 的钱包、通道、支付和交换接口端点 + +两者从同一个代码仓库发布并共用版本号，因此同一个版本在两种语言中的行为完全一致。 + + + 要确认哪个 SDK 版本对应哪个 API 版本，请参阅 [Maker API 兼容性](/cn/sdk/maker-api-compatibility) 和 [RLN API 兼容性](/cn/sdk/rln-api-compatibility)。 + + +## 安装依赖包 {#install-the-package} + + +```bash npm +npm install kaleido-sdk +``` + +```bash pnpm +pnpm add kaleido-sdk +``` + +```bash yarn +yarn add kaleido-sdk +``` + +```bash pip +pip install kaleido-sdk +``` + + +### 环境要求 {#requirements} + + + + - Node.js 18 或更高版本 + - 推荐 TypeScript 5.x + + + - Python 3.10 或更高版本 + - 运行时依赖会自动安装 + + + +## 配置 {#configuration} + +### TypeScript + +`KaleidoClient.create()` 接收一个 `KaleidoConfig` 对象： + +```typescript +import { KaleidoClient, LogLevel } from 'kaleido-sdk'; + +const client = KaleidoClient.create({ + baseUrl: 'https://api.signet.kaleidoswap.com', + nodeUrl: 'http://localhost:3001', + apiKey: process.env.KALEIDO_API_KEY, + timeout: 30, + logLevel: LogLevel.INFO, +}); +``` + +支持的配置字段： + +- `baseUrl?`：Maker API 基础 URL，默认为 `https://api.signet.kaleidoswap.com` +- `nodeUrl?`：RGB Lightning Node 地址 +- `apiKey?`：可选的 API key +- `nodeApiKey?`：可选的 bearer token，用于需要认证的 RLN 节点请求 +- `timeout?`：请求超时时间（秒） +- `logLevel?`：SDK 日志级别 +- `logger?`：自定义日志实现 + +### Python + +`KaleidoClient.create()` 接收关键字参数： + +```python +import logging +from kaleido_sdk import KaleidoClient + +client = KaleidoClient.create( + base_url="https://api.signet.kaleidoswap.com", + node_url="http://localhost:3001", + api_key=None, + timeout=30.0, + max_retries=3, + cache_ttl=60, + log_level=logging.INFO, +) +``` + +Python 支持相同的连接设置，并额外提供： + +- `max_retries`：HTTP 客户端的重试次数上限 +- `cache_ttl`：缓存 TTL（秒） +- `log_level`：标准 Python 日志级别 + +## 环境变量 {#environment-variables} + +SDK 不会自动加载环境变量，但示例中使用了以下名称，作为约定也很实用： + +| 变量 | 常见用途 | +|----------|-------------| +| `KALEIDO_API_URL` | Maker API 基础 URL | +| `KALEIDO_NODE_URL` | RGB Lightning Node 地址 | +| `KALEIDO_API_KEY` | API key | + + +```typescript TypeScript +import { KaleidoClient } from 'kaleido-sdk'; + +const client = KaleidoClient.create({ + baseUrl: process.env.KALEIDO_API_URL || 'https://api.signet.kaleidoswap.com', + nodeUrl: process.env.KALEIDO_NODE_URL, + apiKey: process.env.KALEIDO_API_KEY, +}); +``` + +```python Python +import os +from kaleido_sdk import KaleidoClient + +client = KaleidoClient.create( + base_url=os.environ.get("KALEIDO_API_URL", "https://api.signet.kaleidoswap.com"), + node_url=os.environ.get("KALEIDO_NODE_URL"), + api_key=os.environ.get("KALEIDO_API_KEY"), +) +``` + + +## 可用环境 {#available-environments} + +将 API URL 作为 `baseUrl` / `base_url` 传入即可，SDK 会自行拼接 `/api/v1` 路径。在测试网络上无需 API key。 + +| 环境 | 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}` | 即将上线 | + +装好依赖包之后，请继续阅读[快速上手](/cn/sdk/getting-started)，创建客户端并获取第一笔报价。 diff --git a/mintlify-docs/cn/sdk/introduction.mdx b/mintlify-docs/cn/sdk/introduction.mdx index f9aa68e..adf7e61 100644 --- a/mintlify-docs/cn/sdk/introduction.mdx +++ b/mintlify-docs/cn/sdk/introduction.mdx @@ -1,15 +1,11 @@ --- -title: "多协议比特币交换 SDK" +title: "KaleidoSDK" sidebarTitle: "总览" description: "使用 KaleidoSDK 构建比特币钱包与交易应用。提供 TypeScript 与 Python 客户端，支持跨比特币分层协议的非托管原子交换，类型安全、接口一致。" --- KaleidoSDK（`kaleido-sdk`）让钱包开发者能够集成跨比特币、Lightning 和 RGB 的非托管原子交换。它是 [KaleidoSwap 非托管 DEX](https://kaleidoswap.com) 的底层实现，并提供 TypeScript 与 Python 两个版本。 -## 官方 SDK - -KaleidoSwap 同时提供 TypeScript 和 Python 官方 SDK。两者都是独立实现，类型均由同一份 OpenAPI 规范自动生成，从而保证完整的类型安全和一致的 API 设计。 - ## 架构 两个 SDK 采用相同的 API 设计，各自独立构建： @@ -47,10 +43,3 @@ KaleidoSwap 同时提供 TypeScript 和 Python 官方 SDK。两者都是独立 - **错误处理**：两个 SDK 都提供完整的异常层次结构 - **RGB 资产交易**：完整支持在 Lightning 和链上交易 RGB 资产 - **原子交换**：基于 HTLC 的交换，无需信任做市方 - -## 支持 - -需要帮助？可以查看： -- [GitHub Issues](https://github.com/kaleidoswap/kaleido-sdk/issues) -- [社区 Telegram](https://t.me/kaleidoswap) -- [支持邮箱](mailto:support@kaleidoswap.com) diff --git a/mintlify-docs/cn/sdk/maker-api-compatibility.mdx b/mintlify-docs/cn/sdk/maker-api-compatibility.mdx index a2ca413..3a2ca2d 100644 --- a/mintlify-docs/cn/sdk/maker-api-compatibility.mdx +++ b/mintlify-docs/cn/sdk/maker-api-compatibility.mdx @@ -1,17 +1,19 @@ --- -title: 'Maker API 兼容性' +title: 'Maker API' description: "了解 KaleidoSDK 版本如何跟随 Maker API 演进，以及 SDK 通过 client.maker 暴露的接口端点分组和调用方式。" --- +Maker API 由 KaleidoSwap 托管，通过网络直接访问，你自己不需要运行任何基础设施。它提供市场数据与报价、做市方一侧的原子交换协调，以及 LSPS1 通道订购。 + ## 兼容性 SDK 始终跟随**最新的 Maker API** 版本：这一侧不需要管理版本配对关系。请让两者都保持更新，以便使用受支持的接口端点，并第一时间用上新功能。 -要查看当前的 Maker API 版本和更新内容，请参阅 [Maker API 更新日志](https://github.com/kaleidoswap/maker-api/releases) 或你自己的 API 文档。 +当前的 Maker API 接口详情见 [API 参考](/cn/api-reference/introduction)。SDK 类型所基于的 OpenAPI 规范发布在 [kaleidoswap/specs](https://github.com/kaleidoswap/specs)。 -## API 接口端点分组 +## 接口端点分组 Maker API 提供以下接口端点分组： @@ -25,46 +27,4 @@ Maker API 提供以下接口端点分组： 基于订单的交换接口端点（`/api/v1/swaps/orders/*`）已下线，对应的 SDK 方法在 **0.1.13** 中被移除。请改用原子交换流程 —— 参阅 [如何交换](/cn/sdk/how-to-swap)。 -## 使用 Maker API - -在 SDK 中使用 Maker API 功能： - - -```typescript TypeScript -import { KaleidoClient, Layer } from 'kaleido-sdk'; - -const client = KaleidoClient.create({ - baseUrl: 'https://api.signet.kaleidoswap.com', -}); - -// 通过 client.maker 访问 Maker API -const assets = await client.maker.listAssets(); -const pairs = await client.maker.listPairs(); -const quote = await client.maker.getQuote({ - from_asset: { asset_id: 'BTC', layer: Layer.BTC_LN, amount: 100000 }, - to_asset: { asset_id: 'USDT', layer: Layer.RGB_LN }, -}); -``` - -```python Python -import asyncio -from kaleido_sdk import KaleidoClient, Layer, PairQuoteRequest, SwapLegInput - -async def main(): - client = KaleidoClient.create( - base_url="https://api.signet.kaleidoswap.com" - ) - - # 通过 client.maker 访问 Maker API - assets = await client.maker.list_assets() - pairs = await client.maker.list_pairs() - quote = await client.maker.get_quote( - PairQuoteRequest( - from_asset=SwapLegInput(asset_id="BTC", layer=Layer.BTC_LN, amount=100000), - to_asset=SwapLegInput(asset_id="USDT", layer=Layer.RGB_LN), - ) - ) - -asyncio.run(main()) -``` - +所有分组都通过 `client.maker` 访问，除了客户端上的 `baseUrl` 之外不需要任何额外配置。第一次调用见[快速上手](/cn/sdk/getting-started)，全部方法见[客户端参考](/cn/sdk/api-reference)。 diff --git a/mintlify-docs/cn/sdk/nwc.mdx b/mintlify-docs/cn/sdk/nwc.mdx index 46ec29b..ca23f17 100644 --- a/mintlify-docs/cn/sdk/nwc.mdx +++ b/mintlify-docs/cn/sdk/nwc.mdx @@ -12,9 +12,9 @@ description: '通过 Nostr Wallet Connect（NIP-47）与 kaleido-sdk/nwc 客户 在标准 NIP-47 钱包方法之外，该客户端还增加了 **`rln*` RGB 闪电扩展方法**，让你能够通过同一条加密的 NWC 通道读取余额、管理 RGB 资产，并在远端节点上创建发票。 - + 传输层采用 **NIP-44** 端到端加密；当钱包服务未声明支持 NIP-44 时，会回退到 **NIP-04**。 - + ## 建立连接 diff --git a/mintlify-docs/cn/sdk/rln-api-compatibility.mdx b/mintlify-docs/cn/sdk/rln-api-compatibility.mdx index 3aee2b7..b3a5d1f 100644 --- a/mintlify-docs/cn/sdk/rln-api-compatibility.mdx +++ b/mintlify-docs/cn/sdk/rln-api-compatibility.mdx @@ -1,10 +1,12 @@ --- -title: 'RLN API 兼容性' +title: 'RLN API' description: "查看每个 KaleidoSDK 版本对应的 RGB Lightning Node (RLN) API 版本，以及 client.rln 暴露的节点侧接口端点分类。" --- import { sdkVersion, rlnApiVersion } from "/snippets/versions.mdx"; +RLN（RGB Lightning Node）API 由你所配置的 RGB Lightning Node 直接提供，支持钱包操作、闪电通道管理以及节点间的交换协调。 + ## 兼容性 **SDK v{sdkVersion}** 基于 **RGB Lightning Node API v{rlnApiVersion}** 生成（即 `kaleidoswap/rgb-lightning-node` 分支）。 @@ -15,11 +17,7 @@ SDK 会自动支持最新发布的 RLN API。请始终保持 SDK 与 RGB Lightni 要查看最新的 RLN API 变更和更新内容，请参阅 [RGB Lightning Node](https://github.com/kaleidoswap/rgb-lightning-node) 或你自己的节点文档。 -## RLN API 总览 - -RLN（RGB Lightning Node）API 由你所配置的 RGB Lightning Node 直接提供，支持钱包操作、闪电通道管理以及节点间的交换协调。 - -## RLN API 分类 +## 分类 | 分类 | 用途 | 示例 | |---|---|---| @@ -29,52 +27,4 @@ RLN（RGB Lightning Node）API 由你所配置的 RGB Lightning Node 直接提 | **Payments** | 支付执行 | 支付发票、协调交换、节点间交易 | | **Node Info** | 节点状态与配置 | 公钥、同步状态、能力信息 | -## 访问 RLN 操作 - -在使用 RLN 操作前，请确认已配置好节点： - - -```typescript TypeScript -import { KaleidoClient } from 'kaleido-sdk'; - -const client = KaleidoClient.create({ - baseUrl: 'https://api.signet.kaleidoswap.com', - nodeUrl: 'http://localhost:3001', // RLN 操作必需 -}); - -// 检查节点是否已配置 -if (client.hasNode()) { - // 通过 client.rln 访问 RLN API - const nodeInfo = await client.rln.getNodeInfo(); - const balance = await client.rln.getBtcBalance(); - const channels = await client.rln.listChannels(); -} else { - console.log('Node not configured - RLN operations unavailable'); -} -``` - -```python Python -import asyncio -from kaleido_sdk import KaleidoClient - - -async def main(): - client = KaleidoClient.create( - base_url="https://api.signet.kaleidoswap.com", - node_url="http://localhost:3001" # RLN 操作必需 - ) - - # 检查节点是否已配置 - if client.has_node(): - # 通过 client.rln 访问 RLN API - node_info = await client.rln.get_node_info() - balance = await client.rln.get_btc_balance() - channels = await client.rln.list_channels() - else: - print("Node not configured - RLN operations unavailable") - - -if __name__ == "__main__": - asyncio.run(main()) -``` - +这些分类都通过 `client.rln` 访问，前提是客户端配置了 `nodeUrl` / `node_url`：若未配置，TypeScript 会抛出 `ConfigError`，Python 会抛出 `NodeNotConfiguredError`。配置步骤与节点检查见[快速上手](/cn/sdk/getting-started)，全部方法见[客户端参考](/cn/sdk/api-reference)。 diff --git a/mintlify-docs/cn/sdk/troubleshooting.mdx b/mintlify-docs/cn/sdk/troubleshooting.mdx index 0ccfed6..d1d0cef 100644 --- a/mintlify-docs/cn/sdk/troubleshooting.mdx +++ b/mintlify-docs/cn/sdk/troubleshooting.mdx @@ -1,7 +1,7 @@ --- title: "KaleidoSDK 故障排查" sidebarTitle: "故障排查" -description: "定位并解决 KaleidoSDK 的常见问题：连接失败、版本不匹配、交换报错等，每一项都给出可直接照做的排查步骤" +description: "定位并解决 KaleidoSDK 的常见问题：连接失败、版本不匹配、交换报错等，每一项都给出可直接照做的排查步骤，并附完整的错误层级与重试模式" --- ## 安装问题 @@ -27,11 +27,13 @@ description: "定位并解决 KaleidoSDK 的常见问题：连接失败、版本 4. 试试：`pip install kaleido-sdk --no-cache-dir` - - **症状：** `Cannot find module 'kaleido-sdk'` 或 `ModuleNotFoundError` + + **症状：** `Cannot find module 'kaleido-sdk'`、`ERR_REQUIRE_ESM`、import 语法报错，或 `ModuleNotFoundError` + + **原因（TypeScript）：** SDK 仅支持 ESM，而旧的 `"moduleResolution": "node"` 设置会忽略包的 `exports` 字段。 **解决办法：** - - **TypeScript：** SDK 仅支持 ESM，因此 `tsconfig.json` 需要 `"moduleResolution": "bundler"`、`"node16"` 或 `"nodenext"`。旧的 `"node"` 设置会忽略包的 `exports` 字段，无法解析该模块 + - **TypeScript：** 在 `tsconfig.json` 中将 `"moduleResolution"` 设为 `"bundler"`、`"node16"` 或 `"nodenext"`，并让项目本身使用 ESM —— 在 `package.json` 中设置 `"type": "module"`，或使用 `.mts` 扩展名。如果必须继续使用 CommonJS，请改用动态导入：`const sdk = await import('kaleido-sdk')` - **Python：** 确认你处在正确的虚拟环境中 - 确认包已安装：`npm list kaleido-sdk` 或 `pip show kaleido-sdk` @@ -128,7 +130,7 @@ description: "定位并解决 KaleidoSDK 的常见问题：连接失败、版本 **解决办法：** 1. 增大超时时间：`timeout: 60`（单位为秒） 2. 检查网络连通性 - 3. 用 `error.isRetryable()` 实现重试逻辑 —— 参见[错误处理](/cn/sdk/error-handling#retry-patterns) + 3. 用 `error.isRetryable()` 实现重试逻辑 —— 参见[重试模式](#retry-patterns) @@ -246,10 +248,10 @@ description: "定位并解决 KaleidoSDK 的常见问题：连接失败、版本 -## TypeScript 特有问题 +## 语言相关问题 {#language-specific-issues} - + **症状：** TypeScript 编译器报告类型不兼容 **解决办法：** @@ -261,21 +263,7 @@ description: "定位并解决 KaleidoSDK 的常见问题：连接失败、版本 3. 如果启用了 strict 模式，可能需要显式处理 `undefined` - - **症状：** `ERR_REQUIRE_ESM` 或 import 语法报错 - - **解决办法：** - 1. SDK 仅支持 ESM。请确认你的项目使用 ESM： - - 在 `package.json` 中设置 `"type": "module"` - - 或者使用 `.mts` 文件扩展名 - 2. 如果必须使用 CommonJS，请改用动态导入：`const sdk = await import('kaleido-sdk')` - - - -## Python 特有问题 - - - + **症状：** 解析 API 响应时 Pydantic 抛出 `ValidationError` **解决办法：** @@ -284,7 +272,7 @@ description: "定位并解决 KaleidoSDK 的常见问题：连接失败、版本 3. API 可能已经更新 —— 试着升级 SDK：`pip install --upgrade kaleido-sdk` - + **症状：** `httpx.ConnectError` 或类似报错 **解决办法：** @@ -294,94 +282,232 @@ description: "定位并解决 KaleidoSDK 的常见问题：连接失败、版本 -## 调试 +## 错误参考 {#error-reference} -### 开启详细日志 +两个 SDK 使用几乎完全一致的错误类层级。所有错误都继承自 `KaleidoError`，因此只要捕获它，就不会有 SDK 错误漏网： - -```typescript TypeScript -// 使用 Node.js 自带的调试能力 -// 设置环境变量：NODE_DEBUG=http -// 或者用浏览器 DevTools 检查网络请求 +``` +KaleidoError (基类) +├── APIError (HTTP 400-599) +│ └── RateLimitError (HTTP 429，仅 TypeScript) +├── RateLimitError (HTTP 429，Python —— 直接继承 KaleidoError) +├── NetworkError (连接问题) +├── ValidationError (HTTP 400, 422) +├── TimeoutError (HTTP 408, 504) +├── WebSocketError (WebSocket 问题) +├── NotFoundError (HTTP 404) +├── ConfigError (配置问题) +├── SwapError (交换操作失败) +├── NodeNotConfiguredError (节点未配置) +├── QuoteExpiredError (报价已过期) +└── InsufficientBalanceError (余额不足) ``` -```python Python -import logging +写处理逻辑之前，有两处差异值得注意： -# 为 httpx 开启调试日志 -logging.basicConfig(level=logging.DEBUG) -logging.getLogger("httpx").setLevel(logging.DEBUG) -logging.getLogger("websockets").setLevel(logging.DEBUG) -``` - +- **`RateLimitError`** 在 TypeScript 中继承 `APIError`，而在 Python 中直接继承 `KaleidoError` —— Python 里的 `except APIError` 处理块**捕获不到**速率限制错误。 +- **未配置节点 URL** 在 Python 中抛出 `NodeNotConfiguredError`，而在 TypeScript 中抛出 `ConfigError`（"Node API not configured. Provide \"nodeUrl\" when creating the client."）。 -### 校验配置 +### KaleidoError 属性 {#kaleidoerror-properties} + +无论具体是哪个类，每个错误都带有以下属性： + +| 属性 | 类型 | 说明 | +|----------|------|-------------| +| `code` | `string` | 供程序化处理使用的错误码 | +| `message` | `string` | 便于阅读的错误信息 | +| `statusCode` / `status_code` | `number?` | HTTP 状态码（如适用） | +| `details` | `string?` | 额外的错误详情 | +| `isRetryable()` / `is_retryable()` | `boolean` | 该错误是否可以安全重试 | + +### 错误类 {#error-classes} + +| 类 | 什么时候抛出 | 额外属性 | +|-------|-------------|-----------------------| +| `APIError` | HTTP 400-599 | TypeScript：`details`。Python：`response_body` | +| `RateLimitError` | HTTP 429 | `retryAfter` / `retry_after` —— 需等待的秒数 | +| `NetworkError` | DNS 解析失败、连接被拒绝等连接性故障 | — | +| `ValidationError` | HTTP 400、422 —— 包含解析后的 FastAPI 校验详情 | — | +| `TimeoutError` | HTTP 408、504 | — | +| `WebSocketError` | WebSocket 连接或通信失败 | — | +| `NotFoundError` | HTTP 404 | — | +| `ConfigError` | SDK 配置无效，例如 URL 格式错误。在 TypeScript 中，未配置 `nodeUrl` 时调用 `client.rln.*` 也会抛出它 | — | +| `SwapError` | 交换操作失败 | `swapId` / `swap_id` | +| `NodeNotConfiguredError` | 仅 Python —— 未配置 `node_url` 时调用 `client.rln.*` | — | +| `QuoteExpiredError` | 在 `expires_at` 之后使用 `rfq_id` | — | +| `InsufficientBalanceError` | 余额不足以完成该操作 | `requiredAmount` / `required_amount`、`availableAmount` / `available_amount`、`asset` | + +哪些错误可以安全重试，取决于状态码而不是类本身 —— 见下方的 [HTTP 错误映射](#http-error-mapping)。 + +### HTTP 错误映射 {#http-error-mapping} + +SDK 通过 `mapHttpError` / `map_http_error` 自动把 HTTP 错误映射为带类型的异常： + +| HTTP 状态码 | 错误类 | 是否可重试 | +|------------|-------------|-----------| +| 400, 422 | `ValidationError` | 否 —— 请求本身就有问题 | +| 404 | `NotFoundError` | 否 | +| 408, 504 | `TimeoutError` | 是，始终可重试 | +| 429 | `RateLimitError` | TypeScript：可以，等待 `retryAfter` 之后重试。Python：`is_retryable()` 返回 `False` —— 需要你自己按 `retry_after` 退避 | +| 500, 502, 503 | `APIError` | 是 —— 服务端故障可能自行恢复 | +| 其他 4xx | `APIError` | 否 | +| 网络故障 | `NetworkError` | 是，始终可重试 | + +不要把这张表硬编码进你自己的重试逻辑，而应调用 `isRetryable()` / `is_retryable()` —— 它精确编码了这些规则，并会随映射关系的演进保持正确。 + +### 完整的错误处理 {#comprehensive-error-handling} + +从最具体的类向最一般的类逐层分支，并以 `KaleidoError` 收尾，以免有错误漏网。子类必须写在父类之前 —— 在 TypeScript 中 `RateLimitError` 属于 `APIError`，如果 `APIError` 分支写在前面，它会把前者一并吞掉。 ```typescript TypeScript -const client = KaleidoClient.create({ - baseUrl: 'https://api.signet.kaleidoswap.com', - nodeUrl: 'http://localhost:3001', -}); +import { KaleidoError, RateLimitError, QuoteExpiredError } from 'kaleido-sdk'; -console.log(`Has node: ${client.hasNode()}`); - -// 测试连通性 try { - const assets = await client.maker.listAssets(); - console.log(`API connected: ${assets.assets.length} assets`); + const quote = await client.maker.getQuote({ /* ... */ }); + const swap = await client.maker.initSwap({ /* ... */ }); } catch (error) { - console.error('API connection failed:', error); -} - -if (client.hasNode()) { - try { - const nodeInfo = await client.rln.getNodeInfo(); - console.log(`Node connected: ${nodeInfo.pubkey}`); - } catch (error) { - console.error('Node connection failed:', error); + if (error instanceof QuoteExpiredError) { + // 重新获取报价后重试 + } else if (error instanceof RateLimitError) { + await new Promise(r => setTimeout(r, (error.retryAfter ?? 5) * 1000)); + } else if (error instanceof KaleidoError && error.isRetryable()) { + // 退避后重试 —— 见下方的重试模式 + } else if (error instanceof KaleidoError) { + console.error(`SDK error [${error.code}]: ${error.message}`); } } ``` ```python Python -client = KaleidoClient.create( - base_url="https://api.signet.kaleidoswap.com", - node_url="http://localhost:3001", +import asyncio + +from kaleido_sdk import ( + KaleidoError, + PairQuoteRequest, + QuoteExpiredError, + RateLimitError, + SwapRequest, ) -print(f"Has node: {client.has_node()}") - try: - assets = await client.maker.list_assets() - print(f"API connected: {len(assets.assets)} assets") -except Exception as e: - print(f"API connection failed: {e}") - -if client.has_node(): - try: - node_info = await client.rln.get_node_info() - print(f"Node connected: {node_info.pubkey}") - except Exception as e: - print(f"Node connection failed: {e}") + quote = await client.maker.get_quote(PairQuoteRequest(...)) + swap = await client.maker.init_swap(SwapRequest(...)) +except QuoteExpiredError: + # 重新获取报价后重试 + pass +except RateLimitError as e: + await asyncio.sleep(e.retry_after or 5) +except KaleidoError as e: + if e.is_retryable(): + # 退避后重试 —— 见下方的重试模式 + pass + else: + print(f"SDK error [{e.code}]: {e}") ``` +只有当某个类的处理方式确实不同时，才值得为它单独开一个分支 —— 比如用 `InsufficientBalanceError` 展示差额，用 `ValidationError` 指出出错的字段。其余情况已经被 `isRetryable()` 判断和兵底分支覆盖。 + +### 重试模式 {#retry-patterns} + +使用 `isRetryable()` 实现自动重试： + + +```typescript TypeScript +async function withRetry(fn: () => Promise, maxRetries = 3): Promise { + for (let attempt = 0; attempt < maxRetries; attempt++) { + try { + return await fn(); + } catch (error) { + if (error instanceof KaleidoError && error.isRetryable() && attempt < maxRetries - 1) { + const delay = Math.pow(2, attempt) * 1000; + await new Promise(r => setTimeout(r, delay)); + continue; + } + throw error; + } + } + throw new Error('Max retries exceeded'); +} + +const pairs = await withRetry(() => client.maker.listPairs()); +``` + +```python Python +import asyncio + +async def with_retry(fn, max_retries=3): + for attempt in range(max_retries): + try: + return await fn() + except KaleidoError as e: + if e.is_retryable() and attempt < max_retries - 1: + delay = 2 ** attempt + await asyncio.sleep(delay) + continue + raise + raise RuntimeError("Max retries exceeded") + +pairs = await with_retry(lambda: client.maker.list_pairs()) +``` + + +## 调试 + +### 开启详细日志 + +Python 可以直接使用底层 `httpx` 与 `websockets` 的日志器： + +```python +import logging + +logging.basicConfig(level=logging.DEBUG) +logging.getLogger("httpx").setLevel(logging.DEBUG) +logging.getLogger("websockets").setLevel(logging.DEBUG) +``` + +TypeScript 没有针对传输层的同类开关。创建客户端时传入更低的 `logLevel` 可以拿到 SDK 自身的输出 —— 见[配置](/cn/sdk/installation#configuration)；要看具体的请求，请使用 `NODE_DEBUG=http`，或浏览器 DevTools 的网络面板。 + +### 校验配置 + +当调用失败但还定位不到具体错误时，按顺序检查这四项： + + + + 在浏览器中打开 `/api/v1/market/assets`。`/api/v1` 由 SDK 自动追加，因此配置值本身不能包含它。 + + + + 只要缺少 `nodeUrl` / `node_url`，`client.hasNode()` / `client.has_node()` 就返回 `false`，所有 `client.rln.*` 调用都会因此失败。 + + + + `client.rln.getNodeInfo()` / `get_node_info()` 能返回 pubkey，就证明节点既可达又已解锁。 + + + + signet 的 `baseUrl` 配上主网节点，得到的是令人困惑的空结果，而不是一个清晰的错误。 + + + ## 获取帮助 -如果是疑问而不是报错，请查阅[常见问题](/cn/sdk/faq)。其他情况请通过下面你偏好的渠道反馈问题，并附上： +如果是疑问而不是报错，请查阅[常见问题](/cn/sdk/faq)；上游文档与相关链接见[更多资源](/cn/sdk/additional-resources)。 + +其他情况请通过下面你偏好的渠道反馈问题，并附上： 1. SDK 版本（`getVersion()` / `get_version()`） 2. 语言与运行时版本（Node.js / Python） 3. 错误信息与堆栈跟踪 4. 可复现问题的最小代码 -5. 运行环境（regtest / signet / 主网） +5. 运行环境（signet / 主网） 向社区提问。 - + 在相应的仓库中报告缺陷。 diff --git a/mintlify-docs/cn/sdk/utilities.mdx b/mintlify-docs/cn/sdk/utilities.mdx index d96b79e..28ed85b 100644 --- a/mintlify-docs/cn/sdk/utilities.mdx +++ b/mintlify-docs/cn/sdk/utilities.mdx @@ -4,7 +4,7 @@ sidebarTitle: "工具函数" description: "KaleidoSDK 提供的辅助函数：金额换算、精度处理，以及跨比特币与比特币二层资产的资产与交易对映射" --- -## 金额换算 +## 金额换算 {#amount-conversion} ### `parseRawAmount` / `parse_raw_amount` @@ -257,7 +257,7 @@ console.log(getVersion()); // "0.1.0" —— 返回的是硬编码值，并非 ```python Python from kaleido_sdk import get_version -print(get_version()) # "0.1.17" +print(get_version()) # "0.1.18" ``` diff --git a/mintlify-docs/cn/sdk/websocket.mdx b/mintlify-docs/cn/sdk/websocket.mdx index 391af7f..7f2207a 100644 --- a/mintlify-docs/cn/sdk/websocket.mdx +++ b/mintlify-docs/cn/sdk/websocket.mdx @@ -19,18 +19,18 @@ SDK 提供 WebSocket 支持，用于实时报价推送。WebSocket 客户端会 ```typescript TypeScript -const ws = client.maker.enableWebSocket('wss://api.signet.kaleidoswap.com/ws/my-client-id'); +const ws = client.maker.enableWebSocket('wss://api.signet.kaleidoswap.com/api/v1/market/ws/my-client-id'); ``` ```python Python -ws = client.maker.enable_websocket("wss://api.signet.kaleidoswap.com/ws/my-client-id") +ws = client.maker.enable_websocket("wss://api.signet.kaleidoswap.com/api/v1/market/ws/my-client-id") ``` URL 中包含一个客户端 ID，用于会话跟踪。`enableWebSocket` 方法返回一个 `WSClient` 实例。 -本页示例使用 signet，它同时也是 SDK 的默认环境。请让 WebSocket URL 与 `baseUrl` 指向的环境保持一致。参阅 [可用环境](/cn/sdk/getting-started#available-environments)。 +本页示例使用 signet，它同时也是 SDK 的默认环境。请让 WebSocket URL 与 `baseUrl` 指向的环境保持一致。参阅 [可用环境](/cn/sdk/installation#available-environments)。 ## 高层接口 @@ -170,7 +170,7 @@ for route in routes: ```typescript TypeScript -const ws = client.maker.enableWebSocket('wss://api.signet.kaleidoswap.com/ws/my-client'); +const ws = client.maker.enableWebSocket('wss://api.signet.kaleidoswap.com/api/v1/market/ws/my-client'); await ws.connect(); console.log(`Connected: ${ws.isConnected()}`); @@ -180,7 +180,7 @@ ws.disconnect(); ``` ```python Python -ws = client.maker.enable_websocket("wss://api.signet.kaleidoswap.com/ws/my-client") +ws = client.maker.enable_websocket("wss://api.signet.kaleidoswap.com/api/v1/market/ws/my-client") await ws.connect() print(f"Connected: {ws.is_connected()}") @@ -324,7 +324,7 @@ WebSocket 使用 JSON 消息协议： | `amount` | number | 以最小单位表示的原始数量 | | `precision` | number | 该资产的小数位数（例如 BTC 为 8） | -## 最佳实践 +## 最佳实践 {#best-practices} diff --git a/mintlify-docs/cn/whats-kaleidoswap/additional-resources.mdx b/mintlify-docs/cn/whats-kaleidoswap/additional-resources.mdx new file mode 100644 index 0000000..152f22c --- /dev/null +++ b/mintlify-docs/cn/whats-kaleidoswap/additional-resources.mdx @@ -0,0 +1,123 @@ +--- +title: "KaleidoSwap 扩展资源" +sidebarTitle: "扩展资源" +description: "KaleidoSwap 全部链接汇总：源码仓库、各比特币层级的协议参考、集成标准、测试网络以及支持渠道。" +--- + +本页把各产品标签页中的链接汇总到了一起。每个产品也保留了自己的一份，只覆盖该接入方式所需的内容：[桌面应用](/cn/desktop-app/support/additional-resources)、[浏览器扩展](/cn/extensions/kaleidoswap-extension/additional-resources)、[AI 工具](/cn/ai-tools/additional-resources)和 [KaleidoSDK](/cn/sdk/additional-resources)。 + +## 源码仓库 + +KaleidoSwap 所有开源的部分都在 [KaleidoSwap 组织](https://github.com/kaleidoswap)下。浏览器扩展是例外：在封闭 Beta 期间，它的仓库是私有的。 + + + + 桌面应用的源码、发布版本和问题追踪。 + + + TypeScript 与 Python 两套实现的源码、发布版本和问题追踪。 + + + 在终端里运行节点并交易的命令行客户端。 + + + 自主代理，包含它的仪表盘、状态 API，以及每轮循环加载的 `skills/` 目录。 + + + 本地端引擎：分层漏斗、recipe 引擎、工具契约、记忆与检索，以及评测框架。 + + + 把所有领域收拢到一个连接背后的 MCP 网关。 + + + SDK 和钱包工具所驱动的节点。这是 KaleidoSwap 的分支；[上游项目](https://github.com/RGB-Tools/rgb-lightning-node)由 RGB Tools 维护。 + + + 所有客户端生成 API 类型所依据的 OpenAPI 规范，这也是各语言请求与响应结构保持一致的原因。 + + + +## 协议文档 + +KaleidoSwap 钱包派生账户所在的各个层级，以及各自的上游参考。 + + + + 客户端验证与资产接口，涵盖无需节点的 RGB-L1 以及闪电网络上的 RGB。 + + + 基于状态链的转账、闪电收发，以及 Spark 账户背后的代币。 + + + VTXO、进出场（boarding/offboarding），以及 Arkade 账户背后的批量结算模型。 + + + L-BTC 与 USDt 等发行资产背后的联邦侧链。 + + + +## 集成标准 + +KaleidoSwap 向其他软件暴露的接口所遵循的规范。 + + + + 每个 KaleidoSwap [MCP 服务器](/cn/ai-tools/mcp-servers)都实现的工具协议。 + + + 闪电网络的浏览器 provider 标准，注入在 `window.webln`。 + + + 页面内的 Nostr 签名，注入在 `window.nostr`。 + + + 通过 `bunker://` 字符串、经由中继完成的 Nostr Connect 远程签名。 + + + KaleidoMind 用于 LLM、嵌入、语音转文字和文字转语音的本地端推理运行时。 + + + +这些浏览器 provider 如何暴露给网页，见 [DApp 连接](/cn/extensions/kaleidoswap-extension/dapp-connectivity)。 + +## 开发与测试 + + + + 获取 Signet 比特币，用于给节点充值和开测试通道。 + + + + 查看 signet 上的交易、区块与通道开启。 + + + +## 获取帮助 + +报错请先看[故障排查](/cn/whats-kaleidoswap/troubleshooting)，术语请看[术语表](/cn/whats-kaleidoswap/glossary)。每个产品在自己的「参考」分组下也各有一份 FAQ 和故障排查。 + +反馈问题时，请附上你使用的产品与版本、所在网络（Signet 或主网）、复现步骤，以及错误信息或截图。各产品页面还列出了值得附带的额外信息，比如日志文件位置和查看版本的命令。 + +| 产品 | 问题追踪 | +|---------|---------------| +| 桌面应用 | [desktop-app/issues](https://github.com/kaleidoswap/desktop-app/issues) | +| KaleidoSDK | [kaleido-sdk/issues](https://github.com/kaleidoswap/kaleido-sdk/issues) | +| KaleidoCLI | [kaleido-cli/issues](https://github.com/kaleidoswap/kaleido-cli/issues) | +| AI 工具 | 出问题的那个仓库：[kaleido-agent](https://github.com/kaleidoswap/kaleido-agent/issues)、[kaleido-mind](https://github.com/kaleidoswap/kaleido-mind/issues) 或 [kaleido-mcp](https://github.com/kaleidoswap/kaleido-mcp/issues) | +| 浏览器扩展 | Beta 期间仓库私有，请通过 Telegram 或邮件反馈 | + + + + 向社区提问。 + + + 问题、拉取请求和全部源码。 + + + 紧急问题的直接支持。 + + + + + **绝不要把私钥或助记词分享给任何人，包括技术支持人员。** 正规的技术支持永远不会索取这些信息。 + diff --git a/mintlify-docs/cn/whats-kaleidoswap/glossary.mdx b/mintlify-docs/cn/whats-kaleidoswap/glossary.mdx index 9393e39..4b5e5aa 100644 --- a/mintlify-docs/cn/whats-kaleidoswap/glossary.mdx +++ b/mintlify-docs/cn/whats-kaleidoswap/glossary.mdx @@ -386,6 +386,6 @@ description: "跨比特币分层协议交易所需的核心术语：原子交换 --- - + 本术语表会持续更新。如果你遇到这里没有列出的陌生术语，欢迎通过我们的[支持渠道](/cn/desktop-app/support/additional-resources)告诉我们。 - + diff --git a/mintlify-docs/cn/whats-kaleidoswap/introduction.mdx b/mintlify-docs/cn/whats-kaleidoswap/introduction.mdx index 450e2a5..26fc85a 100644 --- a/mintlify-docs/cn/whats-kaleidoswap/introduction.mdx +++ b/mintlify-docs/cn/whats-kaleidoswap/introduction.mdx @@ -105,7 +105,7 @@ KaleidoSwap 正在为比特币原生原子交换构建流动性层，让任何 TypeScript 使用 `npm install kaleido-sdk`，Python 使用 `pip install kaleido-sdk`。 - [安装指南 →](/cn/sdk/getting-started) + [安装指南 →](/cn/sdk/installation) diff --git a/mintlify-docs/cn/whats-kaleidoswap/quickstart.mdx b/mintlify-docs/cn/whats-kaleidoswap/quickstart.mdx index 424392c..7063215 100644 --- a/mintlify-docs/cn/whats-kaleidoswap/quickstart.mdx +++ b/mintlify-docs/cn/whats-kaleidoswap/quickstart.mdx @@ -31,9 +31,9 @@ description: "几分钟完成 KaleidoSwap 配置并做出首笔非托管交换 - [Windows](https://github.com/kaleidoswap/desktop-app/releases) - [Linux（AppImage）](https://github.com/kaleidoswap/desktop-app/releases) - + 安装前请务必验证二进制文件签名。[了解方法 →](/cn/desktop-app/getting-started/verify-binaries) - + @@ -97,9 +97,9 @@ description: "几分钟完成 KaleidoSwap 配置并做出首笔非托管交换 3. 点击**加载已解压的扩展程序**，选择解压后的文件夹 4. 将 KaleidoSwap 图标固定到工具栏 - + 完整流程（含校验和验证）见：[安装指南 →](/cn/extensions/kaleidoswap-extension/installation) - + diff --git a/mintlify-docs/cn/whats-kaleidoswap/troubleshooting.mdx b/mintlify-docs/cn/whats-kaleidoswap/troubleshooting.mdx index 5daf131..444f011 100644 --- a/mintlify-docs/cn/whats-kaleidoswap/troubleshooting.mdx +++ b/mintlify-docs/cn/whats-kaleidoswap/troubleshooting.mdx @@ -1,560 +1,69 @@ --- -title: "KaleidoSwap 故障排查" -sidebarTitle: "故障排查" -description: "排查桌面应用、浏览器扩展、API 与 SDK 上的常见问题：从连接失败、交换卡住，到通道异常、资产不显示与钱包恢复，逐一给出症状与解决办法。" +title: "常见问题与故障排查" +description: "按产品查找答案：桌面应用、浏览器扩展、AI 工具和 SDK 各自的常见问题与故障排查页面，以及 API 的错误处理参考。" --- -## 桌面应用 - -### 安装与启动问题 - - - - **症状**：双击应用没有任何反应，或弹出错误提示。 - - **解决办法**： - 1. **macOS**：检查应用是否被 Gatekeeper 拦截 - - 打开「系统偏好设置 → 安全性与隐私」(System Preferences → Security & Privacy) - - 如果看到与 KaleidoSwap 相关的提示，点击「仍要打开」(Open Anyway) - - 2. **Windows**：以管理员身份运行 - - 右键点击应用 → 以管理员身份运行 (Run as Administrator) - - 确认 Windows Defender 没有隔离该文件 - - 3. **Linux**：检查可执行权限 - ```bash - chmod +x kaleidoswap-desktop - ``` - - 4. 检查系统要求： - - 至少 4GB 内存 - - 500MB 可用磁盘空间 - - 受支持的操作系统版本（macOS 12+、Windows 10+ 64 位、Ubuntu 22.04+） - - - - **症状**：SHA256 校验和与公布的哈希不一致。 - - **解决办法**： - 1. 从官方 [GitHub releases](https://github.com/kaleidoswap/desktop-app/releases) 重新下载应用 - 2. 确认下载的是与你的平台匹配的文件 - 3. 使用稳定的网络下载（下载损坏会导致校验和不匹配） - 4. 确认你比对的是对应版本的校验和 - - 详细步骤见[二进制文件校验](/cn/desktop-app/getting-started/verify-binaries)指南。 - - - - **症状**：应用短暂打开后立即关闭，或弹出崩溃对话框。 - - **解决办法**： - 1. 查看日志文件： - - macOS：`~/Library/Logs/com.kaleidoswap.dev/` - - Windows：`%APPDATA%\com.kaleidoswap.dev\logs` - - Linux：`~/.local/share/com.kaleidoswap.dev/logs` - - 2. 常见原因： - - **配置文件损坏**：删除配置文件后重启 - - **端口冲突**：另一个应用占用了所需端口（9735、3001） - - **依赖缺失**：重新安装应用 - - 3. 如果崩溃持续出现，在联系支持或提交 GitHub issue 时，请附上上述目录中最新的日志文件。 - - - -### 节点与连接问题 - - - - **症状**：出现 LSP 连接相关的错误提示，或无法开通通道。 - - **解决办法**： - 1. **检查网络连接** - - 确认网络连接稳定 - - 尝试访问其他网站，确认连通性 - - 2. **核对 LSP URL** - - 默认值：`https://api.signet.kaleidoswap.com` - - 在「设置 → LSP 配置」(Settings → LSP Configuration) 中检查 - - 3. **防火墙 / VPN 问题** - - 临时关闭 VPN 进行测试 - - 在防火墙中放行 KaleidoSwap - - 需要开放的端口：9735（闪电网络 P2P）、3001（节点 API） - - 4. **检查 LSP 状态** - - 访问 LSP 的状态页面，或联系支持 - - 如有其他可用的 LSP，尝试切换 - - - - **症状**：区块链同步耗时数小时，或看起来卡住了。 - - **解决办法**： - 1. **属于正常现象**：初次同步可能需要 30 分钟到数小时，取决于： - - 你的网络速度 - - 系统的磁盘速度 - - 网络拥堵情况 - - 2. **查看同步进度**： - - 在界面中查看区块高度 - - 与当前网络高度对比 - - 3. **同步卡住时的排查**： - - 重启应用 - - 检查可用磁盘空间（至少需要 10GB） - - 清空对等节点列表并重新连接 - - 确认防火墙没有拦截 P2P 连接 - - - - **症状**：提示「没有连接对等节点」(No peers connected)，或对等节点数量过少。 - - **解决办法**： - 1. **先等一会儿**：对等节点发现可能需要几分钟 - - 2. **检查网络设置**： - - 确认路由器已启用 UPnP（用于接受入向连接） - - 若 UPnP 不可用，手动转发 9735 端口 - - 3. **引导节点**： - - 应用应会自动连接引导节点 - - 若未连接，检查你的网络连接和防火墙 - - 4. **网络选择**： - - 确认你处于正确的网络（主网 / 测试网 / signet / regtest） - - 对等节点必须处于同一网络 - - - -### 钱包与资产问题 - - - - **症状**：预期有资金，但余额显示 0 或数值不对。 - - **解决办法**： - 1. **等待同步完成**：节点完全同步前不会显示余额 - 2. **确认网络正确**：确保你所在的网络就是资金所在的网络 - 3. **核对钱包恢复过程**：如果是从种子恢复的，确认使用的助记词正确 - 4. **区分资产余额与 BTC 余额**：在比特币视图和 RGB 资产视图之间切换查看 - 5. **刷新**：尝试重启应用 - - - - **症状**：密码无效，钱包始终处于锁定状态。 +每个产品都有各自的常见问题（面向疑问）和故障排查（面向报错）页面。请按你正在使用的产品选择。 - **解决办法**： - 1. **核对密码**：密码区分大小写 - 2. **大写锁定**：检查是否误开了 Caps Lock - 3. **键盘布局不同**：确认与设置密码时使用的键盘布局一致 - 4. **钱包恢复**：如果密码确实丢失，只能用助记词恢复钱包 - 5. **联系支持**：作为最后手段，带上钱包公钥联系支持（切勿分享私钥） - - - - **症状**：已收到资产，但钱包中看不到。 - - **解决办法**： - 1. **等待确认**：RGB 资产转移需要比特币确认 - 2. **导入交付包**：你可能需要手动导入 consignment 数据 - 3. **核对资产 ID**：确认你查看的是正确的资产 - 4. **刷新资产列表**：设置 → 资产 → 刷新 (Settings → Assets → Refresh) - 5. **确认发送方已完成转移**：联系发送方，确认对方已走完发送流程 - - - -### 通道操作 - - - - **症状**：通道订单失败或卡住。 - - **解决办法**： - 1. **查询订单状态**：用订单 ID 通过 API 查询，或联系支持 - - 2. **常见失败原因**： - - **资金不足**：需要覆盖通道金额加费用 - - **支付超时**：发票在支付前已过期 - - **参数无效**：检查通道大小的上下限 - - **LSP 不可用**：LSP 临时停机 - - 3. **退款流程**： - - 订单失败后，退款会自动打到你的退款地址 - - 退款可能需要 6 个以上确认才会显示 - - 4. **重试**： - - 等几分钟后再试 - - 如果已达上限，减小通道大小 - - 确认入向流动性充足 - - - - **症状**：通道存在，但无法收发支付。 - - **解决办法**： - 1. **等待确认**：通道需要区块链确认才会激活 - - 通常需要 3 到 6 个确认 - - 在通道详情中查看确认数 - - 2. **对等节点离线**：通道对端需要在线 - - 等待对端重新上线 - - 查看「最后在线」(Last Seen) 时间戳 - - 3. **通道储备金**：不能花到低于通道储备金的额度 - - 闪电通道要求保留一部分储备余额 - - 这是协议的正常行为 - - 4. **强制关闭**：如果通道彻底卡死，可以强制关闭 - - 这会在一段延迟后把资金退回链上 - - 只作为最后手段 - - - - **症状**：通道已开通，但 RGB 资产尚未交付。 - - **解决办法**： - 1. **属于正常延迟**：通过 keysend 交付资产可能需要几分钟 - - 系统内置了自动重试机制 - - 个别情况下可能长达 30 分钟 - - 2. **查看交付状态**： - - 订单详情中会显示资产交付状态 - - 状态流转：PENDING → IN_PROGRESS → COMPLETED - - 3. **手动重试**： - - 如有「重试交付」(Retry Delivery) 按钮，点击它 - - 4. **交付失败**： - - 带上订单 ID 联系 LSP 支持 - - 如果交付无法完成，可能可以退款 - - - -### 交易与交换 - - - - **症状**：交换未完成，或已过期。 - - **解决办法**： - 1. **报价过期**：询价报价的有效期很短 —— 默认约 60 秒，且每份报价都自带 `expires_at` - - 在过期前完成交换 - - 若已过期，重新请求报价 - - 2. **汇率变动**：市场汇率出现显著变化 - - 收到提示时接受新汇率 - - 或者取消并获得退款 - - 3. **支付路由失败**：闪电支付找不到路径 - - 尝试更小的金额 - - 开通更多通道以获得更多流动性 - - 稍后重试 - - 4. **交换卡住**： - - 查询交换状态：`POST /api/v1/swaps/atomic/status`（按支付哈希查询） - - 带上支付哈希联系支持寻求协助 - - - - **症状**：最终价格与预期不同。 - - **解决办法**： - 1. **核对报价细节**：仔细查看询价响应 - - `from_amount` 与 `to_amount` - - 已计入的费用 - - 资产的精度 - - 2. **费用结构**： - - 基础费用 + 浮动费用 - - 计费资产与精度 - - 报价中会显示总费用 - - 3. **精度混淆**： - - BTC 使用 8 位小数 - - USDT 通常使用 6 位小数 - - 资产精度的说明见术语表 - - 4. **滑点**： - - 市价单的价格可能小幅变动 - - 如果需要精确价格，使用限价单 - - +## 桌面应用 - - 交易失败、钱包恢复以及 LSP 连接相关的问题，见[桌面应用故障排查](/cn/desktop-app/support/troubleshooting)。 - + + + 钱包、通道、交换、费用与安全性。 + + + 启动、节点同步、通道与交换失败。 + + ## 浏览器扩展 -下面这些情况专门针对内测版的安装方式，以及各账户的支撑方式。 - -### 安装与更新 - - - - **症状**：`chrome://extensions` 拒绝该文件夹，或原本正常的扩展过一段时间后无法加载。 - - **解决办法**： - 1. **选对文件夹**：选择包含 `manifest.json` 的那个文件夹。如果压缩包里有 `dist` 目录，就选 `dist`。 - 2. **不要移动或删除解压后的文件夹**：浏览器每次都从该路径加载扩展。把它移到别的磁盘、重命名，或清空下载目录，都会让安装失效。 - 3. **先解压**：让浏览器指向解压后的文件夹，而不是 zip 文件。 - 4. **重新添加**：在 `chrome://extensions` 中移除出问题的卡片，然后重新加载该文件夹。你的钱包并不存放在那个文件夹里，因此这不会影响你的资金。 - - - - **症状**：你安装了更新的 zip，但扩展的行为仍与旧版本一致。 - - **解决办法**： - 1. 内测版本**不会自动更新** —— 没有商店条目来推送更新。 - 2. 解压新的 zip 之后，打开 `chrome://extensions`，在 KaleidoSwap 卡片上点击**重新加载** (Reload)。 - 3. 如果你解压到了**另一个文件夹**，请移除旧的已解压扩展，改为加载新文件夹 —— 否则浏览器会继续运行旧版本。 - 4. 在**设置 > 关于** (Settings > About) 中确认版本号。 - - - - **症状**：内测 zip 完全无法加载。 - - **解决办法**： - 1. 内测版面向**基于 Chromium 的浏览器**：Chrome、Brave、Edge、Opera。 - 2. 除非专门提供了 Firefox 版本，否则 **Firefox** 不在首轮内测范围内；**Safari** 目前也还不支持。 - 3. 必须先在 `chrome://extensions` 中打开**开发者模式** (Developer mode)，**加载已解压的扩展程序** (Load unpacked) 才会出现。 - 4. 只安装来自官方邀请或支持渠道的压缩包 —— 绝不要用转发来的副本。 - - - -### 账户与余额 - - - - **症状**：原本能看到 RGB 余额，连接 RGB 闪电节点后就不见了。 - - **说明**：无需节点的 **RGB-L1** 账户与 **RLN** 账户是 RGB 资产的两种*互斥*支撑方式。连接 RLN 会替换掉无需节点的那一种，因此你看到的是另一个账户 —— RGB-L1 的状态并没有丢失。 - - **解决办法**： - 1. 在**设置 > 账户 > RGB** (Settings > Accounts > RGB) 中断开 RLN，即可回到无需节点的 RGB-L1 支撑方式。 - 2. 决定你需要哪一种支撑方式：无需节点适用于比特币 L1 上的 RGB，RLN 适用于 RGB **闪电通道**以及基于做市方的交换。 - 3. 切换之前，确认你即将离开的那一种已经完成备份 —— RGB-L1 备份到云端（VSS）和本地文件，RLN 则备份到节点自身的备份材料。 - - - - **症状**：导入助记词后 Spark、Arkade 和 Liquid 的余额都回来了，但 RGB 资产没有。 - - **解决办法**： - 1. RGB-L1 状态**不是**从助记词派生的 —— 它由加密云端（VSS）备份恢复，而且只有在你于引导步骤中**明确同意**时才会恢复。跳过该提示就会把状态留在原处。 - 2. 重新导入钱包，并在恢复提示出现时接受它。 - 3. 如果你改用 RLN，RGB 状态必须从节点自身的备份材料恢复，而不是从扩展恢复。 - - - - **症状**：你用 `nsec1…` 密钥做了恢复，结果钱包是空的。 - - **解决办法**： - 1. Nostr 密钥**并不掌控资金**。导入它只会替换 Nostr 身份。 - 2. 恢复时始终使用 **BIP39 助记词** —— 派生 Spark、Arkade、Liquid 和 RGB-L1 账户的正是它。 - 3. 用助记词重新导入；之后可以在设置中再导入 Nostr 密钥。 - - - -### 交换与跨链桥 - - - - **症状**：交换界面拒绝了一个看起来你确实持有的金额。 - - **解决办法**： - 1. 金额输入受源资产的**可花费**余额限制，而不是总余额，因此你无法按超过钱包实际可发送的金额去询价。 - 2. 链上发送还会预留网络费用 —— **最大** (Max) 会自动把这部分算进去。 - 3. 确认余额位于所选路径实际使用的那个账户上；余额是按分层分别记账的。 - - - - **症状**：已报价的交换以失败告终，而不是以更差的汇率成交。 - - **解决办法**： - 1. 这是**滑点保护**在按预期工作：最小输出量由你设置的容忍度推导得出，一旦超出，交换会直接失败而不成交。 - 2. 重新询价 —— 报价会过期，汇率也可能已经变动。 - 3. 如果市场确实波动剧烈，可以调整滑点容忍度，或者减小金额。 - - - - **症状**：你在跨链桥进行中关闭了扩展，订单不再显示在界面上。 - - **解决办法**： - 1. 跨链桥订单会**以会话形式保存在本地**。重新打开跨链桥界面会恢复待处理的订单并继续跟踪，即便 service worker 已经重启过。 - 2. 已完成和已失败的订单会显示最终状态，并附上相关的交易引用。 - 3. 存入需要先在源链上确认 —— 在此期间订单会一直处于进行中状态。 - - - - - 节点连接、支付以及 DApp provider 相关的问题，见 [KaleidoSwap 扩展故障排查](/cn/extensions/kaleidoswap-extension/troubleshooting)。 - - -## API 与集成 - -### 认证与连接 - - - - **症状**：API 返回 401 状态码。 - - **解决办法**： - 1. **Bearer token**：确认认证 token 的发送格式正确 - ```http - Authorization: Bearer YOUR_TOKEN_HERE - ``` - - 2. **Token 过期**：token 可能已过期 —— 重新获取一个 - - 3. **接口端点不对**：确认使用了正确的 API 基础 URL - - signet（已上线）：`https://api.signet.kaleidoswap.com/api/v1` - - 主网：`https://api.kaleidoswap.com/api/v1` *（即将上线）* - - - - **症状**：API 返回 422 及校验错误。 - - **解决办法**： - 1. **检查请求体**：确认所有必填字段都已提供 - 2. **数据类型**：确认整数、字符串、布尔值的类型正确 - 3. **字段校验**：检查最小值 / 最大值和格式 - 4. **阅读错误详情**：响应中会指出哪些字段校验失败 - - 错误响应示例： - ```json - { - "detail": [ - { - "loc": ["body", "from_amount"], - "msg": "field required", - "type": "value_error.missing" - } - ] - } - ``` - - - - **症状**：浏览器以 CORS 错误拦截 API 请求。 - - **解决办法**： - 1. **改用后端调用**：从你的后端而不是前端发起 API 请求 - - 出于安全考虑，大多数接口端点都禁用了 CORS - - 基于浏览器的应用需要一个后端代理 - - 2. **开发期的临时办法**： - - 使用浏览器 CORS 插件（仅限开发环境） - - 把开发服务器配置成代理 - - 3. **生产环境**：始终使用服务端 API 调用 - - - -### 询价与订单问题 - - - - **症状**：使用询价 ID 时返回过期相关的错误。 - - **解决办法**： - 1. **检查 expires_at**：报价默认约 60 秒内有效；始终读取报价自带的 `expires_at`，不要假设一个固定时长 - 2. **重新请求报价**：再次调用 `/api/v1/market/quote` - 3. **加快集成流程**：尽量缩短从报价到创建订单之间的时间 - 4. **利用过期时间**：在界面上做一个显示剩余时间的倒计时 - - - - **症状**：订单停留在 PENDING_PAYMENT 或其他状态不再推进。 - - **解决办法**： - 1. **需要支付**：检查你是否还需要支付一张发票，或向某个地址转账 - 2. **查询支付状态**： - ```bash - POST /api/v1/lsps1/get_order - { - "order_id": "your-order-id" - } - ``` - - 3. **自动流转**：部分状态会自动推进 - - PENDING_PAYMENT → PAID（支付确认后） - - CHANNEL_OPENING → COMPLETED（通道开通后） - - 4. **超时**：订单未在时限内支付就会过期 - - 检查 `expires_at` 字段 - - 未支付的订单会自动过期并退款 - - - - - 完整的 HTTP 状态码列表、错误响应格式和重试策略，见 API 参考中的[错误处理](/cn/api-reference/error-handling)。 - - -## SDK - -两份 SDK 指南都同时覆盖 TypeScript 和 Python —— 每个示例都给出两种写法。按需选择： - - - SDK 会抛出哪些异常、如何捕获它们、重试模式，以及与 HTTP 状态码的对应关系。 + + 账户、恢复、受支持的浏览器与封闭测试。 - - - 针对安装失败、连接错误、WebSocket 问题以及各语言特有的坑，逐条给出症状与解决办法。 + + 连接、支付与扩展加载问题。 -**速查提示**： -- 捕获 `KaleidoError` —— 所有 SDK 异常都继承自它，`isRetryable()` / `is_retryable()` 会告诉你重试是否安全 -- 开启调试日志，查看完整的请求与响应细节 -- 检查运行时版本：Node.js 18+ / Python 3.10+ - -## 通用最佳实践 +## AI 工具 - - 大多数问题都能从日志文件中查出原因。排查时请开启调试日志。 + + MCP 服务器、KaleidoAgent、KaleidoMind 与各个 skill。 - - - 确认你所处的网络（主网、测试网、signet、regtest）与你的使用场景相符。 + + 工具调用失败、宿主配置与运行时报错。 + - - 使用最新版本的桌面应用和 SDK，以获得问题修复与功能改进。 - +## SDK - - 在主网动用真实资金之前，务必先在测试网上验证新的集成。 + + + 语言选择、子客户端、托管方式、网络与版本兼容。 + + + 安装失败、连接错误与交换问题。 -## 还需要帮助？ - -如果上述排查步骤没能解决你的问题： - - - - 每个产品都有自己的参考文档：[桌面应用故障排查](/cn/desktop-app/support/troubleshooting)、[KaleidoSwap 扩展故障排查](/cn/extensions/kaleidoswap-extension/troubleshooting)、[KaleidoSDK 故障排查](/cn/sdk/troubleshooting)，以及 [API 错误处理](/cn/api-reference/error-handling)。 - - - - 用搜索框在文档中查找具体主题。 - +## API 与集成 - - 到你所运行组件对应的仓库中，看看是否已有人报告过同样的问题。所有仓库都在 [KaleidoSwap 组织](https://github.com/kaleidoswap)下。 - + + + HTTP 状态码、错误响应格式与重试策略。 + + + 各类端点、鉴权，以及交换与 LSPS1 API。 + + - - 可通过以下方式联系我们： - - 邮箱：[support@kaleidoswap.com](mailto:support@kaleidoswap.com) - - Telegram：[https://t.me/kaleidoswap](https://t.me/kaleidoswap) - - GitHub Issues：在与你的配置相符的仓库中提交，例如[桌面应用](https://github.com/kaleidoswap/desktop-app/issues/new)、[KaleidoSDK](https://github.com/kaleidoswap/kaleido-sdk/issues/new) 或 [KaleidoCLI](https://github.com/kaleidoswap/kaleido-cli/issues/new)。 - - + + 上述每个页面的末尾都有「获取帮助」一节，列出了反馈问题时需要附上的信息，以及 Telegram、GitHub 和邮件渠道。 + - **绝不要把私钥或助记词分享给任何人，包括支持人员。** 正规的支持渠道永远不会索要这些信息。 + **切勿向任何人透露你的私钥或助记词，包括自称支持人员的人。** 正规的支持渠道绝不会索取这些信息。 diff --git a/mintlify-docs/desktop-app/channels/channel-backups.mdx b/mintlify-docs/desktop-app/channels/channel-backups.mdx index 906f1cc..7ad58c5 100644 --- a/mintlify-docs/desktop-app/channels/channel-backups.mdx +++ b/mintlify-docs/desktop-app/channels/channel-backups.mdx @@ -66,9 +66,9 @@ If you need to restore your wallet on a new device: Because the backup contains the complete node state, your channels resume operating normally after the restore — no mnemonic entry is required and no force-closes are triggered. - + The backup is encrypted with your node password. Without that password, the backup file cannot be decrypted or restored. - + --- diff --git a/mintlify-docs/desktop-app/support/additional-resources.mdx b/mintlify-docs/desktop-app/support/additional-resources.mdx index 794ae38..ebe6a4c 100644 --- a/mintlify-docs/desktop-app/support/additional-resources.mdx +++ b/mintlify-docs/desktop-app/support/additional-resources.mdx @@ -20,8 +20,37 @@ description: "Useful links for KaleidoSwap users and developers, including commu Get testnet Bitcoin for development and testing on Mutinynet. - - Join the community for support and discussions. + + + Check whether a deposit, channel open, or swap has confirmed on Signet. + + + +## Get Help + +Check [Troubleshooting](/desktop-app/support/troubleshooting) for errors and the [FAQ](/desktop-app/support/faq) for questions. + +For anything else, report a problem through your preferred channel from the options below, including: + +1. Your OS and version (macOS, Windows, or Linux) +2. KaleidoSwap Desktop App version +3. Node type (local or remote) and version +4. Steps to reproduce +5. Error messages or screenshots +6. Log files: + - macOS: `~/Library/Logs/com.kaleidoswap.dev/` + - Windows: `%APPDATA%\com.kaleidoswap.dev\logs` + - Linux: `~/.local/share/com.kaleidoswap.dev/logs` + + + + Ask the community. + + + Report a bug on the relevant repository. + + + Direct support for urgent issues. diff --git a/mintlify-docs/desktop-app/support/faq.mdx b/mintlify-docs/desktop-app/support/faq.mdx index dee806b..a978a80 100644 --- a/mintlify-docs/desktop-app/support/faq.mdx +++ b/mintlify-docs/desktop-app/support/faq.mdx @@ -97,7 +97,9 @@ description: "Answers to frequently asked questions about the KaleidoSwap Deskto ## Get Help -Check the [Troubleshooting](/desktop-app/support/troubleshooting) for errors rather than questions. For anything else, report a problem through your preferred channel from the options below, including: +Check the [Troubleshooting](/desktop-app/support/troubleshooting) for errors rather than questions, and [Additional Resources](/desktop-app/support/additional-resources) for upstream documentation and links. + +For anything else, report a problem through your preferred channel from the options below, including: 1. Your OS and version (macOS, Windows, or Linux) 2. KaleidoSwap Desktop App version @@ -113,7 +115,7 @@ Check the [Troubleshooting](/desktop-app/support/troubleshooting) for errors rat Ask the community. - + Report a bug on the relevant repository. diff --git a/mintlify-docs/desktop-app/support/settings.mdx b/mintlify-docs/desktop-app/support/settings.mdx index 6b5c7bc..58cf692 100644 --- a/mintlify-docs/desktop-app/support/settings.mdx +++ b/mintlify-docs/desktop-app/support/settings.mdx @@ -57,9 +57,9 @@ Dark mode is the only supported theme. Light mode was disabled to avoid inconsis ## Node Connection Settings - + These settings require a node restart to take effect. After saving, the app will prompt you to **Restart Node** so the new connection settings are applied. - + ### Node Connection String diff --git a/mintlify-docs/desktop-app/support/troubleshooting.mdx b/mintlify-docs/desktop-app/support/troubleshooting.mdx index ff71e84..0a8236f 100644 --- a/mintlify-docs/desktop-app/support/troubleshooting.mdx +++ b/mintlify-docs/desktop-app/support/troubleshooting.mdx @@ -1,11 +1,9 @@ --- title: "KaleidoSwap Desktop App Troubleshooting" sidebarTitle: "Troubleshooting" -description: "Fix failed trades, wallet restore, and LSP connection problems in the KaleidoSwap Desktop App, with step-by-step checks and links to the full support guide." +description: "Fix failed trades, wallet restore, and LSP connection problems in the KaleidoSwap Desktop App, with step-by-step checks and support channels." --- -Fixes for the problems Desktop App users hit most often. For installation, node sync, channel, and swap issues across every KaleidoSwap surface, see the [full troubleshooting guide](/whats-kaleidoswap/troubleshooting). - ## Trading @@ -50,8 +48,6 @@ Fixes for the problems Desktop App users hit most often. For installation, node 2. Verify the LSP URL — default is `https://api.mutinynet2.kaleidoswap.com/`, under Settings → Maker & LSP Settings 3. Check firewall/VPN settings; required ports are 9735 (Lightning P2P) and 3001 (node API) 4. Visit the LSP's status page, or switch to a different LSP if available - - See the [full troubleshooting guide](/whats-kaleidoswap/troubleshooting) for more connection issues, including node configuration and channel capacity problems. @@ -104,7 +100,9 @@ Fixes for the problems Desktop App users hit most often. For installation, node ## Get Help -Check the [FAQ](/desktop-app/support/faq) for questions rather than errors. For anything else, report a problem through your preferred channel from the options below, including: +Check the [FAQ](/desktop-app/support/faq) for questions rather than errors, and [Additional Resources](/desktop-app/support/additional-resources) for upstream documentation and links. + +For anything else, report a problem through your preferred channel from the options below, including: 1. Your OS and version (macOS, Windows, or Linux) 2. KaleidoSwap Desktop App version @@ -120,7 +118,7 @@ Check the [FAQ](/desktop-app/support/faq) for questions rather than errors. For Ask the community. - + Report a bug on the relevant repository. diff --git a/mintlify-docs/docs.json b/mintlify-docs/docs.json index cf54e34..ffaa910 100644 --- a/mintlify-docs/docs.json +++ b/mintlify-docs/docs.json @@ -39,7 +39,8 @@ "icon": "book", "pages": [ "whats-kaleidoswap/glossary", - "whats-kaleidoswap/troubleshooting" + "whats-kaleidoswap/troubleshooting", + "whats-kaleidoswap/additional-resources" ] } ] @@ -181,19 +182,20 @@ "icon": "flag", "pages": [ "sdk/introduction", + "sdk/installation", "sdk/getting-started" ] }, { - "group": "Version & Compatibility", - "icon": "check-double", + "group": "API Surfaces", + "icon": "layer-group", "pages": [ "sdk/maker-api-compatibility", "sdk/rln-api-compatibility" ] }, { - "group": "Core Reference", + "group": "Modules", "icon": "code", "pages": [ "sdk/api-reference", @@ -208,8 +210,7 @@ "pages": [ "sdk/how-to-swap", "sdk/examples", - "sdk/best-practices", - "sdk/error-handling" + "sdk/best-practices" ] }, { @@ -233,11 +234,12 @@ "icon": "flag", "pages": [ "cli/introduction", + "cli/installation", "cli/getting-started" ] }, { - "group": "Local Node Operations", + "group": "Node Operations", "icon": "server", "pages": [ "cli/node-environments", @@ -245,7 +247,7 @@ ] }, { - "group": "Trading & Channels", + "group": "Channels & Trading", "icon": "arrows-rotate", "pages": [ "cli/channels-lsp", @@ -256,7 +258,10 @@ "group": "Reference", "icon": "book", "pages": [ - "cli/command-reference" + "cli/command-reference", + "cli/faq", + "cli/troubleshooting", + "cli/additional-resources" ] } ] @@ -276,8 +281,7 @@ "group": "Guides", "icon": "book-open", "pages": [ - "api-reference/swap-protocol", - "api-reference/error-handling" + "api-reference/swap-protocol" ] }, { @@ -289,6 +293,15 @@ "api-reference/market-apis", "api-reference/swap-apis" ] + }, + { + "group": "Reference", + "icon": "book", + "pages": [ + "api-reference/faq", + "api-reference/troubleshooting", + "api-reference/additional-resources" + ] } ] } @@ -305,6 +318,11 @@ "href": "https://github.com/kaleidoswap/desktop-app/releases", "icon": "download" }, + { + "anchor": "Build with the SDK", + "href": "/sdk/installation", + "icon": "code" + }, { "anchor": "Website", "href": "https://kaleidoswap.com", @@ -346,7 +364,8 @@ "icon": "book", "pages": [ "cn/whats-kaleidoswap/glossary", - "cn/whats-kaleidoswap/troubleshooting" + "cn/whats-kaleidoswap/troubleshooting", + "cn/whats-kaleidoswap/additional-resources" ] } ] @@ -488,19 +507,20 @@ "icon": "flag", "pages": [ "cn/sdk/introduction", + "cn/sdk/installation", "cn/sdk/getting-started" ] }, { - "group": "版本与兼容性", - "icon": "check-double", + "group": "API 界面", + "icon": "layer-group", "pages": [ "cn/sdk/maker-api-compatibility", "cn/sdk/rln-api-compatibility" ] }, { - "group": "核心参考", + "group": "模块", "icon": "code", "pages": [ "cn/sdk/api-reference", @@ -515,8 +535,7 @@ "pages": [ "cn/sdk/how-to-swap", "cn/sdk/examples", - "cn/sdk/best-practices", - "cn/sdk/error-handling" + "cn/sdk/best-practices" ] }, { @@ -540,11 +559,12 @@ "icon": "flag", "pages": [ "cn/cli/introduction", + "cn/cli/installation", "cn/cli/getting-started" ] }, { - "group": "本地节点操作", + "group": "节点操作", "icon": "server", "pages": [ "cn/cli/node-environments", @@ -552,7 +572,7 @@ ] }, { - "group": "交易与通道", + "group": "通道与交易", "icon": "arrows-rotate", "pages": [ "cn/cli/channels-lsp", @@ -563,7 +583,10 @@ "group": "参考", "icon": "book", "pages": [ - "cn/cli/command-reference" + "cn/cli/command-reference", + "cn/cli/faq", + "cn/cli/troubleshooting", + "cn/cli/additional-resources" ] } ] @@ -583,8 +606,7 @@ "group": "指南", "icon": "book-open", "pages": [ - "cn/api-reference/swap-protocol", - "cn/api-reference/error-handling" + "cn/api-reference/swap-protocol" ] }, { @@ -596,6 +618,15 @@ "cn/api-reference/market-apis", "cn/api-reference/swap-apis" ] + }, + { + "group": "参考", + "icon": "book", + "pages": [ + "cn/api-reference/faq", + "cn/api-reference/troubleshooting", + "cn/api-reference/additional-resources" + ] } ] } @@ -612,6 +643,11 @@ "href": "https://github.com/kaleidoswap/desktop-app/releases", "icon": "download" }, + { + "anchor": "使用 SDK 构建", + "href": "/cn/sdk/installation", + "icon": "code" + }, { "anchor": "官网", "href": "https://kaleidoswap.com", @@ -627,8 +663,8 @@ "navbar": { "links": [ { - "label": "技术支持", - "href": "https://docs.google.com/forms/d/e/1FAIpQLSewf4-AJZxuoI878-TRex91kRH04l-9s5XC51UHW6140xXKVA/viewform" + "label": "构建", + "href": "/cn/sdk/installation" } ], "primary": { @@ -658,8 +694,8 @@ "navbar": { "links": [ { - "label": "Support", - "href": "https://docs.google.com/forms/d/e/1FAIpQLSewf4-AJZxuoI878-TRex91kRH04l-9s5XC51UHW6140xXKVA/viewform" + "label": "Build", + "href": "/sdk/installation" } ], "primary": { @@ -668,6 +704,16 @@ "href": "https://kaleidoswap.com/products" } }, + "redirects": [ + { + "source": "/sdk/error-handling", + "destination": "/sdk/troubleshooting" + }, + { + "source": "/cn/sdk/error-handling", + "destination": "/cn/sdk/troubleshooting" + } + ], "footer": { "socials": { "x": "https://x.com/kaleidoswap", diff --git a/mintlify-docs/extensions/kaleidoswap-extension/additional-resources.mdx b/mintlify-docs/extensions/kaleidoswap-extension/additional-resources.mdx index 21eddc6..cafb2b6 100644 --- a/mintlify-docs/extensions/kaleidoswap-extension/additional-resources.mdx +++ b/mintlify-docs/extensions/kaleidoswap-extension/additional-resources.mdx @@ -42,21 +42,28 @@ Specifications for the providers the Extension injects into web pages. See [DApp -## Community & Support +## Get Help + +Check [Troubleshooting](/extensions/kaleidoswap-extension/troubleshooting) for errors and the [FAQ](/extensions/kaleidoswap-extension/faq) for questions. + +For anything else, report a problem through your preferred channel from the options below, including: + +1. Browser name and version +2. KaleidoSwap Extension version (Settings > About) +3. Node type and version +4. Steps to reproduce +5. Error messages or screenshots +6. Console logs (right-click extension popup > Inspect > Console) - - Join the community for support and discussion with other beta testers. + + Ask the community. Direct support for urgent issues. - - When reporting a problem, include your browser and version, the Extension version from **Settings > About**, steps to reproduce, and console logs (right-click the popup, then **Inspect > Console**). See [Troubleshooting](/extensions/kaleidoswap-extension/troubleshooting) first. - - --- diff --git a/mintlify-docs/extensions/kaleidoswap-extension/faq.mdx b/mintlify-docs/extensions/kaleidoswap-extension/faq.mdx index 24bad82..e11f78e 100644 --- a/mintlify-docs/extensions/kaleidoswap-extension/faq.mdx +++ b/mintlify-docs/extensions/kaleidoswap-extension/faq.mdx @@ -80,7 +80,9 @@ description: "Common questions about the KaleidoSwap Extension, covering browser ## Get Help -Check the [Troubleshooting](/extensions/kaleidoswap-extension/troubleshooting) for errors rather than questions. For anything else, report a problem through your preferred channel from the options below, including: +Check the [Troubleshooting](/extensions/kaleidoswap-extension/troubleshooting) for errors rather than questions, and [Additional Resources](/extensions/kaleidoswap-extension/additional-resources) for upstream documentation and links. + +For anything else, report a problem through your preferred channel from the options below, including: 1. Browser name and version 2. KaleidoSwap Extension version (Settings > About) diff --git a/mintlify-docs/extensions/kaleidoswap-extension/getting-started.mdx b/mintlify-docs/extensions/kaleidoswap-extension/getting-started.mdx index f9afabf..d984988 100644 --- a/mintlify-docs/extensions/kaleidoswap-extension/getting-started.mdx +++ b/mintlify-docs/extensions/kaleidoswap-extension/getting-started.mdx @@ -54,9 +54,9 @@ When you first open the KaleidoSwap Extension, the onboarding flow guides you th KaleidoSwap Extension password step - + When restoring a wallet, always use the **BIP39 recovery phrase**, not a Nostr key. An imported Nostr key only replaces the Nostr identity; it does not control funds. - + Cloud backup found prompt offering to restore encrypted RGB state from the VSS backup server, with a Skip for now option diff --git a/mintlify-docs/extensions/kaleidoswap-extension/troubleshooting.mdx b/mintlify-docs/extensions/kaleidoswap-extension/troubleshooting.mdx index 43724f6..716b435 100644 --- a/mintlify-docs/extensions/kaleidoswap-extension/troubleshooting.mdx +++ b/mintlify-docs/extensions/kaleidoswap-extension/troubleshooting.mdx @@ -4,8 +4,6 @@ sidebarTitle: "Troubleshooting" description: "Fix node connection, payment, and DApp provider problems in the KaleidoSwap Extension, plus what to include when reporting a bug to the support team." --- -Fixes for the problems KaleidoSwap Extension users hit most often. For issues across every KaleidoSwap surface, see the [full troubleshooting guide](/whats-kaleidoswap/troubleshooting). - ## Connection Issues @@ -105,7 +103,9 @@ Fixes for the problems KaleidoSwap Extension users hit most often. For issues ac ## Get Help -Check the [FAQ](/extensions/kaleidoswap-extension/faq) for questions rather than errors. For anything else, report a problem through your preferred channel from the options below, including: +Check the [FAQ](/extensions/kaleidoswap-extension/faq) for questions rather than errors, and [Additional Resources](/extensions/kaleidoswap-extension/additional-resources) for upstream documentation and links. + +For anything else, report a problem through your preferred channel from the options below, including: 1. Browser name and version 2. KaleidoSwap Extension version (Settings > About) diff --git a/mintlify-docs/sdk/additional-resources.mdx b/mintlify-docs/sdk/additional-resources.mdx index 5c95237..6fec15c 100644 --- a/mintlify-docs/sdk/additional-resources.mdx +++ b/mintlify-docs/sdk/additional-resources.mdx @@ -1,20 +1,12 @@ --- title: "KaleidoSDK: Additional Resources" sidebarTitle: "Additional Resources" -description: "Links for KaleidoSDK builders — published packages, OpenAPI specifications, node and RGB protocol references, test networks, and support channels" +description: "Links for KaleidoSDK builders — source repositories, OpenAPI specifications, node and RGB protocol references, test networks, and support channels" --- -## Packages & Source +## Source Repositories - - The published TypeScript package. `npm install kaleido-sdk` - - - - The published Python package. `pip install kaleido-sdk` - - Source, releases, and issue tracking for both language implementations. @@ -27,14 +19,6 @@ description: "Links for KaleidoSDK builders — published packages, OpenAPI spec ## Protocol References - - The atomic HTLC flow the SDK drives, endpoint by endpoint, with the sequence diagram. - - - - The channel-ordering interface behind `client.maker` LSPS1 calls. - - The node `client.rln` talks to. This is the KaleidoSwap fork; the [upstream project](https://github.com/RGB-Tools/rgb-lightning-node) is maintained by RGB Tools. @@ -46,40 +30,36 @@ description: "Links for KaleidoSDK builders — published packages, OpenAPI spec ## Development & Testing -Build against a test network before mainnet. Both environments are live and need no API key. - -Pass these to `baseUrl` / `base_url` as shown — the SDK appends the `/api/v1` path itself. - -| Environment | Base URL | Best for | -|-------------|----------|----------| -| **Signet (MutinyNet)** | `https://api.signet.kaleidoswap.com` | Integration testing under realistic conditions | - Get Signet Bitcoin to fund a node and open test channels. - - Base URLs, authentication, request format, and rate limits. + + Look up the transactions behind `listSwaps` and `refreshTransfers`. -## Community & Support +## Get Help - - - Report a bug or request a feature against the SDK. - +Check [Troubleshooting](/sdk/troubleshooting) for errors and the [FAQ](/sdk/faq) for questions. - - Ask the community and the team. - +For anything else, report a problem through your preferred channel from the options below, including: + +1. SDK version (`getVersion()` / `get_version()`) +2. Language and runtime version (Node.js / Python) +3. Error message and stack trace +4. Minimal code to reproduce +5. Environment (Signet / Mainnet) + + + Ask the community. + + + Report a bug on the relevant repository. + Direct support for urgent issues. - - - Language choice, sub-clients, custody, versioning, and amounts. - diff --git a/mintlify-docs/sdk/api-reference.mdx b/mintlify-docs/sdk/api-reference.mdx index 9ada448..ca953b6 100644 --- a/mintlify-docs/sdk/api-reference.mdx +++ b/mintlify-docs/sdk/api-reference.mdx @@ -4,6 +4,15 @@ sidebarTitle: "Client Reference" description: "Full reference for KaleidoClient, MakerClient, and RlnClient, covering methods, parameters, and return types in the KaleidoSDK" --- +## Overview + +`KaleidoClient` is the single entry point. You create it once, then work through its two sub-clients: + +- **`client.maker`** — the hosted [Maker API](/sdk/maker-api-compatibility): market data, quotes, atomic swaps, LSPS1 channel orders +- **`client.rln`** — your own [RGB Lightning Node](/sdk/rln-api-compatibility): wallet, RGB assets, channels, invoices, payments + +`client.maker` needs nothing beyond `baseUrl`, while `client.rln` also requires `nodeUrl` / `node_url`. Every method below is listed in both its TypeScript and Python form. + ## Client Initialization diff --git a/mintlify-docs/sdk/best-practices.mdx b/mintlify-docs/sdk/best-practices.mdx index 0f23adb..be94585 100644 --- a/mintlify-docs/sdk/best-practices.mdx +++ b/mintlify-docs/sdk/best-practices.mdx @@ -8,31 +8,9 @@ description: "Guidelines for building production apps with the KaleidoSDK, cover ### Use Environment Variables -Keep configuration out of source code: +Keep configuration out of source code. The SDK does not auto-load environment variables — read them yourself and pass them to `create()`. - -```typescript TypeScript -import { KaleidoClient } from 'kaleido-sdk'; - -const client = KaleidoClient.create({ - baseUrl: process.env.KALEIDO_API_URL!, - nodeUrl: process.env.KALEIDO_NODE_URL, - apiKey: process.env.KALEIDO_API_KEY, -}); -``` - -```python Python -import os - -from kaleido_sdk import KaleidoClient - -client = KaleidoClient.create( - base_url=os.environ["KALEIDO_API_URL"], - node_url=os.environ.get("KALEIDO_NODE_URL"), - api_key=os.environ.get("KALEIDO_API_KEY"), -) -``` - +For the conventional variable names and a full snippet in both languages, see [Installation](/sdk/installation#environment-variables). ### Use a Singleton Client @@ -77,7 +55,7 @@ def get_client() -> KaleidoClient: ### Always Handle Errors -Wrap SDK calls in try/catch blocks and handle specific error types. The minimum worth branching on is shown below; [Error Handling](/sdk/error-handling#comprehensive-error-handling) has the exhaustive version. +Wrap SDK calls in try/catch blocks and handle specific error types. The minimum worth branching on is shown below; [Troubleshooting](/sdk/troubleshooting#comprehensive-error-handling) has the exhaustive version. ```typescript TypeScript @@ -118,7 +96,7 @@ except KaleidoError as e: Never retry blindly. Every error exposes `isRetryable()` / `is_retryable()`, which already encodes which failures can succeed on a second attempt — use it instead of matching on status codes yourself. -For the full exception hierarchy, the per-status retryability table, and a ready-made exponential-backoff wrapper, see [Error Handling](/sdk/error-handling#retry-patterns). +For the full exception hierarchy, the per-status retryability table, and a ready-made exponential-backoff wrapper, see [Troubleshooting](/sdk/troubleshooting#retry-patterns). ## Async Patterns @@ -172,108 +150,29 @@ for name, fn in [ ### Always Use Raw Units for API Calls -The API works with raw (smallest unit) amounts. Convert display amounts before sending: +The API works in raw (smallest unit) amounts, never display amounts. Convert with `parseRawAmount` / `parse_raw_amount` before building a quote request, and convert back with `toDisplayAmount` / `to_display_amount` before showing anything to the user. - -```typescript TypeScript -import { parseRawAmount } from 'kaleido-sdk'; - -// User enters 0.001 BTC -const userInput = 0.001; -const rawAmount = parseRawAmount(userInput, 8); // 100000 - -const quote = await client.maker.getQuote({ - from_asset: { asset_id: 'BTC', layer: 'BTC_LN', amount: rawAmount }, - to_asset: { asset_id: 'USDT', layer: 'RGB_LN' } -}); -``` - -```python Python -from kaleido_sdk import Layer, PairQuoteRequest, SwapLegInput, parse_raw_amount - -# User enters 0.001 BTC -user_input = 0.001 -raw_amount = parse_raw_amount(user_input, 8) # 100000 - -quote = await client.maker.get_quote(PairQuoteRequest( - from_asset=SwapLegInput(asset_id="BTC", layer=Layer.BTC_LN, amount=raw_amount), - to_asset=SwapLegInput(asset_id="USDT", layer=Layer.RGB_LN) -)) -``` - +Both functions are documented in [Utilities](/sdk/utilities#amount-conversion). ### Use PrecisionHandler for Multi-Asset Apps -When working with multiple assets, use `PrecisionHandler` to avoid precision errors: +With more than one asset in play, passing a precision by hand on every call is how rounding bugs get in. `PrecisionHandler` reads the precision from asset metadata, so you convert by asset ID instead. - -```typescript TypeScript -import { createPrecisionHandler } from 'kaleido-sdk'; - -const handler = createPrecisionHandler(mappedAssets); - -// Convert safely using asset ID -const raw = handler.toRawAmount(userInput, assetId); -const display = handler.toDisplayAmount(rawFromApi, assetId); -``` - -```python Python -from kaleido_sdk import create_precision_handler - -handler = create_precision_handler(mapped_assets) -raw = handler.to_raw_amount(user_input, asset_id) -display = handler.to_display_amount(raw_from_api, asset_id) -``` - +See [Utilities](/sdk/utilities#precisionhandler) for how to create one and the full method list. ## Node Operations -### Check Node Before Using RLN - -Always verify the node is configured: - - -```typescript TypeScript -if (!client.hasNode()) { - throw new Error('Node URL required for this operation'); -} - -const balance = await client.rln.getBtcBalance(); -``` - -```python Python -if not client.has_node(): - raise RuntimeError("Node URL required for this operation") +`client.rln` is only usable when the client was created with a node URL, so guard every node call with `hasNode()` / `has_node()`. In Python, accessing `client.rln` without a node URL raises `NodeNotConfiguredError`. -balance = await client.rln.get_btc_balance() -``` - +See [Getting Started](/sdk/getting-started#node-configuration-checks) for the guard pattern in both languages. ## WebSocket ### Unsubscribe When Done -Always clean up WebSocket subscriptions: - - -```typescript TypeScript -const unsubscribe = await client.maker.streamQuotesByTicker( - 'BTC', 'USDT', 100000, onQuote -); - -// Clean up when component unmounts or user navigates away -unsubscribe(); -``` +`streamQuotes` / `streamQuotesByTicker` return an unsubscribe function. Call it as soon as you stop needing quotes — on unmount, on navigation, or when the user closes the pair. Skipping it leaks memory and keeps quote traffic flowing that nobody reads. -```python Python -unsubscribe = await client.maker.stream_quotes_by_ticker( - "BTC", "USDT", 100000, on_quote -) - -# Clean up when done -unsubscribe() -``` - +See [WebSocket](/sdk/websocket#best-practices) for this and the other streaming guidelines. ### Handle Reconnection diff --git a/mintlify-docs/sdk/changelog.mdx b/mintlify-docs/sdk/changelog.mdx index ad516ac..b912824 100644 --- a/mintlify-docs/sdk/changelog.mdx +++ b/mintlify-docs/sdk/changelog.mdx @@ -4,7 +4,29 @@ sidebarTitle: "Changelog" description: "KaleidoSDK version history, listing new features, breaking changes, and RLN and Maker API compatibility notes for each release" --- -## SDK v0.1.17 (Current) +## SDK v0.1.18 (Current) + +**Compatible APIs:** Latest Maker API · RLN (RGB Lightning Node) API **v0.9.0** + + +This release requires an RGB Lightning Node at **v0.9.0 or later**. If your node still runs 0.8.0 or earlier, stay on SDK **0.1.17** — the new `/unlock` body is rejected by those nodes, and their body shape can no longer be expressed. + + +### Changed + +- Synced the vendored RGB Lightning Node OpenAPI spec to RLN **v0.9.0** and regenerated the node models (Python + TypeScript). + +### Added + +- `ldk_chain_sync` on `UnlockRequest` selects how LDK follows the chain: `BlockSync` (bitcoind RPC, the pre-0.9.0 behaviour) or `TransactionSync` (indexer only, no bitcoind). +- New node types `LdkChainSyncBlockSync` and `LdkChainSyncTransactionSync`. TypeScript also exports the `LdkChainSync` union and the `LdkChainSyncBlockSyncMode` / `LdkChainSyncTransactionSyncMode` enums; Python exports the nested configs as `LdkBlockSyncConfig` / `LdkTransactionSyncConfig`. + +### Breaking changes + +- **`UnlockRequest` no longer takes `bitcoind_rpc_username`, `bitcoind_rpc_password`, `bitcoind_rpc_host`, or `bitcoind_rpc_port`.** Move them into `ldk_chain_sync.config` with `mode: "BlockSync"`, or drop them entirely and pass `mode: "TransactionSync"` with `config.indexer_url`. +- **`UnlockRequest.indexer_url` is now required** (previously optional and nullable). RGB transfers use it regardless of the chain-sync mode you pick. + +## SDK v0.1.17 **Compatible APIs:** Latest Maker API · RLN (RGB Lightning Node) API **v0.8.0** @@ -103,17 +125,17 @@ If your RGB Lightning Node still runs **v0.7.1**, stay on SDK **0.1.13** — the - `ListUnspentsRequest` now requires `settled_only`. RLN 0.7.1 rejects the old `{skip_sync}`-only body with `HTTP 400 "Failed to deserialize the JSON body into the target type"`. The `list_unspents()` convenience method defaults `settled_only=False`; callers that build the request directly must set it. - `POST /sendasset` was renamed to `POST /sendrgb` (`SendAssetRequest`/`SendAssetResponse` → `SendRgbRequest`/`SendRgbResponse`). - + Versions 0.1.6–0.1.8 are omitted here; see the full [CHANGELOG](https://github.com/kaleidoswap/kaleido-sdk/blob/master/CHANGELOG.md) in the SDK repository. - + ## SDK v0.1.5 **Compatible APIs:** Latest Maker API and Latest RLN API - + This entry describes the surface as it shipped in 0.1.5. The order-based swap methods and `waitForSwapCompletion` listed below were later removed in **0.1.13** — see that entry for the migration path. - + ### What's included @@ -152,7 +174,7 @@ Full RGB Lightning Node operations for wallet management, Lightning channels, an **Status:** Stable. No breaking changes planned for v1. -For the Maker API endpoint groups see [Maker API Compatibility](/sdk/maker-api-compatibility), and for the node-side surface see [RLN API Compatibility](/sdk/rln-api-compatibility). Live environments and their WebSocket URLs are listed in [Getting Started](/sdk/getting-started#available-environments). +For the Maker API endpoint groups see [Maker API Compatibility](/sdk/maker-api-compatibility), and for the node-side surface see [RLN API Compatibility](/sdk/rln-api-compatibility). Live environments and their WebSocket URLs are listed in [Installation](/sdk/installation#available-environments). --- diff --git a/mintlify-docs/sdk/error-handling.mdx b/mintlify-docs/sdk/error-handling.mdx deleted file mode 100644 index 67cde89..0000000 --- a/mintlify-docs/sdk/error-handling.mdx +++ /dev/null @@ -1,372 +0,0 @@ ---- -title: "SDK Error Handling" -sidebarTitle: "Error Handling" -description: "Handle KaleidoSDK errors with the exception hierarchy, covering error types, retry patterns, and debugging tips for reliable integrations" ---- - -## Error Hierarchy - -Both SDKs share a nearly identical error class hierarchy. All errors extend from `KaleidoError`: - -``` -KaleidoError (base) -├── APIError (HTTP 400-599) -│ └── RateLimitError (HTTP 429, TypeScript only) -├── RateLimitError (HTTP 429, Python — extends KaleidoError directly) -├── NetworkError (connectivity issues) -├── ValidationError (HTTP 400, 422) -├── TimeoutError (HTTP 408, 504) -├── WebSocketError (WebSocket issues) -├── NotFoundError (HTTP 404) -├── ConfigError (configuration issues) -├── SwapError (swap operation failures) -├── NodeNotConfiguredError (node not set up) -├── QuoteExpiredError (quote expired) -└── InsufficientBalanceError (not enough funds) -``` - -One divergence to be aware of: in TypeScript `RateLimitError` extends `APIError`, while in Python it extends `KaleidoError` directly — a Python `except APIError` handler will not catch rate-limit errors. - -## Base Error: KaleidoError - -All SDK errors extend `KaleidoError` with these properties: - -| Property | Type | Description | -|----------|------|-------------| -| `code` | `string` | Error code for programmatic handling | -| `message` | `string` | Human-readable error message | -| `statusCode` / `status_code` | `number?` | HTTP status code (if applicable) | -| `details` | `string?` | Additional error details | -| `isRetryable()` / `is_retryable()` | `boolean` | Whether the error is safe to retry | - - -```typescript TypeScript -import { KaleidoError } from 'kaleido-sdk'; - -try { - await client.maker.listPairs(); -} catch (error) { - if (error instanceof KaleidoError) { - console.log(`Code: ${error.code}`); - console.log(`Message: ${error.message}`); - console.log(`Status: ${error.statusCode}`); - console.log(`Retryable: ${error.isRetryable()}`); - } -} -``` - -```python Python -from kaleido_sdk import KaleidoError - -try: - await client.maker.list_pairs() -except KaleidoError as e: - print(f"Code: {e.code}") - print(f"Message: {e}") - print(f"Status: {e.status_code}") - print(f"Retryable: {e.is_retryable()}") -``` - - -## Specific Error Classes - -### APIError - -Raised for HTTP errors (status 400-599). - - -```typescript TypeScript -import { APIError } from 'kaleido-sdk'; -// Properties: code='API_ERROR', statusCode, message, details -``` - -```python Python -from kaleido_sdk import APIError -# Properties: code='API_ERROR', status_code, response_body -``` - - -### RateLimitError - -Raised when rate limit is exceeded (HTTP 429). Extends `APIError` in TypeScript; in Python it extends `KaleidoError` directly. - - -```typescript TypeScript -import { RateLimitError } from 'kaleido-sdk'; -// Additional property: retryAfter?: number (seconds) - -try { /* ... */ } catch (error) { - if (error instanceof RateLimitError) { - console.log(`Retry after: ${error.retryAfter} seconds`); - } -} -``` - -```python Python -from kaleido_sdk import RateLimitError -# Additional property: retry_after: int | None - -try: - ... -except RateLimitError as e: - print(f"Retry after: {e.retry_after} seconds") -``` - - -### NetworkError - -Raised for network connectivity issues (DNS failures, connection refused, etc.). - -Always retryable (`isRetryable()` returns `true`). - -### ValidationError - -Raised for validation failures (HTTP 400, 422). Includes FastAPI validation error parsing. - -### TimeoutError - -Raised when requests time out (HTTP 408, 504). - -Always retryable. - -### WebSocketError - -Raised for WebSocket connection or communication errors. - -### NotFoundError - -Raised when a resource is not found (HTTP 404). - -### ConfigError - -Raised for SDK configuration issues (e.g., invalid URLs). - -### SwapError - -Raised for swap operation failures. - - -```typescript TypeScript -import { SwapError } from 'kaleido-sdk'; -// Additional property: swapId?: string - -try { /* ... */ } catch (error) { - if (error instanceof SwapError) { - console.log(`Swap failed: ${error.swapId}`); - } -} -``` - -```python Python -from kaleido_sdk import SwapError -# Additional property: swap_id: str | None -``` - - -### NodeNotConfiguredError - -Raised by the Python SDK when an RLN node operation is attempted without a configured `node_url`. TypeScript instead throws `ConfigError` ("Node API not configured. Provide \"nodeUrl\" when creating the client.") when a `client.rln.*` method is called without `nodeUrl`. - - -```typescript TypeScript -import { ConfigError } from 'kaleido-sdk'; - -try { - await client.rln.getNodeInfo(); -} catch (error) { - if (error instanceof ConfigError) { - console.log('Configure nodeUrl to use RLN operations'); - } -} -``` - -```python Python -from kaleido_sdk import NodeNotConfiguredError - -try: - await client.rln.get_node_info() -except NodeNotConfiguredError: - print("Configure node_url to use RLN operations") -``` - - -### QuoteExpiredError - -Raised when attempting to use an expired quote. - -### InsufficientBalanceError - -Raised when a balance is insufficient for the requested operation. - - -```typescript TypeScript -import { InsufficientBalanceError } from 'kaleido-sdk'; -// Properties: requiredAmount: number, availableAmount: number, asset?: string - -try { /* ... */ } catch (error) { - if (error instanceof InsufficientBalanceError) { - console.log(`Need: ${error.requiredAmount}, Have: ${error.availableAmount}`); - } -} -``` - -```python Python -from kaleido_sdk import InsufficientBalanceError -# Properties: required_amount, available_amount, asset - -try: - ... -except InsufficientBalanceError as e: - print(f"Need: {e.required_amount}, Have: {e.available_amount}") -``` - - -## Comprehensive Error Handling - - -```typescript TypeScript -import { - KaleidoError, - APIError, - NetworkError, - ValidationError, - TimeoutError, - NotFoundError, - QuoteExpiredError, - ConfigError, - InsufficientBalanceError, - RateLimitError, -} from 'kaleido-sdk'; - -try { - const quote = await client.maker.getQuote({ /* ... */ }); - const swap = await client.maker.initSwap({ /* ... */ }); -} catch (error) { - if (error instanceof QuoteExpiredError) { - // Get a fresh quote and retry - } else if (error instanceof InsufficientBalanceError) { - console.log(`Need ${error.requiredAmount}, have ${error.availableAmount}`); - } else if (error instanceof ValidationError) { - console.log(`Invalid request: ${error.message}`); - } else if (error instanceof RateLimitError) { - // Wait and retry - await new Promise(r => setTimeout(r, (error.retryAfter ?? 5) * 1000)); - } else if (error instanceof NotFoundError) { - console.log('Resource not found'); - } else if (error instanceof TimeoutError) { - console.log('Request timed out, retrying...'); - } else if (error instanceof NetworkError) { - console.log('Network issue, check connectivity'); - } else if (error instanceof ConfigError) { - console.log('Node not configured'); - } else if (error instanceof APIError) { - console.log(`API error (${error.statusCode}): ${error.message}`); - } else if (error instanceof KaleidoError) { - console.log(`SDK error [${error.code}]: ${error.message}`); - } -} -``` - -```python Python -from kaleido_sdk import ( - KaleidoError, - APIError, - NetworkError, - ValidationError, - TimeoutError, - NotFoundError, - QuoteExpiredError, - NodeNotConfiguredError, - InsufficientBalanceError, - RateLimitError, - PairQuoteRequest, - SwapRequest, -) -import asyncio - -try: - quote = await client.maker.get_quote(PairQuoteRequest(...)) - swap = await client.maker.init_swap(SwapRequest(...)) -except QuoteExpiredError: - # Get a fresh quote and retry - pass -except InsufficientBalanceError as e: - print(f"Need {e.required_amount}, have {e.available_amount}") -except ValidationError as e: - print(f"Invalid request: {e}") -except RateLimitError as e: - await asyncio.sleep(e.retry_after or 5) -except NotFoundError: - print("Resource not found") -except TimeoutError: - print("Request timed out, retrying...") -except NetworkError: - print("Network issue, check connectivity") -except NodeNotConfiguredError: - print("Node not configured") -except APIError as e: - print(f"API error ({e.status_code}): {e}") -except KaleidoError as e: - print(f"SDK error [{e.code}]: {e}") -``` - - -## Retry Patterns - -Use `isRetryable()` to implement automatic retries: - - -```typescript TypeScript -async function withRetry(fn: () => Promise, maxRetries = 3): Promise { - for (let attempt = 0; attempt < maxRetries; attempt++) { - try { - return await fn(); - } catch (error) { - if (error instanceof KaleidoError && error.isRetryable() && attempt < maxRetries - 1) { - const delay = Math.pow(2, attempt) * 1000; - await new Promise(r => setTimeout(r, delay)); - continue; - } - throw error; - } - } - throw new Error('Max retries exceeded'); -} - -const pairs = await withRetry(() => client.maker.listPairs()); -``` - -```python Python -import asyncio - -async def with_retry(fn, max_retries=3): - for attempt in range(max_retries): - try: - return await fn() - except KaleidoError as e: - if e.is_retryable() and attempt < max_retries - 1: - delay = 2 ** attempt - await asyncio.sleep(delay) - continue - raise - raise RuntimeError("Max retries exceeded") - -pairs = await with_retry(lambda: client.maker.list_pairs()) -``` - - -## HTTP Error Mapping - -The SDK automatically maps HTTP errors to typed exceptions using `mapHttpError` / `map_http_error`: - -| HTTP Status | Error Class | Retryable | -|------------|-------------|-----------| -| 400, 422 | `ValidationError` | No — the request itself is wrong | -| 404 | `NotFoundError` | No | -| 408, 504 | `TimeoutError` | Yes, always | -| 429 | `RateLimitError` | TypeScript: yes, after `retryAfter`. Python: `is_retryable()` returns `False` — back off using `retry_after` yourself | -| 500, 502, 503 | `APIError` | Yes — a server-side fault may clear | -| Other 4xx | `APIError` | No | -| Network failure | `NetworkError` | Yes, always | - -Rather than hardcoding this table in your own retry logic, call `isRetryable()` / `is_retryable()` — it encodes exactly these rules and stays correct as the mapping evolves. diff --git a/mintlify-docs/sdk/examples.mdx b/mintlify-docs/sdk/examples.mdx index 07b0457..9b9b950 100644 --- a/mintlify-docs/sdk/examples.mdx +++ b/mintlify-docs/sdk/examples.mdx @@ -59,7 +59,7 @@ const client = KaleidoClient.create({ baseUrl: 'https://api.signet.kaleidoswap.com', }); -client.maker.enableWebSocket('wss://api.signet.kaleidoswap.com/ws/my-client-id'); +client.maker.enableWebSocket('wss://api.signet.kaleidoswap.com/api/v1/market/ws/my-client-id'); const stop = await client.maker.streamQuotesByTicker( 'BTC', @@ -81,7 +81,7 @@ client = KaleidoClient.create( base_url="https://api.signet.kaleidoswap.com" ) -client.maker.enable_websocket("wss://api.signet.kaleidoswap.com/ws/my-client-id") +client.maker.enable_websocket("wss://api.signet.kaleidoswap.com/api/v1/market/ws/my-client-id") stop = await client.maker.stream_quotes_by_ticker( "BTC", diff --git a/mintlify-docs/sdk/faq.mdx b/mintlify-docs/sdk/faq.mdx index 8f520c9..a0d0754 100644 --- a/mintlify-docs/sdk/faq.mdx +++ b/mintlify-docs/sdk/faq.mdx @@ -8,7 +8,7 @@ description: "Common questions about the KaleidoSDK, covering language choice, t - Whichever matches your stack. Both are standalone implementations that generate their types from the same [OpenAPI specifications](https://github.com/kaleidoswap/specs), so the API shape, the sub-clients, and the error hierarchy are nearly identical across the two — the few divergences (rate-limit handling, the missing-node error) are called out in [Error Handling](/sdk/error-handling). Every example in these docs shows both. + Whichever matches your stack. Both are standalone implementations that generate their types from the same [OpenAPI specifications](https://github.com/kaleidoswap/specs), so the API shape, the sub-clients, and the error hierarchy are nearly identical across the two — the few divergences (rate-limit handling, the missing-node error) are called out in [Troubleshooting](/sdk/troubleshooting#error-reference). Every example in these docs shows both. Runtime requirements: **Node.js 18+** for TypeScript, **Python 3.10+** for Python. A Rust core is in progress. @@ -39,7 +39,7 @@ description: "Common questions about the KaleidoSDK, covering language choice, t - **Signet** — `https://api.signet.kaleidoswap.com`, realistic conditions, best before mainnet - Pass this as `baseUrl` / `base_url`; the SDK appends `/api/v1` itself. Full list in [Available Environments](/sdk/getting-started#available-environments). + Pass this as `baseUrl` / `base_url`; the SDK appends `/api/v1` itself. Full list in [Available Environments](/sdk/installation#available-environments). @@ -79,25 +79,27 @@ description: "Common questions about the KaleidoSDK, covering language choice, t Every SDK exception extends `KaleidoError`, so catching that one type covers the whole hierarchy. Each error exposes `isRetryable()` / `is_retryable()`, which tells you whether retrying is safe — do not retry blindly, since some failures will never succeed on a second attempt. - See [Error Handling](/sdk/error-handling) for the full hierarchy and the retry-with-backoff pattern, and [Best Practices](/sdk/best-practices) for how it fits a production client. + See [Troubleshooting](/sdk/troubleshooting#error-reference) for the full hierarchy and the retry-with-backoff pattern, and [Best Practices](/sdk/best-practices) for how it fits a production client. ## Get Help -Check the [Troubleshooting](/sdk/troubleshooting) for errors rather than questions. For anything else, report a problem through your preferred channel from the options below, including: +Check the [Troubleshooting](/sdk/troubleshooting) for errors rather than questions, and [Additional Resources](/sdk/additional-resources) for upstream documentation and links. + +For anything else, report a problem through your preferred channel from the options below, including: 1. SDK version (`getVersion()` / `get_version()`) 2. Language and runtime version (Node.js / Python) 3. Error message and stack trace 4. Minimal code to reproduce -5. Environment (Regtest / Signet / Mainnet) +5. Environment (Signet / Mainnet) Ask the community. - + Report a bug on the relevant repository. diff --git a/mintlify-docs/sdk/getting-started.mdx b/mintlify-docs/sdk/getting-started.mdx index c1c879b..b0ba9ba 100644 --- a/mintlify-docs/sdk/getting-started.mdx +++ b/mintlify-docs/sdk/getting-started.mdx @@ -1,50 +1,10 @@ --- -title: "Getting Started with the KaleidoSDK" +title: "KaleidoSDK: Getting Started" sidebarTitle: "Getting Started" -description: "Install and configure the KaleidoSDK for TypeScript or Python, covering clients, endpoints, and your first swap quote in minutes" +description: "Create your first KaleidoSDK client in TypeScript or Python, reach the maker and node sub-clients, and request a swap quote in a few lines" --- -`kaleido-sdk` (TypeScript) and `kaleido_sdk` (Python) are generated from the same Maker API and RGB Lightning Node specs, then wrapped with handwritten clients: - -- `client.maker` for KaleidoSwap market, swap, and LSPS1 endpoints -- `client.rln` for RGB Lightning Node wallet, channel, payment, and swap endpoints - - - For which SDK version works with which API, see [Maker API Compatibility](/sdk/maker-api-compatibility) and [RLN API Compatibility](/sdk/rln-api-compatibility). - - -## Installation - - -```bash npm -npm install kaleido-sdk -``` - -```bash pnpm -pnpm add kaleido-sdk -``` - -```bash yarn -yarn add kaleido-sdk -``` - -```bash pip -pip install kaleido-sdk -``` - - -### Requirements - - - - - Node.js 18 or higher - - TypeScript 5.x recommended - - - - Python 3.10 or higher - - Runtime dependencies are installed automatically - - +This is the path from an installed package to a first quote. If you have not installed the SDK yet, start with [Installation](/sdk/installation). ## Basic Setup @@ -76,100 +36,7 @@ print(f"Found {len(assets.assets)} assets") `KaleidoClient.create()` is synchronous in both SDKs. Do not `await` client creation. -## Configuration - -### TypeScript - -`KaleidoClient.create()` accepts a `KaleidoConfig` object: - -```typescript -import { KaleidoClient, LogLevel } from 'kaleido-sdk'; - -const client = KaleidoClient.create({ - baseUrl: 'https://api.signet.kaleidoswap.com', - nodeUrl: 'http://localhost:3001', - apiKey: process.env.KALEIDO_API_KEY, - timeout: 30, - logLevel: LogLevel.INFO, -}); -``` - -Supported config fields: - -- `baseUrl?`: Maker API base URL. Defaults to `https://api.signet.kaleidoswap.com` -- `nodeUrl?`: RGB Lightning Node URL -- `apiKey?`: optional API key -- `nodeApiKey?`: optional bearer token for authenticated RLN node requests -- `timeout?`: request timeout in seconds -- `logLevel?`: SDK log level -- `logger?`: custom logger implementation - -### Python - -`KaleidoClient.create()` accepts keyword arguments: - -```python -import logging -from kaleido_sdk import KaleidoClient - -client = KaleidoClient.create( - base_url="https://api.signet.kaleidoswap.com", - node_url="http://localhost:3001", - api_key=None, - timeout=30.0, - max_retries=3, - cache_ttl=60, - log_level=logging.INFO, -) -``` - -Python supports the same connection settings plus: - -- `max_retries`: retry budget for the HTTP client -- `cache_ttl`: cache TTL in seconds -- `log_level`: standard Python logging level - -## Environment Variables - -The SDK does not auto-load environment variables, but these names are used by the examples and work well as a convention: - -| Variable | Typical use | -|----------|-------------| -| `KALEIDO_API_URL` | Maker API base URL | -| `KALEIDO_NODE_URL` | RGB Lightning Node URL | -| `KALEIDO_API_KEY` | API key | - - -```typescript TypeScript -import { KaleidoClient } from 'kaleido-sdk'; - -const client = KaleidoClient.create({ - baseUrl: process.env.KALEIDO_API_URL || 'https://api.signet.kaleidoswap.com', - nodeUrl: process.env.KALEIDO_NODE_URL, - apiKey: process.env.KALEIDO_API_KEY, -}); -``` - -```python Python -import os -from kaleido_sdk import KaleidoClient - -client = KaleidoClient.create( - base_url=os.environ.get("KALEIDO_API_URL", "https://api.signet.kaleidoswap.com"), - node_url=os.environ.get("KALEIDO_NODE_URL"), - api_key=os.environ.get("KALEIDO_API_KEY"), -) -``` - - -## Available Environments - -Pass the API URL as `baseUrl` / `base_url`; the SDK appends the `/api/v1` path itself. No API key is required on the test networks. - -| Environment | API URL | WebSocket URL | Status | -|-------------|---------|---------------|--------| -| **Signet** | `https://api.signet.kaleidoswap.com` | `wss://api.signet.kaleidoswap.com/ws/{id}` | Live (default) | -| **Mainnet** | `https://api.kaleidoswap.com` | `wss://api.kaleidoswap.com/ws/{id}` | Coming soon | +Every field you can pass to `create()` is listed in [Configuration](/sdk/installation#configuration). ## Sub-Client Architecture @@ -265,3 +132,5 @@ print(quote.rfq_id) print(quote.price) ``` + +Once a quote looks right, [How to Swap](/sdk/how-to-swap) walks the atomic swap flow end to end. diff --git a/mintlify-docs/sdk/how-to-swap.mdx b/mintlify-docs/sdk/how-to-swap.mdx index 03ccdc0..48fb4af 100644 --- a/mintlify-docs/sdk/how-to-swap.mdx +++ b/mintlify-docs/sdk/how-to-swap.mdx @@ -1,5 +1,5 @@ --- -title: "Create Atomic Swaps with the SDK" +title: "How to Swap with KaleidoSDK" sidebarTitle: "How to Swap" description: "Create and execute Bitcoin atomic swaps with the KaleidoSDK in a step-by-step guide that runs from quote to settlement" --- @@ -182,20 +182,3 @@ print(status.swap.status if status.swap else None) If a transfer sits pending longer than expected, `client.rln.refreshTransfers()` / `refresh_transfers()` advances pending RGB transfers, and `client.rln.listSwaps()` gives you the node's own view. See [Troubleshooting](/sdk/troubleshooting#swap-issues) for the failure modes. - -## Next Steps - - - - The exception hierarchy and retry patterns around each step. - - - The HTLC flow underneath, endpoint by endpoint, with the sequence diagram. - - - Stream live quotes instead of requesting them one at a time. - - - Every method on `client.maker` and `client.rln`. - - diff --git a/mintlify-docs/sdk/installation.mdx b/mintlify-docs/sdk/installation.mdx new file mode 100644 index 0000000..e257d66 --- /dev/null +++ b/mintlify-docs/sdk/installation.mdx @@ -0,0 +1,146 @@ +--- +title: "KaleidoSDK: Installation" +sidebarTitle: "Installation" +description: "Install the KaleidoSDK for TypeScript or Python, with runtime requirements, the client configuration fields, environment variables, and the available API environments" +--- + +`kaleido-sdk` (TypeScript) and `kaleido_sdk` (Python) are generated from the same Maker API and RGB Lightning Node specs, then wrapped with handwritten clients: + +- `client.maker` for KaleidoSwap market, swap, and LSPS1 endpoints +- `client.rln` for RGB Lightning Node wallet, channel, payment, and swap endpoints + +Both ship from the same repository and share a version number, so a given release behaves identically in either language. + + + For which SDK version works with which API, see [Maker API Compatibility](/sdk/maker-api-compatibility) and [RLN API Compatibility](/sdk/rln-api-compatibility). + + +## Install the Package + + +```bash npm +npm install kaleido-sdk +``` + +```bash pnpm +pnpm add kaleido-sdk +``` + +```bash yarn +yarn add kaleido-sdk +``` + +```bash pip +pip install kaleido-sdk +``` + + +### Requirements + + + + - Node.js 18 or higher + - TypeScript 5.x recommended + + + - Python 3.10 or higher + - Runtime dependencies are installed automatically + + + +## Configuration + +### TypeScript + +`KaleidoClient.create()` accepts a `KaleidoConfig` object: + +```typescript +import { KaleidoClient, LogLevel } from 'kaleido-sdk'; + +const client = KaleidoClient.create({ + baseUrl: 'https://api.signet.kaleidoswap.com', + nodeUrl: 'http://localhost:3001', + apiKey: process.env.KALEIDO_API_KEY, + timeout: 30, + logLevel: LogLevel.INFO, +}); +``` + +Supported config fields: + +- `baseUrl?`: Maker API base URL. Defaults to `https://api.signet.kaleidoswap.com` +- `nodeUrl?`: RGB Lightning Node URL +- `apiKey?`: optional API key +- `nodeApiKey?`: optional bearer token for authenticated RLN node requests +- `timeout?`: request timeout in seconds +- `logLevel?`: SDK log level +- `logger?`: custom logger implementation + +### Python + +`KaleidoClient.create()` accepts keyword arguments: + +```python +import logging +from kaleido_sdk import KaleidoClient + +client = KaleidoClient.create( + base_url="https://api.signet.kaleidoswap.com", + node_url="http://localhost:3001", + api_key=None, + timeout=30.0, + max_retries=3, + cache_ttl=60, + log_level=logging.INFO, +) +``` + +Python supports the same connection settings plus: + +- `max_retries`: retry budget for the HTTP client +- `cache_ttl`: cache TTL in seconds +- `log_level`: standard Python logging level + +## Environment Variables + +The SDK does not auto-load environment variables, but these names are used by the examples and work well as a convention: + +| Variable | Typical use | +|----------|-------------| +| `KALEIDO_API_URL` | Maker API base URL | +| `KALEIDO_NODE_URL` | RGB Lightning Node URL | +| `KALEIDO_API_KEY` | API key | + + +```typescript TypeScript +import { KaleidoClient } from 'kaleido-sdk'; + +const client = KaleidoClient.create({ + baseUrl: process.env.KALEIDO_API_URL || 'https://api.signet.kaleidoswap.com', + nodeUrl: process.env.KALEIDO_NODE_URL, + apiKey: process.env.KALEIDO_API_KEY, +}); +``` + +```python Python +import os +from kaleido_sdk import KaleidoClient + +client = KaleidoClient.create( + base_url=os.environ.get("KALEIDO_API_URL", "https://api.signet.kaleidoswap.com"), + node_url=os.environ.get("KALEIDO_NODE_URL"), + api_key=os.environ.get("KALEIDO_API_KEY"), +) +``` + + +## Available Environments + +Pass the API URL as `baseUrl` / `base_url`; the SDK appends the `/api/v1` path itself. No API key is required on the test networks. + +| 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 | + +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/sdk/introduction.mdx b/mintlify-docs/sdk/introduction.mdx index dfccfe0..c024975 100644 --- a/mintlify-docs/sdk/introduction.mdx +++ b/mintlify-docs/sdk/introduction.mdx @@ -1,15 +1,11 @@ --- -title: "Multi-Protocol Bitcoin Swap SDK" +title: "KaleidoSDK" sidebarTitle: "Overview" description: "Build Bitcoin wallets and trading apps with the KaleidoSDK, which ships TypeScript and Python clients for non-custodial atomic swaps across Bitcoin Layers" --- The KaleidoSDK (`kaleido-sdk`) lets wallet builders integrate non-custodial atomic swaps across Bitcoin, Lightning, and RGB. It powers the [KaleidoSwap non-custodial DEX](https://kaleidoswap.com) and ships in TypeScript and Python. -## Official SDKs - -KaleidoSwap provides official SDKs for both TypeScript and Python. Both are standalone implementations that auto-generate types from the same OpenAPI specifications, ensuring full type safety and consistent API design. - ## Architecture Both SDKs share the same API design and are built independently: @@ -47,10 +43,3 @@ For what KaleidoSwap is as a protocol, see [What's KaleidoSwap](/whats-kaleidosw - **Error Handling**: Comprehensive exception hierarchy across both SDKs - **RGB Asset Trading**: Full support for trading RGB assets on Lightning and on-chain - **Atomic Swaps**: HTLC-based swaps with no trust in the maker - -## Support - -Need help? Check out our: -- [GitHub Issues](https://github.com/kaleidoswap/kaleido-sdk/issues) -- [Community Telegram](https://t.me/kaleidoswap) -- [Support Email](mailto:support@kaleidoswap.com) diff --git a/mintlify-docs/sdk/maker-api-compatibility.mdx b/mintlify-docs/sdk/maker-api-compatibility.mdx index 66cb3d0..8dada9d 100644 --- a/mintlify-docs/sdk/maker-api-compatibility.mdx +++ b/mintlify-docs/sdk/maker-api-compatibility.mdx @@ -1,17 +1,19 @@ --- -title: 'Maker API Compatibility' +title: 'Maker API' description: "How KaleidoSDK versions track the Maker API, with the endpoint groups the SDK exposes through client.maker and how to reach them" --- +The Maker API is hosted by KaleidoSwap and reached over the network, with no infrastructure of your own to run. It enables market data and quoting, maker-side atomic swap coordination, and LSPS1 channel ordering. + ## Compatibility The SDK tracks the **latest Maker API** release: there is no version pairing to manage on this side. Keep both up to date to stay on supported endpoints and get new features as they ship. -To check the current Maker API version and updates, refer to the [Maker API changelog](https://github.com/kaleidoswap/maker-api/releases) or your API documentation. +For the current Maker API surface, see the [API Reference](/api-reference/introduction). The OpenAPI specification the SDK generates its types from is published in [kaleidoswap/specs](https://github.com/kaleidoswap/specs). -## API Endpoint Groups +## Endpoint Groups The Maker API provides the following endpoint groups: @@ -25,46 +27,4 @@ The Maker API provides the following endpoint groups: The order-based swap endpoints (`/api/v1/swaps/orders/*`) were retired, and the matching SDK methods were removed in **0.1.13**. Use the atomic swap flow instead — see [How to Swap](/sdk/how-to-swap). -## Using the Maker API - -To use Maker API features with the SDK: - - -```typescript TypeScript -import { KaleidoClient, Layer } from 'kaleido-sdk'; - -const client = KaleidoClient.create({ - baseUrl: 'https://api.signet.kaleidoswap.com', -}); - -// Access Maker API through client.maker -const assets = await client.maker.listAssets(); -const pairs = await client.maker.listPairs(); -const quote = await client.maker.getQuote({ - from_asset: { asset_id: 'BTC', layer: Layer.BTC_LN, amount: 100000 }, - to_asset: { asset_id: 'USDT', layer: Layer.RGB_LN }, -}); -``` - -```python Python -import asyncio -from kaleido_sdk import KaleidoClient, Layer, PairQuoteRequest, SwapLegInput - -async def main(): - client = KaleidoClient.create( - base_url="https://api.signet.kaleidoswap.com" - ) - - # Access Maker API through client.maker - assets = await client.maker.list_assets() - pairs = await client.maker.list_pairs() - quote = await client.maker.get_quote( - PairQuoteRequest( - from_asset=SwapLegInput(asset_id="BTC", layer=Layer.BTC_LN, amount=100000), - to_asset=SwapLegInput(asset_id="USDT", layer=Layer.RGB_LN), - ) - ) - -asyncio.run(main()) -``` - +Every group is reached through `client.maker`, which needs nothing beyond a `baseUrl` on the client. See [Getting Started](/sdk/getting-started) for the first call, and the [Client Reference](/sdk/api-reference) for every method. diff --git a/mintlify-docs/sdk/nwc.mdx b/mintlify-docs/sdk/nwc.mdx index df4a1b0..9df3a2e 100644 --- a/mintlify-docs/sdk/nwc.mdx +++ b/mintlify-docs/sdk/nwc.mdx @@ -14,10 +14,10 @@ On top of the standard NIP-47 wallet methods, the client adds **`rln*` RGB Light methods** so you can read balances, manage RGB assets, and open invoices on the remote node through the same encrypted NWC transport. - + Transport is end-to-end encrypted with **NIP-44**, falling back to **NIP-04** when the wallet service does not advertise NIP-44 support. - + ## Connecting diff --git a/mintlify-docs/sdk/rln-api-compatibility.mdx b/mintlify-docs/sdk/rln-api-compatibility.mdx index ba01813..0df5c3e 100644 --- a/mintlify-docs/sdk/rln-api-compatibility.mdx +++ b/mintlify-docs/sdk/rln-api-compatibility.mdx @@ -1,10 +1,12 @@ --- -title: 'RLN API Compatibility' +title: 'RLN API' description: "Which RGB Lightning Node (RLN) API version each KaleidoSDK release targets, with the node-side endpoint categories client.rln exposes" --- import { sdkVersion, rlnApiVersion } from "/snippets/versions.mdx"; +The RLN (RGB Lightning Node) API is provided directly by your configured RGB Lightning Node. It enables wallet operations, Lightning channel management, and node-to-node swap coordination. + ## Compatibility **SDK v{sdkVersion}** is generated against **RGB Lightning Node API v{rlnApiVersion}** (the `kaleidoswap/rgb-lightning-node` fork). @@ -15,11 +17,7 @@ The SDK automatically supports the most recent RLN API release. Always keep your To check the latest RLN API changes and updates, refer to the [RGB Lightning Node](https://github.com/kaleidoswap/rgb-lightning-node) or your node documentation. -## RLN API Overview - -The RLN (RGB Lightning Node) API is provided directly by your configured RGB Lightning Node. It enables wallet operations, Lightning channel management, and node-to-node swap coordination. - -## RLN API Categories +## Categories | Category | Purpose | Examples | |---|---|---| @@ -29,52 +27,4 @@ The RLN (RGB Lightning Node) API is provided directly by your configured RGB Lig | **Payments** | Payment execution | Pay invoices, coordinate swaps, node-to-node transactions | | **Node Info** | Node status and configuration | Pubkey, sync status, capabilities | -## Accessing RLN Operations - -Before using RLN operations, ensure your node is configured: - - -```typescript TypeScript -import { KaleidoClient } from 'kaleido-sdk'; - -const client = KaleidoClient.create({ - baseUrl: 'https://api.signet.kaleidoswap.com', - nodeUrl: 'http://localhost:3001', // Required for RLN operations -}); - -// Check if node is configured -if (client.hasNode()) { - // Access RLN API through client.rln - const nodeInfo = await client.rln.getNodeInfo(); - const balance = await client.rln.getBtcBalance(); - const channels = await client.rln.listChannels(); -} else { - console.log('Node not configured - RLN operations unavailable'); -} -``` - -```python Python -import asyncio -from kaleido_sdk import KaleidoClient - - -async def main(): - client = KaleidoClient.create( - base_url="https://api.signet.kaleidoswap.com", - node_url="http://localhost:3001" # Required for RLN operations - ) - - # Check if node is configured - if client.has_node(): - # Access RLN API through client.rln - node_info = await client.rln.get_node_info() - balance = await client.rln.get_btc_balance() - channels = await client.rln.list_channels() - else: - print("Node not configured - RLN operations unavailable") - - -if __name__ == "__main__": - asyncio.run(main()) -``` - +These are reached through `client.rln`, which requires a `nodeUrl` / `node_url` on the client: without one, TypeScript throws `ConfigError` and Python raises `NodeNotConfiguredError`. See [Getting Started](/sdk/getting-started) for the setup and the node checks, and the [Client Reference](/sdk/api-reference) for every method. diff --git a/mintlify-docs/sdk/troubleshooting.mdx b/mintlify-docs/sdk/troubleshooting.mdx index 638def5..86a3bd6 100644 --- a/mintlify-docs/sdk/troubleshooting.mdx +++ b/mintlify-docs/sdk/troubleshooting.mdx @@ -1,7 +1,7 @@ --- title: "KaleidoSDK Troubleshooting" sidebarTitle: "Troubleshooting" -description: "Diagnose common KaleidoSDK issues such as connection failures, version mismatches, and swap errors, with step-by-step solutions" +description: "Diagnose common KaleidoSDK issues such as connection failures, version mismatches, and swap errors, with step-by-step solutions plus the full error hierarchy and retry patterns" --- ## Installation Issues @@ -27,11 +27,13 @@ description: "Diagnose common KaleidoSDK issues such as connection failures, ver 4. Try: `pip install kaleido-sdk --no-cache-dir` - - **Symptoms:** `Cannot find module 'kaleido-sdk'` or `ModuleNotFoundError` + + **Symptoms:** `Cannot find module 'kaleido-sdk'`, `ERR_REQUIRE_ESM`, import syntax errors, or `ModuleNotFoundError` + + **Cause (TypeScript):** The SDK is ESM-only, and the legacy `"moduleResolution": "node"` setting ignores the package's `exports` field. **Solutions:** - - **TypeScript:** The SDK is ESM-only, so `tsconfig.json` needs `"moduleResolution": "bundler"`, `"node16"`, or `"nodenext"`. The legacy `"node"` setting ignores the package's `exports` field and will not resolve it + - **TypeScript:** set `"moduleResolution"` to `"bundler"`, `"node16"`, or `"nodenext"` in `tsconfig.json`, and make the consuming project ESM — `"type": "module"` in `package.json`, or the `.mts` file extension. If you must stay on CommonJS, use a dynamic import: `const sdk = await import('kaleido-sdk')` - **Python:** Verify you are in the correct virtual environment - Verify the package is installed: `npm list kaleido-sdk` or `pip show kaleido-sdk` @@ -114,7 +116,7 @@ description: "Diagnose common KaleidoSDK issues such as connection failures, ver **Solutions:** 1. Check that `apiKey` / `api_key` is set correctly 2. Verify the key is valid and not expired - 3. Some endpoints may not require an API key -- check the [API Reference](/sdk/api-reference) + 3. Some endpoints may not require an API key — check the [API Reference](/sdk/api-reference) @@ -128,7 +130,7 @@ description: "Diagnose common KaleidoSDK issues such as connection failures, ver **Solutions:** 1. Increase the timeout: `timeout: 60` (seconds) 2. Check network connectivity - 3. Implement retry logic using `error.isRetryable()` — see [Error Handling](/sdk/error-handling#retry-patterns) + 3. Implement retry logic using `error.isRetryable()` — see [Retry Patterns](#retry-patterns) @@ -246,10 +248,10 @@ description: "Diagnose common KaleidoSDK issues such as connection failures, ver -## TypeScript-Specific Issues +## Language-Specific Issues - + **Symptoms:** TypeScript compiler errors about incompatible types **Solutions:** @@ -261,30 +263,16 @@ description: "Diagnose common KaleidoSDK issues such as connection failures, ver 3. If using strict mode, you may need to handle `undefined` explicitly - - **Symptoms:** `ERR_REQUIRE_ESM` or import syntax errors - - **Solutions:** - 1. The SDK is ESM-only. Ensure your project uses ESM: - - `"type": "module"` in `package.json` - - Or use `.mts` file extension - 2. If you must use CommonJS, use dynamic import: `const sdk = await import('kaleido-sdk')` - - - -## Python-Specific Issues - - - + **Symptoms:** `ValidationError` from Pydantic when parsing API responses **Solutions:** 1. Ensure `pydantic>=2.0` is installed 2. Check that you are using the correct request format - 3. The API may have been updated -- try updating the SDK: `pip install --upgrade kaleido-sdk` + 3. The API may have been updated — try updating the SDK: `pip install --upgrade kaleido-sdk` - + **Symptoms:** `httpx.ConnectError` or similar **Solutions:** @@ -294,94 +282,232 @@ description: "Diagnose common KaleidoSDK issues such as connection failures, ver -## Debugging +## Error Reference -### Enable Verbose Logging +Both SDKs share a nearly identical error class hierarchy. All errors extend from `KaleidoError`, so a single `catch` on it never lets an SDK failure escape unhandled: - -```typescript TypeScript -// Use Node.js debugging -// Set environment variable: NODE_DEBUG=http -// Or inspect network with browser DevTools +``` +KaleidoError (base) +├── APIError (HTTP 400-599) +│ └── RateLimitError (HTTP 429, TypeScript only) +├── RateLimitError (HTTP 429, Python — extends KaleidoError directly) +├── NetworkError (connectivity issues) +├── ValidationError (HTTP 400, 422) +├── TimeoutError (HTTP 408, 504) +├── WebSocketError (WebSocket issues) +├── NotFoundError (HTTP 404) +├── ConfigError (configuration issues) +├── SwapError (swap operation failures) +├── NodeNotConfiguredError (node not set up) +├── QuoteExpiredError (quote expired) +└── InsufficientBalanceError (not enough funds) ``` -```python Python -import logging +Two divergences between the SDKs are worth knowing before you write a handler: -# Enable debug logging for httpx -logging.basicConfig(level=logging.DEBUG) -logging.getLogger("httpx").setLevel(logging.DEBUG) -logging.getLogger("websockets").setLevel(logging.DEBUG) -``` - +- **`RateLimitError`** extends `APIError` in TypeScript but `KaleidoError` directly in Python — a Python `except APIError` handler will **not** catch rate-limit errors. +- **A missing node URL** raises `NodeNotConfiguredError` in Python, but `ConfigError` ("Node API not configured. Provide \"nodeUrl\" when creating the client.") in TypeScript. -### Validate Configuration +### KaleidoError Properties + +Every error carries these, whichever class it is: + +| Property | Type | Description | +|----------|------|-------------| +| `code` | `string` | Error code for programmatic handling | +| `message` | `string` | Human-readable error message | +| `statusCode` / `status_code` | `number?` | HTTP status code (if applicable) | +| `details` | `string?` | Additional error details | +| `isRetryable()` / `is_retryable()` | `boolean` | Whether the error is safe to retry | + +### Error Classes + +| Class | Raised when | Additional properties | +|-------|-------------|-----------------------| +| `APIError` | HTTP 400-599 | TypeScript: `details`. Python: `response_body` | +| `RateLimitError` | HTTP 429 | `retryAfter` / `retry_after` — seconds to wait | +| `NetworkError` | DNS failure, connection refused, and other connectivity faults | — | +| `ValidationError` | HTTP 400, 422 — includes parsed FastAPI validation detail | — | +| `TimeoutError` | HTTP 408, 504 | — | +| `WebSocketError` | WebSocket connection or communication failure | — | +| `NotFoundError` | HTTP 404 | — | +| `ConfigError` | Invalid SDK configuration, such as a malformed URL. In TypeScript, also a `client.rln.*` call made without `nodeUrl` | — | +| `SwapError` | A swap operation failed | `swapId` / `swap_id` | +| `NodeNotConfiguredError` | Python only — a `client.rln.*` call made without `node_url` | — | +| `QuoteExpiredError` | An `rfq_id` is used after its `expires_at` | — | +| `InsufficientBalanceError` | The balance cannot cover the operation | `requiredAmount` / `required_amount`, `availableAmount` / `available_amount`, `asset` | + +Which of these are safe to retry is decided per status, not per class — see [HTTP Error Mapping](#http-error-mapping) below. + +### HTTP Error Mapping + +The SDK automatically maps HTTP errors to typed exceptions using `mapHttpError` / `map_http_error`: + +| HTTP Status | Error Class | Retryable | +|------------|-------------|-----------| +| 400, 422 | `ValidationError` | No — the request itself is wrong | +| 404 | `NotFoundError` | No | +| 408, 504 | `TimeoutError` | Yes, always | +| 429 | `RateLimitError` | TypeScript: yes, after `retryAfter`. Python: `is_retryable()` returns `False` — back off using `retry_after` yourself | +| 500, 502, 503 | `APIError` | Yes — a server-side fault may clear | +| Other 4xx | `APIError` | No | +| Network failure | `NetworkError` | Yes, always | + +Rather than hardcoding this table in your own retry logic, call `isRetryable()` / `is_retryable()` — it encodes exactly these rules and stays correct as the mapping evolves. + +### Comprehensive Error Handling + +Branch from the most specific class to the most general, and end on `KaleidoError` so nothing escapes. Subclasses must be tested before their parents — in TypeScript `RateLimitError` is an `APIError`, so an `APIError` branch placed first would swallow it. ```typescript TypeScript -const client = KaleidoClient.create({ - baseUrl: 'https://api.signet.kaleidoswap.com', - nodeUrl: 'http://localhost:3001', -}); +import { KaleidoError, RateLimitError, QuoteExpiredError } from 'kaleido-sdk'; -console.log(`Has node: ${client.hasNode()}`); - -// Test connectivity try { - const assets = await client.maker.listAssets(); - console.log(`API connected: ${assets.assets.length} assets`); + const quote = await client.maker.getQuote({ /* ... */ }); + const swap = await client.maker.initSwap({ /* ... */ }); } catch (error) { - console.error('API connection failed:', error); -} - -if (client.hasNode()) { - try { - const nodeInfo = await client.rln.getNodeInfo(); - console.log(`Node connected: ${nodeInfo.pubkey}`); - } catch (error) { - console.error('Node connection failed:', error); + if (error instanceof QuoteExpiredError) { + // Get a fresh quote and retry + } else if (error instanceof RateLimitError) { + await new Promise(r => setTimeout(r, (error.retryAfter ?? 5) * 1000)); + } else if (error instanceof KaleidoError && error.isRetryable()) { + // Back off and retry — see Retry Patterns below + } else if (error instanceof KaleidoError) { + console.error(`SDK error [${error.code}]: ${error.message}`); } } ``` ```python Python -client = KaleidoClient.create( - base_url="https://api.signet.kaleidoswap.com", - node_url="http://localhost:3001", +import asyncio + +from kaleido_sdk import ( + KaleidoError, + PairQuoteRequest, + QuoteExpiredError, + RateLimitError, + SwapRequest, ) -print(f"Has node: {client.has_node()}") - try: - assets = await client.maker.list_assets() - print(f"API connected: {len(assets.assets)} assets") -except Exception as e: - print(f"API connection failed: {e}") - -if client.has_node(): - try: - node_info = await client.rln.get_node_info() - print(f"Node connected: {node_info.pubkey}") - except Exception as e: - print(f"Node connection failed: {e}") + quote = await client.maker.get_quote(PairQuoteRequest(...)) + swap = await client.maker.init_swap(SwapRequest(...)) +except QuoteExpiredError: + # Get a fresh quote and retry + pass +except RateLimitError as e: + await asyncio.sleep(e.retry_after or 5) +except KaleidoError as e: + if e.is_retryable(): + # Back off and retry — see Retry Patterns below + pass + else: + print(f"SDK error [{e.code}]: {e}") ``` +Add a branch for a specific class only where your handling genuinely differs — `InsufficientBalanceError` to show the shortfall, `ValidationError` to point at the offending field. Everything else is already covered by the `isRetryable()` check and the base case. + +### Retry Patterns + +Use `isRetryable()` to implement automatic retries: + + +```typescript TypeScript +async function withRetry(fn: () => Promise, maxRetries = 3): Promise { + for (let attempt = 0; attempt < maxRetries; attempt++) { + try { + return await fn(); + } catch (error) { + if (error instanceof KaleidoError && error.isRetryable() && attempt < maxRetries - 1) { + const delay = Math.pow(2, attempt) * 1000; + await new Promise(r => setTimeout(r, delay)); + continue; + } + throw error; + } + } + throw new Error('Max retries exceeded'); +} + +const pairs = await withRetry(() => client.maker.listPairs()); +``` + +```python Python +import asyncio + +async def with_retry(fn, max_retries=3): + for attempt in range(max_retries): + try: + return await fn() + except KaleidoError as e: + if e.is_retryable() and attempt < max_retries - 1: + delay = 2 ** attempt + await asyncio.sleep(delay) + continue + raise + raise RuntimeError("Max retries exceeded") + +pairs = await with_retry(lambda: client.maker.list_pairs()) +``` + + +## Debugging + +### Enable Verbose Logging + +Python exposes the underlying `httpx` and `websockets` loggers: + +```python +import logging + +logging.basicConfig(level=logging.DEBUG) +logging.getLogger("httpx").setLevel(logging.DEBUG) +logging.getLogger("websockets").setLevel(logging.DEBUG) +``` + +TypeScript has no equivalent switch for the transport. Pass a lower `logLevel` when creating the client for the SDK's own output — see [Configuration](/sdk/installation#configuration) — and inspect the wire with `NODE_DEBUG=http`, or the network panel in your browser's DevTools. + +### Validate Configuration + +When calls fail before you can pin down a specific error, check these four things in order: + + + + Open `/api/v1/market/assets` in a browser. The SDK appends `/api/v1` itself, so the config value must not already include it. + + + + `client.hasNode()` / `client.has_node()` returns `false` whenever `nodeUrl` / `node_url` was omitted, and every `client.rln.*` call will fail on that alone. + + + + `client.rln.getNodeInfo()` / `get_node_info()` returning a pubkey proves the node is both reachable and unlocked. + + + + A Signet `baseUrl` paired with a mainnet node yields confusing empty results rather than a clean error. + + + ## Get Help -Check the [FAQ](/sdk/faq) for questions rather than errors. For anything else, report a problem through your preferred channel from the options below, including: +Check the [FAQ](/sdk/faq) for questions rather than errors, and [Additional Resources](/sdk/additional-resources) for upstream documentation and links. + +For anything else, report a problem through your preferred channel from the options below, including: 1. SDK version (`getVersion()` / `get_version()`) 2. Language and runtime version (Node.js / Python) 3. Error message and stack trace 4. Minimal code to reproduce -5. Environment (Regtest / Signet / Mainnet) +5. Environment (Signet / Mainnet) Ask the community. - + Report a bug on the relevant repository. diff --git a/mintlify-docs/sdk/utilities.mdx b/mintlify-docs/sdk/utilities.mdx index e969be0..df43d09 100644 --- a/mintlify-docs/sdk/utilities.mdx +++ b/mintlify-docs/sdk/utilities.mdx @@ -257,7 +257,7 @@ console.log(getVersion()); // "0.1.0" -- returns a hardcoded value, not the pac ```python Python from kaleido_sdk import get_version -print(get_version()) # "0.1.17" +print(get_version()) # "0.1.18" ``` diff --git a/mintlify-docs/sdk/websocket.mdx b/mintlify-docs/sdk/websocket.mdx index 1013ae6..8df5af2 100644 --- a/mintlify-docs/sdk/websocket.mdx +++ b/mintlify-docs/sdk/websocket.mdx @@ -19,18 +19,18 @@ Before streaming quotes, enable the WebSocket connection: ```typescript TypeScript -const ws = client.maker.enableWebSocket('wss://api.signet.kaleidoswap.com/ws/my-client-id'); +const ws = client.maker.enableWebSocket('wss://api.signet.kaleidoswap.com/api/v1/market/ws/my-client-id'); ``` ```python Python -ws = client.maker.enable_websocket("wss://api.signet.kaleidoswap.com/ws/my-client-id") +ws = client.maker.enable_websocket("wss://api.signet.kaleidoswap.com/api/v1/market/ws/my-client-id") ``` The URL includes a client ID for session tracking. The `enableWebSocket` method returns a `WSClient` instance. -The examples on this page use Signet, which is also the SDK default. Match the WebSocket URL to the environment your `baseUrl` points at. See [Available Environments](/sdk/getting-started#available-environments). +The examples on this page use Signet, which is also the SDK default. Match the WebSocket URL to the environment your `baseUrl` points at. See [Available Environments](/sdk/installation#available-environments). ## High-Level API @@ -170,7 +170,7 @@ For full control, use the `WSClient` directly. ```typescript TypeScript -const ws = client.maker.enableWebSocket('wss://api.signet.kaleidoswap.com/ws/my-client'); +const ws = client.maker.enableWebSocket('wss://api.signet.kaleidoswap.com/api/v1/market/ws/my-client'); await ws.connect(); console.log(`Connected: ${ws.isConnected()}`); @@ -180,7 +180,7 @@ ws.disconnect(); ``` ```python Python -ws = client.maker.enable_websocket("wss://api.signet.kaleidoswap.com/ws/my-client") +ws = client.maker.enable_websocket("wss://api.signet.kaleidoswap.com/api/v1/market/ws/my-client") await ws.connect() print(f"Connected: {ws.is_connected()}") diff --git a/mintlify-docs/snippets/versions.mdx b/mintlify-docs/snippets/versions.mdx index 39ec589..8c0a669 100644 --- a/mintlify-docs/snippets/versions.mdx +++ b/mintlify-docs/snippets/versions.mdx @@ -12,5 +12,5 @@ **SDK v{sdkVersion}** is generated against ... */} -export const sdkVersion = "0.1.17"; -export const rlnApiVersion = "0.8.0"; +export const sdkVersion = "0.1.18"; +export const rlnApiVersion = "0.9.0"; diff --git a/mintlify-docs/whats-kaleidoswap/additional-resources.mdx b/mintlify-docs/whats-kaleidoswap/additional-resources.mdx new file mode 100644 index 0000000..34bc899 --- /dev/null +++ b/mintlify-docs/whats-kaleidoswap/additional-resources.mdx @@ -0,0 +1,123 @@ +--- +title: "KaleidoSwap Additional Resources" +sidebarTitle: "Additional Resources" +description: "Every KaleidoSwap link in one place: source repositories, protocol references across Bitcoin layers, integration standards, test networks, and support channels" +--- + +This page collects the links from every product tab in one list. Each product also keeps its own, scoped to what that surface needs: [Desktop App](/desktop-app/support/additional-resources), [Extension](/extensions/kaleidoswap-extension/additional-resources), [AI Tools](/ai-tools/additional-resources), and [KaleidoSDK](/sdk/additional-resources). + +## Source Repositories + +Everything KaleidoSwap ships in the open lives under the [KaleidoSwap organisation](https://github.com/kaleidoswap). The Extension is the exception: its repository is private while the beta is closed. + + + + Source, releases, and issue tracking for the Desktop App. + + + Source, releases, and issue tracking for both the TypeScript and Python implementations. + + + The command-line client for running a node and trading from a terminal. + + + The autonomous agent, its dashboard and status API, and the `skills/` directory every loop loads from. + + + The on-device engine: tiered funnel, recipe engine, tool contract, memory and retrieval, and the eval harness. + + + The MCP gateway that composes every domain behind one connection. + + + The node the SDK and the wallet tools drive. This is the KaleidoSwap fork; the [upstream project](https://github.com/RGB-Tools/rgb-lightning-node) is maintained by RGB Tools. + + + The OpenAPI specifications every client generates its API types from, which is what keeps request and response shapes identical across languages. + + + +## Protocol Documentation + +The layers a KaleidoSwap wallet derives accounts on, and the upstream reference for each. + + + + Client-side validation and asset interfaces, for both node-less RGB-L1 and RGB over Lightning. + + + Statechain-based transfers, Lightning send and receive, and the tokens behind the Spark account. + + + VTXOs, boarding and offboarding, and the batch settlement model behind the Arkade account. + + + The federated sidechain behind L-BTC and issued assets such as USDt. + + + +## Integration Standards + +Specifications for the interfaces KaleidoSwap exposes to other software. + + + + The tool protocol every KaleidoSwap [MCP server](/ai-tools/mcp-servers) implements. + + + The browser provider standard for Lightning, injected at `window.webln`. + + + In-page Nostr signing, injected at `window.nostr`. + + + Nostr Connect remote signing over relays, via a `bunker://` string. + + + The on-device inference runtime KaleidoMind uses for LLM, embeddings, speech to text, and text to speech. + + + +See [DApp connectivity](/extensions/kaleidoswap-extension/dapp-connectivity) for how the browser providers are exposed to web pages. + +## Development & Testing + + + + Get Signet Bitcoin to fund a node and open test channels. + + + + Inspect Signet transactions, blocks, and channel opens. + + + +## Get Help + +Check the [Troubleshooting](/whats-kaleidoswap/troubleshooting) page for errors and the [Glossary](/whats-kaleidoswap/glossary) for terminology. Each product also keeps its own FAQ and troubleshooting under its Reference group. + +When reporting a problem, include the product and version you are running, the network you are on (Signet or mainnet), the steps to reproduce, and the error message or a screenshot. The product-specific pages list the extra details worth attaching, such as log file locations and version commands. + +| Product | Issue tracker | +|---------|---------------| +| Desktop App | [desktop-app/issues](https://github.com/kaleidoswap/desktop-app/issues) | +| KaleidoSDK | [kaleido-sdk/issues](https://github.com/kaleidoswap/kaleido-sdk/issues) | +| KaleidoCLI | [kaleido-cli/issues](https://github.com/kaleidoswap/kaleido-cli/issues) | +| AI Tools | The repository for the surface that failed: [kaleido-agent](https://github.com/kaleidoswap/kaleido-agent/issues), [kaleido-mind](https://github.com/kaleidoswap/kaleido-mind/issues), or [kaleido-mcp](https://github.com/kaleidoswap/kaleido-mcp/issues) | +| Extension | Private repository during the beta, use Telegram or email | + + + + Ask the community. + + + Issues, pull requests, and the full source. + + + Direct support for urgent issues. + + + + + **Never share your private keys or mnemonic seed with anyone, including support staff.** Legitimate support will never ask for this information. + diff --git a/mintlify-docs/whats-kaleidoswap/glossary.mdx b/mintlify-docs/whats-kaleidoswap/glossary.mdx index 946ecbd..1b06e5c 100644 --- a/mintlify-docs/whats-kaleidoswap/glossary.mdx +++ b/mintlify-docs/whats-kaleidoswap/glossary.mdx @@ -386,6 +386,6 @@ description: "Key terms for trading across Bitcoin Layers, explaining atomic swa --- - + This glossary is continuously updated. If you encounter unfamiliar terms not listed here, please let us know via our [support channels](/desktop-app/support/additional-resources). - + diff --git a/mintlify-docs/whats-kaleidoswap/introduction.mdx b/mintlify-docs/whats-kaleidoswap/introduction.mdx index 2a4fceb..bddcc0c 100644 --- a/mintlify-docs/whats-kaleidoswap/introduction.mdx +++ b/mintlify-docs/whats-kaleidoswap/introduction.mdx @@ -105,7 +105,7 @@ Build on KaleidoSwap with our SDKs, APIs, and AI Tools: `npm install kaleido-sdk` for TypeScript, `pip install kaleido-sdk` for Python. - [Installation Guide →](/sdk/getting-started) + [Installation Guide →](/sdk/installation) diff --git a/mintlify-docs/whats-kaleidoswap/quickstart.mdx b/mintlify-docs/whats-kaleidoswap/quickstart.mdx index cf71655..b31b3dd 100644 --- a/mintlify-docs/whats-kaleidoswap/quickstart.mdx +++ b/mintlify-docs/whats-kaleidoswap/quickstart.mdx @@ -31,9 +31,9 @@ description: "Set up KaleidoSwap and make your first non-custodial swap in minut - [Windows](https://github.com/kaleidoswap/desktop-app/releases) - [Linux (AppImage)](https://github.com/kaleidoswap/desktop-app/releases) - + Always verify the binary signatures before installing. [Learn how →](/desktop-app/getting-started/verify-binaries) - + @@ -97,9 +97,9 @@ description: "Set up KaleidoSwap and make your first non-custodial swap in minut 3. Click **Load unpacked** and select the extracted folder 4. Pin the KaleidoSwap icon to your toolbar - + Full walkthrough, including checksum verification: [Installation Guide →](/extensions/kaleidoswap-extension/installation) - + diff --git a/mintlify-docs/whats-kaleidoswap/troubleshooting.mdx b/mintlify-docs/whats-kaleidoswap/troubleshooting.mdx index a90d934..5bf776d 100644 --- a/mintlify-docs/whats-kaleidoswap/troubleshooting.mdx +++ b/mintlify-docs/whats-kaleidoswap/troubleshooting.mdx @@ -1,559 +1,68 @@ --- -title: "KaleidoSwap Troubleshooting" -sidebarTitle: "Troubleshooting" -description: "Fix common KaleidoSwap issues across the Desktop App, Browser Extension, API, and SDK, from connection errors and stuck swaps to channel problems and recovery" +title: "FAQ & Troubleshooting" +description: "Where to find answers for each KaleidoSwap product: the FAQ and troubleshooting pages for the Desktop App, Browser Extension, AI Tools, and SDK, plus API error handling" --- -## Desktop Application +Every product keeps its own FAQ for questions and troubleshooting page for errors. Pick the surface you are using. -### Installation & Startup Issues +## Desktop App - - - **Symptoms**: Double-clicking the application does nothing or shows an error. - - **Solutions**: - 1. **macOS**: Check if the app is blocked by Gatekeeper - - Go to System Preferences → Security & Privacy - - Click "Open Anyway" if you see a message about KaleidoSwap - - 2. **Windows**: Run as Administrator - - Right-click the app → Run as Administrator - - Check Windows Defender hasn't quarantined the file - - 3. **Linux**: Check execution permissions - ```bash - chmod +x kaleidoswap-desktop - ``` - - 4. Check system requirements: - - 4GB RAM minimum - - 500MB free disk space - - Supported OS version (macOS 12+, Windows 10+ 64-bit, Ubuntu 22.04+) - - - - **Symptoms**: SHA256 checksum doesn't match the published hash. - - **Solutions**: - 1. Re-download the application from the official [GitHub releases](https://github.com/kaleidoswap/desktop-app/releases) - 2. Ensure you're downloading the correct file for your platform - 3. Use a reliable download connection (corrupted downloads can cause mismatches) - 4. Verify you're comparing against the correct version's checksum - - See the [Binary Verification](/desktop-app/getting-started/verify-binaries) guide for detailed steps. - - - - **Symptoms**: Application opens briefly then closes, or shows a crash dialog. - - **Solutions**: - 1. Check the log files: - - macOS: `~/Library/Logs/com.kaleidoswap.dev/` - - Windows: `%APPDATA%\com.kaleidoswap.dev\logs` - - Linux: `~/.local/share/com.kaleidoswap.dev/logs` - - 2. Common causes: - - **Corrupted configuration**: Delete the config file and restart - - **Port conflict**: Another app is using the required ports (9735, 3001) - - **Missing dependencies**: Reinstall the application - - 3. If the crash persists, attach the most recent log file from the directory above when contacting support or opening a GitHub issue. - - - -### Node & Connection Issues - - - - **Symptoms**: Error messages about LSP connection, or unable to open channels. - - **Solutions**: - 1. **Check your internet connection** - - Ensure you have a stable internet connection - - Try accessing other websites to verify connectivity - - 2. **Verify LSP URL** - - Default: `https://api.signet.kaleidoswap.com` - - Check Settings → LSP Configuration - - 3. **Firewall/VPN issues** - - Disable VPN temporarily to test - - Allow KaleidoSwap through your firewall - - Required ports: 9735 (Lightning P2P), 3001 (node API) - - 4. **Check LSP status** - - Visit the LSP's status page or contact support - - Try switching to a different LSP if available - - - - **Symptoms**: Blockchain sync taking hours or appearing stuck. - - **Solutions**: - 1. **Normal behavior**: Initial sync can take 30 minutes to several hours depending on: - - Your internet speed - - Your system's disk speed - - Network congestion - - 2. **Check sync progress**: - - Look for block height in the UI - - Compare against current network height - - 3. **Stuck sync troubleshooting**: - - Restart the application - - Check available disk space (need at least 10GB free) - - Clear peer list and reconnect - - Check firewall isn't blocking P2P connections - - - - **Symptoms**: "No peers connected" or low peer count. - - **Solutions**: - 1. **Wait**: Peer discovery can take a few minutes - - 2. **Check network settings**: - - Ensure UPnP is enabled on your router (for incoming connections) - - Manually forward port 9735 if UPnP unavailable - - 3. **Bootstrap nodes**: - - The app should connect to bootstrap nodes automatically - - If not, check your internet connection and firewall - - 4. **Network selection**: - - Verify you're on the correct network (Mainnet/Testnet/Signet/Regtest) - - Peers must be on the same network - - - -### Wallet & Asset Issues - - - - **Symptoms**: Expecting funds but balance shows 0 or is incorrect. - - **Solutions**: - 1. **Wait for sync**: Balance won't show until node is fully synced - 2. **Check the correct network**: Ensure you're on the network where you have funds - 3. **Verify wallet recovery**: If you restored from seed, ensure you used the correct mnemonic - 4. **Check asset vs BTC balance**: Toggle between Bitcoin and RGB asset views - 5. **Refresh**: Try restarting the application - - - - **Symptoms**: Password not working, wallet stays locked. - - **Solutions**: - 1. **Verify password**: Passwords are case-sensitive - 2. **Caps Lock**: Check if Caps Lock is accidentally on - 3. **Different keyboard layout**: Ensure same keyboard layout as when password was set - 4. **Wallet recovery**: If password is truly lost, you'll need to recover using your mnemonic seed - 5. **Contact support**: As a last resort, contact support with your wallet public key (never share private keys) - - - - **Symptoms**: Received an asset but it doesn't show in your wallet. - - **Solutions**: - 1. **Wait for confirmation**: RGB asset transfers require Bitcoin confirmations - 2. **Import consignment**: You may need to manually import the consignment data - 3. **Check asset ID**: Verify you're looking at the correct asset - 4. **Refresh asset list**: Settings → Assets → Refresh - 5. **Verify sender completed transfer**: Contact sender to confirm they finished the send process - - - -### Channel Operations - - - - **Symptoms**: Channel order fails or gets stuck. - - **Solutions**: - 1. **Check order status**: Use Order ID to check status via API or support - - 2. **Common failure reasons**: - - **Insufficient funds**: Need to cover channel amount + fees - - **Payment timeout**: Invoice expired before payment - - **Invalid parameters**: Check min/max channel sizes - - **LSP unavailable**: Temporary LSP downtime - - 3. **Refund process**: - - If order fails, refunds are automatic to your refund address - - Refunds may take 6+ confirmations to appear - - 4. **Retry**: - - Wait a few minutes and try again - - Reduce channel size if at maximum - - Verify sufficient inbound liquidity - - - - **Symptoms**: Channel exists but cannot send/receive payments. - - **Solutions**: - 1. **Wait for confirmations**: Channels need blockchain confirmations to become active - - Typically 3-6 confirmations required - - Check confirmation count in channel details - - 2. **Peer offline**: Your channel partner needs to be online - - Wait for peer to come back online - - Check "Last Seen" timestamp - - 3. **Channel reserves**: Cannot spend below channel reserve amount - - Lightning channels require keeping a reserve balance - - This is normal protocol behavior - - 4. **Force close**: If channel is permanently stuck, you can force-close - - This puts funds back on-chain after a delay - - Should be last resort - - - - **Symptoms**: Channel opened but RGB assets not yet delivered. - - **Solutions**: - 1. **Normal delay**: Asset delivery via keysend can take a few minutes - - Automatic retry mechanism in place - - Can take up to 30 minutes in some cases - - 2. **Check delivery status**: - - Order details show asset delivery status - - Statuses: PENDING → IN_PROGRESS → COMPLETED - - 3. **Manual retry**: - - Use "Retry Delivery" button if available - - 4. **Failed delivery**: - - Contact LSP support with Order ID - - Refund may be available if delivery cannot complete - - - -### Trading & Swaps - - - - **Symptoms**: Swap doesn't complete or expires. - - **Solutions**: - 1. **Quote expiration**: RFQ quotes are short-lived — about 60 seconds by default, and each quote carries its own `expires_at` - - Complete swap before expiration - - Request new quote if expired - - 2. **Rate changed**: Market rate changed significantly - - Accept new rate when prompted - - Or cancel and get refund - - 3. **Payment routing failed**: Lightning payment couldn't find a route - - Try smaller amount - - Open additional channels for more liquidity - - Wait and retry - - 4. **Swap stuck**: - - Check swap status: `POST /api/v1/swaps/atomic/status` (by payment hash) - - Contact support with the payment hash for assistance - - - - **Symptoms**: Final price different from expected. - - **Solutions**: - 1. **Check quote details**: Review the RFQ response carefully - - `from_amount` vs `to_amount` - - Applied fees - - Precision of assets - - 2. **Fee structure**: - - Base fee + variable fee - - Fee asset and precision - - Total fee shown in quote - - 3. **Precision confusion**: - - BTC uses 8 decimals - - USDT typically uses 6 decimals - - Check asset precision in glossary - - 4. **Slippage**: - - For market orders, price can move slightly - - Use limit orders if you need exact price - - - - - For failed trades, wallet restore, and LSP connection questions, see [Desktop App Troubleshooting](/desktop-app/support/troubleshooting). - + + + Wallets, channels, swaps, fees, and security. + + + Startup, node sync, channel, and swap failures. + + ## Browser Extension -The cases below are specific to how the closed beta is installed and how its accounts are backed. - -### Installation & Updates - - - - **Symptoms**: `chrome://extensions` rejects the folder, or a working extension stops loading after a while. - - **Solutions**: - 1. **Select the right folder**: Choose the folder that contains `manifest.json`. If the archive has a `dist` folder, select `dist`. - 2. **Don't move or delete the extracted folder**: The browser loads the extension from that path every time. Moving it to another disk, renaming it, or clearing a Downloads folder breaks the install. - 3. **Extract first**: Point the browser at the extracted folder, not at the zip. - 4. **Re-add it**: Remove the broken card in `chrome://extensions` and load the folder again. Your wallet is not stored in that folder, so this does not touch your funds. - - - - **Symptoms**: You installed a newer zip but the extension still behaves like the old version. - - **Solutions**: - 1. Closed beta builds **do not auto-update** — there is no store listing to push them. - 2. After extracting the new zip, go to `chrome://extensions` and click **Reload** on the KaleidoSwap card. - 3. If you extracted into a **different folder**, remove the old unpacked extension and load the new folder instead — otherwise the browser keeps running the old one. - 4. Confirm the version under **Settings > About**. - - - - **Symptoms**: The beta zip cannot be loaded at all. - - **Solutions**: - 1. The closed beta targets **Chromium-based browsers**: Chrome, Brave, Edge, Opera. - 2. **Firefox** is not part of the first closed beta unless a Firefox build is provided, and **Safari** is not supported yet. - 3. **Developer mode** must be toggled on in `chrome://extensions` before **Load unpacked** appears. - 4. Install only archives from the official invite or support channel — never a forwarded copy. - - - -### Accounts & Balances - - - - **Symptoms**: RGB balances were visible, then vanished once an RGB Lightning Node was connected. - - **Explanation**: The node-less **RGB-L1** account and the **RLN** account are *mutually exclusive* backings for RGB assets. Connecting RLN replaces the node-less backing, so you are looking at a different account — the RGB-L1 state has not been lost. - - **Solutions**: - 1. Disconnect RLN in **Settings > Accounts > RGB** to return to the node-less RGB-L1 backing. - 2. Decide which backing you want: node-less for RGB on Bitcoin L1, RLN for RGB **Lightning channels** and maker-based swaps. - 3. Before switching, make sure the backing you are leaving is backed up — RGB-L1 to its cloud (VSS) and local backups, RLN to the node's own backup material. - - - - **Symptoms**: Spark, Arkade, and Liquid balances came back after importing the recovery phrase, but RGB assets did not. - - **Solutions**: - 1. RGB-L1 state is **not** derived from the recovery phrase — it is restored from the encrypted cloud (VSS) backup, and only if you **explicitly consent** at that onboarding step. Skipping the prompt leaves the state behind. - 2. Re-import the wallet and accept the restore prompt when it appears. - 3. If you use RLN instead, RGB state must be recovered from the node's own backup material, not from the extension. - - - - **Symptoms**: You restored using an `nsec1…` key and the wallet is empty. - - **Solutions**: - 1. A Nostr key **does not control funds**. Importing one only replaces the Nostr identity. - 2. Always restore with the **BIP39 recovery phrase** — it is what derives the Spark, Arkade, Liquid, and RGB-L1 accounts. - 3. Re-import using the recovery phrase; you can import the Nostr key afterwards from Settings. - - - -### Swaps & Bridge - - - - **Symptoms**: The swap screen refuses an amount you appear to hold. - - **Solutions**: - 1. The amount input is gated by your **spendable** balance for the source asset, not the total balance, so you cannot quote more than the wallet can actually send. - 2. On-chain sends also reserve the network fee — **Max** accounts for this automatically. - 3. Check that the balance is on the account the selected route uses; balances are tracked per layer. - - - - **Symptoms**: A quoted swap ends in failure rather than filling at a worse rate. - - **Solutions**: - 1. This is **slippage protection** working as intended: the minimum output is derived from your configured tolerance, and the swap fails rather than executing beyond it. - 2. Re-quote — quotes expire, and the rate may have moved since. - 3. Adjust your slippage tolerance if the market is genuinely volatile, or reduce the size. - - - - **Symptoms**: You closed the extension mid-bridge and the order is no longer on screen. - - **Solutions**: - 1. Bridge orders are **saved locally as a session**. Reopening the bridge screen restores the pending order and resumes tracking, even after the service worker restarts. - 2. Completed and failed orders show a final status with the relevant transaction references. - 3. Deposits confirm on the source chain first — an order can sit in progress while that happens. - - - - - For node connection, payment, and DApp provider problems, see [KaleidoSwap Extension Troubleshooting](/extensions/kaleidoswap-extension/troubleshooting). - - -## API & Integration - -### Authentication & Connection - - - - **Symptoms**: API returns 401 status code. - - **Solutions**: - 1. **Bearer token**: Ensure you're sending authentication token correctly - ```http - Authorization: Bearer YOUR_TOKEN_HERE - ``` - - 2. **Token expiration**: Tokens may expire - obtain a new one - - 3. **Incorrect endpoint**: Verify you're using the correct API base URL - - Signet (live): `https://api.signet.kaleidoswap.com/api/v1` - - Mainnet: `https://api.kaleidoswap.com/api/v1` *(coming soon)* - - - - **Symptoms**: API returns 422 with validation errors. - - **Solutions**: - 1. **Check request body**: Ensure all required fields are present - 2. **Data types**: Verify integers, strings, booleans are correct type - 3. **Field validation**: Check min/max values, formats - 4. **Read error details**: The response includes which fields failed validation - - Example error response: - ```json - { - "detail": [ - { - "loc": ["body", "from_amount"], - "msg": "field required", - "type": "value_error.missing" - } - ] - } - ``` - - - - **Symptoms**: Browser blocks API requests with CORS error. - - **Solutions**: - 1. **Use backend**: Make API calls from your backend, not frontend - - CORS is disabled for security on most endpoints - - Browser-based apps need a backend proxy - - 2. **Development workaround**: - - Use browser CORS plugin (development only) - - Configure your dev server as proxy - - 3. **Production**: Always use server-side API calls - - - -### RFQ & Order Issues - - - - **Symptoms**: Using RFQ ID returns error about expiration. - - **Solutions**: - 1. **Check expires_at**: Quotes are valid for about 60 seconds by default; always read the quote's own `expires_at` rather than assuming a fixed window - 2. **Request new quote**: Call `/api/v1/market/quote` again - 3. **Faster integration**: Minimize time between quote and order creation - 4. **Use expiration time**: Build UI countdown showing time remaining - - - - **Symptoms**: Order doesn't progress from PENDING_PAYMENT or other status. - - **Solutions**: - 1. **Payment required**: Check if you need to pay an invoice or send to an address - 2. **Check payment status**: - ```bash - POST /api/v1/lsps1/get_order - { - "order_id": "your-order-id" - } - ``` - - 3. **Automatic transitions**: Some states transition automatically - - PENDING_PAYMENT → PAID (after payment confirmed) - - CHANNEL_OPENING → COMPLETED (after channel opens) - - 4. **Timeouts**: Orders expire if not paid within time limit - - Check `expires_at` field - - Unpaid orders auto-expire and refund - - - - - For the full list of HTTP status codes, the error response format, and retry strategies, see [Error Handling](/api-reference/error-handling) in the API Reference. - - -## SDK - -Both SDK guides cover TypeScript and Python side by side — every example shows both. Pick by what you need: - - - Which exceptions the SDK raises, how to catch them, retry patterns, and HTTP status mapping. + + Accounts, recovery, supported browsers, and the closed beta. - - - Symptom-to-fix for install failures, connection errors, WebSocket problems, and language-specific gotchas. + + Connection, payment, and extension-loading problems. -**Quick tips**: -- Catch `KaleidoError` — every SDK exception extends it, and `isRetryable()` / `is_retryable()` tells you whether a retry is safe -- Enable debug logging for full request and response detail -- Check your runtime: Node.js 18+ / Python 3.10+ - -## General Best Practices +## AI Tools - - Most issues can be diagnosed from log files. Enable debug logging when troubleshooting. + + MCP servers, KaleidoAgent, KaleidoMind, and the skills. - - - Ensure you're on the correct network (Mainnet, Testnet, Signet, Regtest) for your use case. + + Tool failures, host configuration, and runtime errors. + - - Use the latest version of Desktop App and SDKs for bug fixes and improvements. - +## SDK - - Always test new integrations on Testnet before using real funds on Mainnet. + + + Language choice, sub-clients, custody, networks, and versioning. + + + Install failures, connection errors, and swap issues. -## Still Need Help? - -If these troubleshooting steps don't resolve your issue: - - - - Each product keeps its own reference: [Desktop App Troubleshooting](/desktop-app/support/troubleshooting), [KaleidoSwap Extension Troubleshooting](/extensions/kaleidoswap-extension/troubleshooting), [KaleidoSDK Troubleshooting](/sdk/troubleshooting), and [API Error Handling](/api-reference/error-handling). - - - - Use the search bar to find specific topics in the documentation. - +## API & Integration - - See if others have reported the same problem in the repository for the component you are running. All repositories live under the [KaleidoSwap organization](https://github.com/kaleidoswap). - + + + HTTP status codes, the error response format, and retry strategies. + + + Endpoints, authentication, and the swap and LSPS1 APIs. + + - - Reach out via: - - Email: [support@kaleidoswap.com](mailto:support@kaleidoswap.com) - - Telegram: [https://t.me/kaleidoswap](https://t.me/kaleidoswap) - - GitHub Issues: open one in the repository that matches your setup, for example [Desktop App](https://github.com/kaleidoswap/desktop-app/issues/new), [KaleidoSDK](https://github.com/kaleidoswap/kaleido-sdk/issues/new), or [KaleidoCLI](https://github.com/kaleidoswap/kaleido-cli/issues/new). - - + + Each of those pages ends with a Get Help section listing the details to include when you report a problem, along with the Telegram, GitHub, and email channels. + **Never share your private keys or mnemonic seed with anyone, including support staff.** Legitimate support will never ask for this information. diff --git a/scripts/check-cn-parity.py b/scripts/check-cn-parity.py index c668719..d3550b2 100644 --- a/scripts/check-cn-parity.py +++ b/scripts/check-cn-parity.py @@ -50,7 +50,7 @@ # titles that are nothing but product names / acronyms correctly stay English PROPER_ONLY = re.compile( r"^(?:Kaleido\w*|KaleidoSwap|Nostr|Wallet|Connect|SDK|CLI|API|NWC|RGB|MCP|" - r"LSPS1|RLN|Bitcoin|Lightning|FAQ|WebSocket|REST|Taproot|Assets|" + r"LSPS1|RLN|Maker|Bitcoin|Lightning|FAQ|WebSocket|REST|Taproot|Assets|" r"[-–&/()0-9.]+)(?:\s+|$)" ) From 5e3e5e74842d1b5d740b2c404d8e583939017231 Mon Sep 17 00:00:00 2001 From: bitwalt Date: Wed, 2 Sep 2026 01:11:23 +0900 Subject: [PATCH 2/2] docs: add api-reference error-handling redirects, sync README inventory - redirect /api-reference/error-handling (+ /cn) to troubleshooting, matching the sdk redirects for the other deleted page - drop the deleted error-handling.mdx entries from the README file inventory and list the API Reference tab's current 9 pages - normalize two relative links in cn channel-requests to /cn/ paths Co-Authored-By: Claude Fable 5 --- mintlify-docs/README.md | 7 +++---- .../cn/desktop-app/channels/channel-requests.mdx | 4 ++-- mintlify-docs/docs.json | 8 ++++++++ 3 files changed, 13 insertions(+), 6 deletions(-) diff --git a/mintlify-docs/README.md b/mintlify-docs/README.md index 450353b..b51e699 100644 --- a/mintlify-docs/README.md +++ b/mintlify-docs/README.md @@ -83,7 +83,6 @@ The documentation will be available at `http://localhost:3000` - `api-reference.mdx` - Complete API documentation - `types.mdx` - Pydantic models and enums - `examples.mdx` - Real-world code examples -- `error-handling.mdx` - Exception handling guide - `websocket.mdx` - Real-time data streaming - `utilities.mdx` - Helper functions @@ -94,16 +93,16 @@ The documentation will be available at `http://localhost:3000` - `api-reference.mdx` - API method documentation - `types.mdx` - Type definitions - `utilities.mdx` - Utility classes -- `error-handling.mdx` - Error management - `examples.mdx` - Code examples - `websocket.mdx` - WebSocket integration - `best-practices.mdx` - Best practices guide - `troubleshooting.mdx` - Common issues -### API Reference (6 pages) +### API Reference (9 pages) ✅ Migrated + expanded with OpenAPI -- `introduction.mdx`, `getting-started.mdx`, `error-handling.mdx` +- `introduction.mdx`, `getting-started.mdx`, `swap-protocol.mdx` - `rgb-lsps1-apis.mdx`, `market-apis.mdx`, `swap-apis.mdx` +- `faq.mdx`, `troubleshooting.mdx`, `additional-resources.mdx` - Automatic endpoint reference generated from `openapi.json` ## 🎨 Customization diff --git a/mintlify-docs/cn/desktop-app/channels/channel-requests.mdx b/mintlify-docs/cn/desktop-app/channels/channel-requests.mdx index 3e2d691..9e31022 100644 --- a/mintlify-docs/cn/desktop-app/channels/channel-requests.mdx +++ b/mintlify-docs/cn/desktop-app/channels/channel-requests.mdx @@ -3,7 +3,7 @@ title: 通道请求 description: "在 KaleidoSwap 桌面应用中向闪电服务提供商申请入向通道，配置容量与时长，并随时跟踪每个通道请求的处理状态" --- -除了与其他节点[开通通道](./opening-channel)之外，你还可以向 LSP 申请入向通道，代价是让出节点所持流动性的一定比例。当你需要入向容量来接收支付时，这种方式很有用。 +除了与其他节点[开通通道](/cn/desktop-app/channels/opening-channel)之外，你还可以向 LSP 申请入向通道，代价是让出节点所持流动性的一定比例。当你需要入向容量来接收支付时，这种方式很有用。 ## 申请入向通道 @@ -44,7 +44,7 @@ description: "在 KaleidoSwap 桌面应用中向闪电服务提供商申请入 --- -*下一步：[通道备份](./channel-backups)* +*下一步：[通道备份](/cn/desktop-app/channels/channel-backups)* --- diff --git a/mintlify-docs/docs.json b/mintlify-docs/docs.json index ffaa910..d8d6806 100644 --- a/mintlify-docs/docs.json +++ b/mintlify-docs/docs.json @@ -712,6 +712,14 @@ { "source": "/cn/sdk/error-handling", "destination": "/cn/sdk/troubleshooting" + }, + { + "source": "/api-reference/error-handling", + "destination": "/api-reference/troubleshooting" + }, + { + "source": "/cn/api-reference/error-handling", + "destination": "/cn/api-reference/troubleshooting" } ], "footer": {