> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaleidoswap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# KaleidoSDK 快速上手

> 在 TypeScript 或 Python 中安装并配置 KaleidoSDK，了解客户端、接口端点与环境设置，几分钟内获取你的第一笔交换报价。

`kaleido-sdk`（TypeScript）和 `kaleido_sdk`（Python）由同一份 Maker API 与 RGB Lightning Node 规范生成，并在其上封装了手写客户端：

* `client.maker` 对应 KaleidoSwap 的市场、交换和 LSPS1 接口端点
* `client.rln` 对应 RGB Lightning Node 的钱包、通道、支付和交换接口端点

<Note>
  要确认哪个 SDK 版本对应哪个 API 版本，请参阅 [Maker API 兼容性](/cn/sdk/maker-api-compatibility) 和 [RLN API 兼容性](/cn/sdk/rln-api-compatibility)。
</Note>

## 安装

<CodeGroup>
  ```bash npm theme={null}
  npm install kaleido-sdk
  ```

  ```bash pnpm theme={null}
  pnpm add kaleido-sdk
  ```

  ```bash yarn theme={null}
  yarn add kaleido-sdk
  ```

  ```bash pip theme={null}
  pip install kaleido-sdk
  ```
</CodeGroup>

### 环境要求

<Tabs>
  <Tab title="TypeScript">
    * Node.js 18 或更高版本
    * 推荐 TypeScript 5.x
  </Tab>

  <Tab title="Python">
    * Python 3.10 或更高版本
    * 运行时依赖会自动安装
  </Tab>
</Tabs>

## 基础设置

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { KaleidoClient } from 'kaleido-sdk';

  const client = KaleidoClient.create({
    baseUrl: 'https://api.signet.kaleidoswap.com',
  });

  const assets = await client.maker.listAssets();
  console.log(`Found ${assets.assets.length} assets`);
  ```

  ```python Python theme={null}
  from kaleido_sdk import KaleidoClient

  client = KaleidoClient.create(
      base_url="https://api.signet.kaleidoswap.com"
  )

  assets = await client.maker.list_assets()
  print(f"Found {len(assets.assets)} assets")
  ```
</CodeGroup>

<Note>
  `KaleidoClient.create()` 在两个 SDK 中都是同步方法。创建客户端时不要使用 `await`。
</Note>

## 配置

### TypeScript

`KaleidoClient.create()` 接收一个 `KaleidoConfig` 对象：

```typescript theme={null}
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 theme={null}
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               |

<CodeGroup>
  ```typescript TypeScript theme={null}
  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 theme={null}
  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"),
  )
  ```
</CodeGroup>

<h2 id="available-environments">
  可用环境
</h2>

将 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}`        | 即将上线    |

## 子客户端架构

<CodeGroup>
  ```typescript TypeScript theme={null}
  const client = KaleidoClient.create({
    baseUrl: 'https://api.signet.kaleidoswap.com',
    nodeUrl: 'http://localhost:3001',
  });

  const pairs = await client.maker.listPairs();

  if (client.hasNode()) {
    const nodeInfo = await client.rln.getNodeInfo();
    const channels = await client.rln.listChannels();
  }
  ```

  ```python Python theme={null}
  client = KaleidoClient.create(
      base_url="https://api.signet.kaleidoswap.com",
      node_url="http://localhost:3001",
  )

  pairs = await client.maker.list_pairs()

  if client.has_node():
      node_info = await client.rln.get_node_info()
      channels = await client.rln.list_channels()
  ```
</CodeGroup>

<h2 id="node-configuration-checks">
  节点配置检查
</h2>

TypeScript 提供 `client.hasNode()`，并且始终返回一个 `rln` 客户端实例。Python 提供 `client.has_node()`，如果缺少 `node_url`，访问 `client.rln` 会抛出 `NodeNotConfiguredError`。

<CodeGroup>
  ```typescript TypeScript theme={null}
  if (!client.hasNode()) {
    console.log('Node URL not configured; only maker operations are available');
  } else {
    const nodeInfo = await client.rln.getNodeInfo();
    console.log(nodeInfo.pubkey);
  }
  ```

  ```python Python theme={null}
  if not client.has_node():
      print("Node URL not configured; only maker operations are available")
  else:
      node_info = await client.rln.get_node_info()
      print(node_info.pubkey)
  ```
</CodeGroup>

## 第一笔报价

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { KaleidoClient, Layer } from 'kaleido-sdk';

  const client = KaleidoClient.create();

  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,
    },
  });

  console.log(quote.rfq_id);
  console.log(quote.price);
  ```

  ```python Python theme={null}
  from kaleido_sdk import KaleidoClient, Layer, PairQuoteRequest, SwapLegInput

  client = KaleidoClient.create()

  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),
      )
  )

  print(quote.rfq_id)
  print(quote.price)
  ```
</CodeGroup>