Skip to main content

​
Installation Issues

Symptoms: npm install kaleidoswap-sdk fails with errorsSolutions:
  1. Ensure Node.js 18+ is installed: node --version
  2. Clear npm cache: npm cache clean --force
  3. Delete node_modules and package-lock.json, then reinstall
  4. Try with a different package manager: pnpm add kaleidoswap-sdk
Symptoms: pip install kaleidoswap-sdk failsSolutions:
  1. Ensure Python 3.10+ is installed: python --version
  2. Use a virtual environment: python -m venv .venv && source .venv/bin/activate
  3. Upgrade pip: pip install --upgrade pip
  4. Try: pip install kaleidoswap-sdk --no-cache-dir
Symptoms: Cannot find module 'kaleidoswap-sdk' or ModuleNotFoundErrorSolutions:
  • TypeScript: Check your tsconfig.json has "moduleResolution": "node" or "bundler"
  • Python: Verify you are in the correct virtual environment
  • Verify the package is installed: npm list kaleidoswap-sdk or pip show kaleidoswap-sdk

​
Runtime Errors

Symptoms: NetworkError when making API callsCauses:
  • API server unreachable
  • Incorrect baseUrl
  • Firewall blocking requests
Solutions:
  1. Verify the baseUrl is correct and accessible
  2. Check internet connectivity
  3. Try accessing the API URL in a browser: https://api.regtest.kaleidoswap.com/api/v1/market/assets
  4. If behind a firewall, ensure outbound HTTPS is allowed
Symptoms: NodeNotConfiguredError when calling client.rln.* methodsCause: No nodeUrl / node_url was provided when creating the client.Solution:
const client = KaleidoClient.create({
  baseUrl: 'https://api.regtest.kaleidoswap.com',
  nodeUrl: 'http://localhost:3001',  // Add this
});
Always check client.hasNode() / client.has_node() before calling RLN methods.
Symptoms: QuoteExpiredError when creating a swap orderCause: The quote’s expires_at time has passed.Solutions:
  1. Get a fresh quote immediately before creating the order
  2. Use WebSocket streaming for always-current quotes
  3. Reduce the time between getting a quote and creating the order
Symptoms: ValidationError with amount-related messageCauses:
  • Amount below minimum or above maximum
  • Wrong precision (sending display units instead of raw)
  • Negative or zero amount
Solutions:
  1. Check min/max limits from listPairs response
  2. Ensure you are sending raw amounts (use toSmallestUnits / to_smallest_units)
  3. Validate amounts before sending
import { toSmallestUnits } from 'kaleidoswap-sdk';

// Convert 0.001 BTC to satoshis (100000)
const amount = toSmallestUnits(0.001, 8);
Symptoms: APIError with status 401Cause: Invalid or missing API key.Solutions:
  1. Check that apiKey / api_key is set correctly
  2. Verify the key is valid and not expired
  3. Some endpoints may not require an API key — check the API Reference
Symptoms: TimeoutError on API callsCauses:
  • Slow network connection
  • Server under heavy load
  • Timeout too short
Solutions:
  1. Increase the timeout: timeout: 60 (seconds)
  2. Check network connectivity
  3. Implement retry logic using error.isRetryable()

​
WebSocket Issues

Symptoms: connected event never fires, or WebSocketErrorSolutions:
  1. Verify the WebSocket URL is correct (should start with wss://)
  2. Ensure enableWebSocket / enable_websocket was called before streaming
  3. Check that WebSocket connections are not blocked by firewall or proxy
  4. Try with a different client ID in the URL
Symptoms: quoteResponse / quote_response event never firesSolutions:
  1. Verify the asset pair is valid and has available routes
  2. Check that the amount is within min/max limits
  3. Listen for error events on the WSClient
  4. Verify the connection is established (check connected event)
Symptoms: WebSocket disconnects and reconnects frequentlySolutions:
  1. Check internet stability
  2. The WSClient auto-reconnects with exponential backoff
  3. Monitor reconnecting events to track attempts
  4. If maxReconnectExceeded fires, manually reconnect:
ws.on('maxReconnectExceeded', async () => {
  console.log('Reconnecting manually...');
  await ws.connect();
});

​
TypeScript-Specific Issues

Symptoms: TypeScript compiler errors about incompatible typesSolutions:
  1. Ensure you are importing types from kaleidoswap-sdk: 
    import type { Asset, TradingPair } from 'kaleidoswap-sdk';
  2. Check your TypeScript version is 5.0+
  3. If using strict mode, you may need to handle undefined explicitly
Symptoms: ERR_REQUIRE_ESM or import syntax errorsSolutions:
  1. The SDK is ESM-only. Ensure your project uses ESM:
    • "type": "module" in package.json
    • Or use .mts file extension
  2. If you must use CommonJS, use dynamic import: const sdk = await import('kaleidoswap-sdk')

​
Python-Specific Issues

Symptoms: ValidationError from Pydantic when parsing API responsesSolutions:
  1. Ensure pydantic>=2.0 is installed
  2. Check that you are using the correct request format
  3. The API may have been updated — try updating the SDK: pip install --upgrade kaleidoswap-sdk
Symptoms: httpx.ConnectError or similarSolutions:
  1. Check that the API URL is reachable
  2. If using a proxy, configure it via environment variables: HTTP_PROXY, HTTPS_PROXY
  3. Increase timeout if the connection is slow

​
Debugging

​
Enable Verbose Logging

// Use Node.js debugging
// Set environment variable: NODE_DEBUG=http
// Or inspect network with browser DevTools

​
Validate Configuration

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

console.log(`Has node: ${client.hasNode()}`);

// Test connectivity
try {
  const assets = await client.maker.listAssets();
  console.log(`API connected: ${assets.assets.length} assets`);
} catch (error) {
  console.error('API connection failed:', error);
}

if (client.hasNode()) {
  try {
    const nodeInfo = await client.rln.getNodeInfo();
    console.log(`Node connected: ${nodeInfo.pubkey}`);
  } catch (error) {
    console.error('Node connection failed:', error);
  }
}

​
Getting Help

GitHub Issues

Report bugs or request features

Telegram Community

Get help from the community

Email Support

Direct support for urgent issues

API Reference

Complete method documentation
When reporting issues, include:
  1. SDK version (getVersion() / get_version())
  2. Language and runtime version (Node.js / Python)
  3. Error message and stack trace
  4. Minimal code to reproduce
  5. Environment (Regtest / Signet / Mainnet)