KaleidoSDK Best Practices

Client Initialization

Use Environment Variables

Keep configuration out of source code:

import { KaleidoClient } from 'kaleido-sdk';

const client = KaleidoClient.create({
  baseUrl: process.env.KALEIDO_API_URL!,
  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["KALEIDO_API_URL"],
    node_url=os.environ.get("KALEIDO_NODE_URL"),
    api_key=os.environ.get("KALEIDO_API_KEY"),
)

Use a Singleton Client

Create one client instance and reuse it throughout your application:

// lib/kaleido.ts
import { KaleidoClient } from 'kaleido-sdk';

let client: KaleidoClient | null = null;

export function getClient(): KaleidoClient {
  if (!client) {
    client = KaleidoClient.create({
      baseUrl: process.env.KALEIDO_API_URL!,
    });
  }
  return client;
}

# lib/kaleido.py
import os

from kaleido_sdk import KaleidoClient

_client = None

def get_client() -> KaleidoClient:
    global _client
    if _client is None:
        _client = KaleidoClient.create(
            base_url=os.environ["KALEIDO_API_URL"]
        )
    return _client

Error Handling

Always Handle Errors

Wrap SDK calls in try/catch blocks and handle specific error types. The minimum worth branching on is shown below; Error Handling has the exhaustive version.

import { KaleidoError, NetworkError, QuoteExpiredError } from 'kaleido-sdk';

try {
  const quote = await client.maker.getQuote({ /* ... */ });
} catch (error) {
  if (error instanceof QuoteExpiredError) {
    // Retry with a fresh quote
  } else if (error instanceof NetworkError && error.isRetryable()) {
    // Retry after a delay
  } else if (error instanceof KaleidoError) {
    // Log and handle gracefully
    console.error(`[${error.code}] ${error.message}`);
  }
}

from kaleido_sdk import KaleidoError, NetworkError, QuoteExpiredError, PairQuoteRequest

try:
    quote = await client.maker.get_quote(PairQuoteRequest(...))
except QuoteExpiredError:
    # Retry with a fresh quote
    pass
except NetworkError as e:
    if e.is_retryable():
        # Retry after a delay
        pass
except KaleidoError as e:
    print(f"[{e.code}] {e}")

Check Retryability

Never retry blindly. Every error exposes isRetryable() / is_retryable(), which already encodes which failures can succeed on a second attempt — use it instead of matching on status codes yourself. For the full exception hierarchy, the per-status retryability table, and a ready-made exponential-backoff wrapper, see Error Handling.

Async Patterns

TypeScript: Parallel Requests

Use Promise.all for independent requests:

const [assets, pairs, lspInfo] = await Promise.all([
  client.maker.listAssets(),
  client.maker.listPairs(),
  client.maker.getLspInfo(),
]);

Use Promise.allSettled when you want partial results:

const results = await Promise.allSettled([
  client.maker.listAssets(),
  client.maker.listPairs(),
]);

for (const result of results) {
  if (result.status === 'fulfilled') {
    console.log('Success:', result.value);
  } else {
    console.error('Failed:', result.reason);
  }
}

Python: Sequential with Error Recovery

from kaleido_sdk import KaleidoError

results = {}
for name, fn in [
    ("assets", lambda: client.maker.list_assets()),
    ("pairs", lambda: client.maker.list_pairs()),
]:
    try:
        results[name] = await fn()
    except KaleidoError as e:
        print(f"Failed to fetch {name}: {e}")
        results[name] = None

Amount Handling

Always Use Raw Units for API Calls

The API works with raw (smallest unit) amounts. Convert display amounts before sending:

import { parseRawAmount } from 'kaleido-sdk';

// User enters 0.001 BTC
const userInput = 0.001;
const rawAmount = parseRawAmount(userInput, 8);  // 100000

const quote = await client.maker.getQuote({
  from_asset: { asset_id: 'BTC', layer: 'BTC_LN', amount: rawAmount },
  to_asset: { asset_id: 'USDT', layer: 'RGB_LN' }
});

from kaleido_sdk import Layer, PairQuoteRequest, SwapLegInput, parse_raw_amount

# User enters 0.001 BTC
user_input = 0.001
raw_amount = parse_raw_amount(user_input, 8)  # 100000

quote = await client.maker.get_quote(PairQuoteRequest(
    from_asset=SwapLegInput(asset_id="BTC", layer=Layer.BTC_LN, amount=raw_amount),
    to_asset=SwapLegInput(asset_id="USDT", layer=Layer.RGB_LN)
))

Use PrecisionHandler for Multi-Asset Apps

When working with multiple assets, use PrecisionHandler to avoid precision errors:

import { createPrecisionHandler } from 'kaleido-sdk';

const handler = createPrecisionHandler(mappedAssets);

// Convert safely using asset ID
const raw = handler.toRawAmount(userInput, assetId);
const display = handler.toDisplayAmount(rawFromApi, assetId);

from kaleido_sdk import create_precision_handler

handler = create_precision_handler(mapped_assets)
raw = handler.to_raw_amount(user_input, asset_id)
display = handler.to_display_amount(raw_from_api, asset_id)

Node Operations

Check Node Before Using RLN

Always verify the node is configured:

if (!client.hasNode()) {
  throw new Error('Node URL required for this operation');
}

const balance = await client.rln.getBtcBalance();

if not client.has_node():
    raise RuntimeError("Node URL required for this operation")

balance = await client.rln.get_btc_balance()

WebSocket

Unsubscribe When Done

Always clean up WebSocket subscriptions:

const unsubscribe = await client.maker.streamQuotesByTicker(
  'BTC', 'USDT', 100000, onQuote
);

// Clean up when component unmounts or user navigates away
unsubscribe();

unsubscribe = await client.maker.stream_quotes_by_ticker(
    "BTC", "USDT", 100000, on_quote
)

# Clean up when done
unsubscribe()

Handle Reconnection

The WSClient reconnects on its own with exponential backoff, so the work on your side is surfacing state to the user: show a “reconnecting” indicator on disconnected, re-request quotes on connected, and treat maxReconnectExceeded as a hard error rather than a transient blip. For the event list and the reconnection configuration, see WebSocket.

Security

Never Expose API Keys in Client Code

API keys should only be used server-side. For browser applications, proxy API calls through your backend.

Validate User Input

Always validate amounts and addresses before sending to the API:

// Validate amount is within the layer's trading limits
const pairs = await client.maker.listPairs();
const pair = pairs.pairs.find(p =>
  p.base.ticker === 'BTC' && p.quote.ticker === 'USDT'
);

const limits = pair?.base.endpoints?.find(e => e.layer === 'BTC_LN');
if (limits && (amount < limits.min_amount || amount > limits.max_amount)) {
  throw new Error(`Amount must be between ${limits.min_amount} and ${limits.max_amount}`);
}

pairs = await client.maker.list_pairs()
pair = next(
    (p for p in pairs.pairs
     if p.base.ticker == "BTC" and p.quote.ticker == "USDT"),
    None
)

limits = next(
    (e for e in (pair.base.endpoints or []) if e.layer == "BTC_LN"),
    None,
) if pair else None

if limits and not (limits.min_amount <= amount <= limits.max_amount):
    raise ValueError(
        f"Amount must be between {limits.min_amount} and {limits.max_amount}"
    )

Order-size limits live on each asset’s endpoints list (TradingLimits per layer); pair.routes only tells you which from_layer -> to_layer combinations exist.

Performance

Cache Static Data

Assets and trading pairs change infrequently. Cache them to reduce API calls:

import type { TradingPairsResponse } from 'kaleido-sdk';

let cachedPairs: TradingPairsResponse | null = null;
let cacheTime = 0;

async function getPairs() {
  const now = Date.now();
  if (!cachedPairs || now - cacheTime > 60000) {  // 60 second cache
    cachedPairs = await client.maker.listPairs();
    cacheTime = now;
  }
  return cachedPairs;
}

import time

_cached_pairs = None
_cache_time = 0

async def get_pairs():
    global _cached_pairs, _cache_time
    now = time.time()
    if _cached_pairs is None or now - _cache_time > 60:
        _cached_pairs = await client.maker.list_pairs()
        _cache_time = now
    return _cached_pairs

Introduction

Version & Compatibility

Core Reference

Guides

Reference

Client Initialization

Use Environment Variables

Use a Singleton Client

Error Handling

Always Handle Errors

Check Retryability

Async Patterns

TypeScript: Parallel Requests

Python: Sequential with Error Recovery

Amount Handling

Always Use Raw Units for API Calls

Use PrecisionHandler for Multi-Asset Apps

Node Operations

Check Node Before Using RLN

WebSocket

Unsubscribe When Done

Handle Reconnection

Security

Never Expose API Keys in Client Code

Validate User Input

Performance

Cache Static Data

​Client Initialization

​Use Environment Variables

​Use a Singleton Client

​Error Handling

​Always Handle Errors

​Check Retryability

​Async Patterns

​TypeScript: Parallel Requests

​Python: Sequential with Error Recovery

​Amount Handling

​Always Use Raw Units for API Calls

​Use PrecisionHandler for Multi-Asset Apps

​Node Operations

​Check Node Before Using RLN

​WebSocket

​Unsubscribe When Done

​Handle Reconnection

​Security

​Never Expose API Keys in Client Code

​Validate User Input

​Performance

​Cache Static Data

Client Initialization

Use Environment Variables

Use a Singleton Client

Error Handling

Always Handle Errors

Check Retryability

Async Patterns

TypeScript: Parallel Requests

Python: Sequential with Error Recovery

Amount Handling

Always Use Raw Units for API Calls

Use PrecisionHandler for Multi-Asset Apps

Node Operations

Check Node Before Using RLN

WebSocket

Unsubscribe When Done

Handle Reconnection

Security

Never Expose API Keys in Client Code

Validate User Input

Performance

Cache Static Data