Skip to main content

​
Overview

Both SDKs auto-generate types from the same OpenAPI specifications, ensuring consistency:
  • TypeScript: Types generated via openapi-fetch with full type inference
  • Python: Pydantic models generated from the OpenAPI specs

​
Configuration

​
KaleidoConfig

interface KaleidoConfig {
  baseUrl: string;        // Required: API base URL
  nodeUrl?: string;       // Optional: RGB Lightning Node URL
  apiKey?: string;        // Optional: API key
  timeout?: number;       // Optional: timeout in seconds (default: 30)
  maxRetries?: number;    // Optional: max retries (default: 3)
  cacheTtl?: number;      // Optional: cache TTL in seconds (default: 60)
}

​
Layer Types

The Layer type defines all supported network layers for asset transfers. 
type Layer =
  | 'BTC_L1'           // Bitcoin on-chain
  | 'BTC_LN'           // Bitcoin Lightning
  | 'BTC_SPARK'        // Bitcoin Spark
  | 'BTC_ARKADE'       // Bitcoin Arkade
  | 'BTC_LIQUID'       // Bitcoin Liquid
  | 'BTC_CASHU'        // Bitcoin Cashu
  | 'RGB_L1'           // RGB on-chain
  | 'RGB_LN'           // RGB Lightning
  | 'TAPASS_L1'        // Taproot Assets on-chain
  | 'TAPASS_LN'        // Taproot Assets Lightning
  | 'LIQUID_LIQUID'    // Liquid network
  | 'ARKADE_ARKADE'    // Arkade network
  | 'SPARK_SPARK';     // Spark network

// Runtime enum for Layer values
import { LayerEnum } from 'kaleidoswap-sdk';
const layer = LayerEnum.BTC_LN;

​
Receiver Address Formats

The ReceiverAddressFormat type defines address formats for each layer. 
type ReceiverAddressFormat =
  | 'BTC_ADDRESS'        // Standard Bitcoin address (bc1q...)
  | 'BOLT11'             // Lightning BOLT11 invoice
  | 'BOLT12'             // Lightning BOLT12 offer
  | 'LN_ADDRESS'         // Lightning Address (user@domain)
  | 'RGB_INVOICE'        // RGB invoice
  | 'LIQUID_ADDRESS'     // Liquid address
  | 'LIQUID_INVOICE'     // Liquid invoice
  | 'SPARK_ADDRESS'      // Spark address
  | 'SPARK_INVOICE'      // Spark invoice
  | 'ARKADE_ADDRESS'     // Arkade address
  | 'ARKADE_INVOICE'     // Arkade invoice
  | 'CASHU_TOKEN';       // Cashu token

import { ReceiverAddressFormatEnum } from 'kaleidoswap-sdk';
const format = ReceiverAddressFormatEnum.BOLT11;

​
Market Types

​
Asset

Represents a tradeable asset. 
// Auto-generated from OpenAPI
type Asset = components['schemas']['Asset'];
// Fields: asset_id, ticker, name, precision, ...

​
TradingPair

Represents a trading pair with routes and limits. 
type TradingPair = components['schemas']['TradingPair'];
// Fields: base_asset_ticker, quote_asset_ticker, routes, ...

​
Quote / PairQuoteResponse

A price quote for a swap. 
type Quote = components['schemas']['PairQuoteResponse'];
// Fields: rfq_id, from_amount, to_amount, price, expires_at, fee, ...

​
Fee

Fee structure returned in quotes. 
// From WebSocket types
interface Fee {
  fee_asset: string;
  fee_precision: number;
  base_fee: number;
  variable_fee: number;
  fee_rate: number;
  final_fee: number;
}

​
Order Types

​
CreateSwapOrderRequest

Request to create a swap order. 
type CreateSwapOrderRequest = components['schemas']['CreateSwapOrderRequest'];
// Fields: rfq_id, from_asset, to_asset, receiver_address, min_onchain_conf

​
SwapOrder

A swap order with full details. 
type SwapOrder = components['schemas']['SwapOrder'];
// Fields: order_id, status, from_asset, to_asset, deposit_address, ...

​
Order State Enums

type OrderState = components['schemas']['OrderState'];
// Values: CREATED, PENDING_PAYMENT, PAID, EXECUTING,
//         FILLED, EXPIRED, CANCELLED, FAILED, PENDING_RATE_DECISION

type PaymentState = components['schemas']['PaymentState'];
// Values: NOT_PAID, PAID, OVERPAID, UNDERPAID

type PaymentStatus = components['schemas']['PaymentStatus'];
// Payment processing status

​
Node Types (RLN)

These types are used with client.rln operations. They are auto-generated from the RLN node OpenAPI spec.

​
NodeInfoResponse

type NodeInfoResponse = nodeComponents['schemas']['NodeInfoResponse'];
// Fields: pubkey, alias, color, num_channels, ...

​
BtcBalanceResponse

type BtcBalanceResponse = nodeComponents['schemas']['BtcBalanceResponse'];
// Fields: vanilla { settled, future, spendable }, colored { settled, future, spendable }

​
Channel

type Channel = nodeComponents['schemas']['Channel'];
// Fields: channel_id, peer_pubkey, capacity, local_balance, status, ...

​
Invoice Types

type LNInvoiceResponse = nodeComponents['schemas']['LNInvoiceResponse'];
type RgbInvoiceResponse = nodeComponents['schemas']['RgbInvoiceResponse'];
type DecodeLNInvoiceResponse = nodeComponents['schemas']['DecodeLNInvoiceResponse'];

​
Asset Types

type AssetNIA = nodeComponents['schemas']['AssetNIA'];
type ListAssetsResponse = nodeComponents['schemas']['ListAssetsResponse'];
type AssetBalanceResponse = nodeComponents['schemas']['AssetBalanceResponse'];

​
WebSocket Types

import type { QuoteResponse, QuoteRequest, PongResponse, Fee } from 'kaleidoswap-sdk';

interface QuoteRequest {
  from_asset: string;
  to_asset: string;
  from_amount?: number | null;
  to_amount?: number | null;
  from_layer?: string | null;
  to_layer?: string | null;
}

interface QuoteResponse {
  action: 'quote_response';
  from_asset: string;
  to_asset: string;
  from_amount: number;
  to_amount: number;
  price: number;
  rfq_id: string;
  price_precision: number;
  timestamp: number;
  expires_at: number;
  fee: Fee;
}

​
Importing Types

// Import specific types
import type {
  KaleidoConfig,
  Asset,
  TradingPair,
  Quote,
  CreateSwapOrderRequest,
  SwapOrder,
  Layer,
  ReceiverAddressFormat,
  BtcBalanceResponse,
  Channel,
} from 'kaleidoswap-sdk';

// Import runtime enums
import { LayerEnum, ReceiverAddressFormatEnum } from 'kaleidoswap-sdk';

// Import raw OpenAPI components for advanced usage
import type { components, paths } from 'kaleidoswap-sdk';