Getting Started with the KaleidoSDK

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 and RLN API Compatibility.

Installation

npm install kaleido-sdk

pnpm add kaleido-sdk

yarn add kaleido-sdk

pip install kaleido-sdk

Requirements

TypeScript
Python

Node.js 18 or higher
TypeScript 5.x recommended

Basic Setup

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() is synchronous in both SDKs. Do not await client creation.

Configuration

TypeScript

KaleidoClient.create() accepts a KaleidoConfig object:

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:

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

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

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

Sub-Client Architecture

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

Node Configuration Checks

TypeScript exposes client.hasNode() and always returns an rln client instance. Python exposes client.has_node(), and client.rln raises NodeNotConfiguredError if node_url is missing.

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)

First Quote

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)

Introduction

Version & Compatibility

Core Reference

Guides

Reference

Installation

Requirements

Basic Setup

Configuration

TypeScript

Python

Environment Variables

Available Environments

Sub-Client Architecture

Node Configuration Checks

First Quote

​Installation

​Requirements

​Basic Setup

​Configuration

​TypeScript

​Python

​Environment Variables

​Available Environments

​Sub-Client Architecture

​Node Configuration Checks

​First Quote

Installation

Requirements

Basic Setup

Configuration

TypeScript

Python

Environment Variables

Available Environments

Sub-Client Architecture

Node Configuration Checks

First Quote