KaleidoSDK 快速上手

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

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

要确认哪个 SDK 版本对应哪个 API 版本，请参阅 Maker API 兼容性和 RLN API 兼容性。

安装

npm install kaleido-sdk

pnpm add kaleido-sdk

yarn add kaleido-sdk

pip install kaleido-sdk

环境要求

TypeScript
Python

Node.js 18 或更高版本
推荐 TypeScript 5.x

基础设置

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`);

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

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

配置

TypeScript

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

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() 接收关键字参数：

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

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

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

可用环境

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

子客户端架构

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

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

节点配置检查

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

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

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)

第一笔报价

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

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)

简介

版本与兼容性

核心参考

指南

参考

安装

环境要求

基础设置

配置

TypeScript

Python

环境变量

可用环境

子客户端架构

节点配置检查

第一笔报价

​安装

​环境要求

​基础设置

​配置

​TypeScript

​Python

​环境变量

​可用环境

​子客户端架构

​节点配置检查

​第一笔报价

安装

环境要求

基础设置

配置

TypeScript

Python

环境变量

可用环境

子客户端架构

节点配置检查

第一笔报价