Installation
npm install kaleidoswap-sdk
Requirements
- Node.js 18 or higher
- TypeScript 5.0+ (recommended)
- Python 3.10 or higher
- Dependencies installed automatically:
httpx, websockets, pydantic
Configuration
Basic Setup
import { KaleidoClient } from 'kaleidoswap-sdk';
const client = KaleidoClient.create({
baseUrl: 'https://api.regtest.kaleidoswap.com',
});
// Make your first API call
const assets = await client.maker.listAssets();
console.log(`Found ${assets.assets.length} assets`);
KaleidoClient.create() is synchronous in both languages. No await is needed for client creation.
Full Configuration
import { KaleidoClient, KaleidoConfig } from 'kaleidoswap-sdk';
const config: KaleidoConfig = {
// Required: API base URL
baseUrl: 'https://api.regtest.kaleidoswap.com',
// Optional: Your RGB Lightning Node URL
nodeUrl: 'http://localhost:3001',
// Optional: API key for authenticated requests
apiKey: undefined,
// Optional: Request timeout in seconds (default: 30)
timeout: 30,
// Optional: Maximum retries (default: 3)
maxRetries: 3,
// Optional: Cache TTL in seconds (default: 60)
cacheTtl: 60,
};
const client = KaleidoClient.create(config);
Environment Variables
You can configure the SDK using environment variables:
export KALEIDO_API_URL=https://api.regtest.kaleidoswap.com
export KALEIDO_NODE_URL=http://localhost:3001
export KALEIDO_API_KEY=your_api_key_here
import { KaleidoClient } from 'kaleidoswap-sdk';
const client = KaleidoClient.create({
baseUrl: process.env.KALEIDO_API_URL || 'https://api.regtest.kaleidoswap.com',
nodeUrl: process.env.KALEIDO_NODE_URL,
apiKey: process.env.KALEIDO_API_KEY,
});
Available Environments
| Environment | API URL | Description |
|---|
| Regtest | https://api.regtest.kaleidoswap.com | Local development and testing |
| Signet | https://api.signet.kaleidoswap.com | Bitcoin Signet testnet |
| Mainnet | https://api.kaleidoswap.com | Production environment |
Sub-Client Architecture
The SDK organizes API operations into two sub-clients:
// Maker operations (market, orders, swaps, LSPS1)
const assets = await client.maker.listAssets();
const pairs = await client.maker.listPairs();
const quote = await client.maker.getQuote({ /* ... */ });
const order = await client.maker.createSwapOrder({ /* ... */ });
const status = await client.maker.getSwapOrderStatus({ order_id: 'order-123' });
const history = await client.maker.getOrderHistory();
const lspInfo = await client.maker.getLspInfo();
// RLN operations (wallet, channels, payments -- requires nodeUrl)
if (client.hasNode()) {
const nodeInfo = await client.rln.getNodeInfo();
const balance = await client.rln.getBtcBalance();
const channels = await client.rln.listChannels();
const invoice = await client.rln.createLNInvoice({ /* ... */ });
}
Checking Node Configuration
Before executing node operations, verify that your node is configured:
if (client.hasNode()) {
console.log('Node configured - can access RLN operations');
const nodeInfo = await client.rln.getNodeInfo();
console.log(`Node pubkey: ${nodeInfo.pubkey}`);
} else {
console.log('Node not configured - limited to maker operations');
}
Basic Error Handling
import {
KaleidoClient,
KaleidoError,
NetworkError,
ValidationError,
APIError,
} from 'kaleidoswap-sdk';
try {
const pairs = await client.maker.listPairs();
console.log(`Found ${pairs.pairs.length} pairs`);
} catch (error) {
if (error instanceof NetworkError) {
console.log(`Network error: ${error.message}`);
} else if (error instanceof ValidationError) {
console.log(`Validation error: ${error.message}`);
} else if (error instanceof APIError) {
console.log(`API error (${error.statusCode}): ${error.message}`);
} else if (error instanceof KaleidoError) {
console.log(`SDK error: ${error.message}`);
}
}
Next Steps
