Skip to main content

​
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.

TypeScript SDK

Pure TypeScript using openapi-fetch with full type inference

Python SDK

Pure Python using httpx with Pydantic models for type-safe development

​
Architecture

Both SDKs share the same API design and are built independently: KaleidoSwap SDK Architecture Your application connects through KaleidoClient, which provides two sub-clients: MakerClient for market operations (quotes, orders, swaps) and RlnClient for RGB Lightning Node operations (wallets, channels, invoices). Both use HTTP clients internally, with optional WebSocket support for real-time streaming.

​
Key Benefits

  • Type Safety: Auto-generated types from OpenAPI specs in both languages
  • Consistent API: Identical structure across TypeScript and Python
  • Sub-client Design: Organized access via client.maker and client.rln
  • WebSocket Support: Real-time quote streaming with automatic reconnection

​
What is KaleidoSwap?

KaleidoSwap is a decentralized exchange protocol for Bitcoin and RGB assets. It enables trading of digital assets through order-based swaps on the Lightning Network and on-chain Bitcoin transactions.

​
SDK Dual Purpose

Our SDK serves two primary functions: Maker API Integration (client.maker) Connect to KaleidoSwap’s maker APIs for:
  • Getting quotes for asset pairs
  • Creating and managing swap orders
  • Streaming real-time quotes via WebSocket
  • LSPS1 channel ordering
RLN (RGB Lightning Node) Operations (client.rln) Direct interaction with RGB Lightning Nodes for:
  • Wallet management and RGB asset operations
  • Lightning channel management
  • Invoice creation and payment
  • Node-to-node swap coordination

​
Key Features

  • Sub-client Architecture: Organized API access via client.maker and client.rln
  • Type Safety: Full TypeScript types and Python Pydantic models
  • WebSocket Support: Real-time quote streaming with automatic reconnection
  • Error Handling: Comprehensive exception hierarchy across both SDKs
  • Dual API Support: Seamlessly work with both Maker APIs and RLN node operations
  • RGB Asset Trading: Full support for trading RGB assets on Lightning and on-chain
  • Order-Based Swaps: Create swap orders, pay deposits, and track execution

​
Quick Start

npm install kaleidoswap-sdk

​
Maker API Trading

import { KaleidoClient } from 'kaleidoswap-sdk';

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

// Get available trading pairs
const pairs = await client.maker.listPairs();
console.log(`Found ${pairs.pairs.length} trading pairs`);

// Get a quote
const quote = await client.maker.getQuote({
  from_asset: { asset_id: 'BTC', layer: 'BTC_LN', amount: 100000 },
  to_asset: { asset_id: 'USDT', layer: 'RGB_LN' }
});
console.log(`Price: ${quote.price}`);

​
RLN Node Operations

import { KaleidoClient } from 'kaleidoswap-sdk';

const client = KaleidoClient.create({
  baseUrl: 'https://api.regtest.kaleidoswap.com',
  nodeUrl: 'http://localhost:3001'
});

if (client.hasNode()) {
  const nodeInfo = await client.rln.getNodeInfo();
  const balance = await client.rln.getBtcBalance();
  console.log(`BTC Balance: ${balance.vanilla.spendable} sats`);
}

​
Documentation Structure

​
Support

Need help? Check out our: