> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaleidoswap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Install and configure the Kaleido SDK for TypeScript or Python

## Version Compatibility

The current SDK implementation in `kaleido-sdk` (TypeScript) and `kaleido_sdk` (Python) is `v0.1.5`.

Both SDKs are generated from the same Maker API and RGB Lightning Node specs, then wrapped with handwritten clients for:

* `client.maker` for Kaleidoswap market, swap, and LSPS1 endpoints
* `client.rln` for RGB Lightning Node wallet, channel, payment, and swap endpoints

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install kaleido-sdk
  ```

  ```bash pnpm theme={null}
  pnpm add kaleido-sdk
  ```

  ```bash yarn theme={null}
  yarn add kaleido-sdk
  ```

  ```bash pip theme={null}
  pip install kaleido-sdk
  ```
</CodeGroup>

### Requirements

<Tabs>
  <Tab title="TypeScript">
    * Node.js 18 or higher
    * TypeScript 5.x recommended
  </Tab>

  <Tab title="Python">
    * Python 3.10 or higher
    * Runtime dependencies are installed automatically
  </Tab>
</Tabs>

## Basic Setup

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { KaleidoClient } from 'kaleido-sdk';

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

  const assets = await client.maker.listAssets();
  console.log(`Found ${assets.assets.length} assets`);
  ```

  ```python Python theme={null}
  from kaleido_sdk import KaleidoClient

  client = KaleidoClient.create(
      base_url="https://api.regtest.kaleidoswap.com"
  )

  assets = await client.maker.list_assets()
  print(f"Found {len(assets.assets)} assets")
  ```
</CodeGroup>

<Note>
  `KaleidoClient.create()` is synchronous in both SDKs. Do not `await` client creation.
</Note>

## Configuration

### TypeScript

`KaleidoClient.create()` accepts a `KaleidoConfig` object:

```typescript theme={null}
import { KaleidoClient, LogLevel } from 'kaleido-sdk';

const client = KaleidoClient.create({
  baseUrl: 'https://api.regtest.kaleidoswap.com',
  nodeUrl: 'http://localhost:3001',
  apiKey: process.env.KALEIDO_API_KEY,
  timeout: 30,
  logLevel: LogLevel.INFO,
});
```

Supported config fields:

* `baseUrl?`: Maker API base URL. Defaults to `https://api.regtest.kaleidoswap.com`
* `nodeUrl?`: RGB Lightning Node URL
* `apiKey?`: optional API key
* `timeout?`: request timeout in seconds
* `logLevel?`: SDK log level
* `logger?`: custom logger implementation

### Python

`KaleidoClient.create()` accepts keyword arguments:

```python theme={null}
import logging
from kaleido_sdk import KaleidoClient

client = KaleidoClient.create(
    base_url="https://api.regtest.kaleidoswap.com",
    node_url="http://localhost:3001",
    api_key=None,
    timeout=30.0,
    max_retries=3,
    cache_ttl=60,
    log_level=logging.INFO,
)
```

Python supports the same connection settings plus:

* `max_retries`: retry budget for the HTTP client
* `cache_ttl`: cache TTL in seconds
* `log_level`: standard Python logging level

## Environment Variables

The SDK does not auto-load environment variables, but these names are used by the examples and work well as a convention:

| Variable           | Typical use            |
| ------------------ | ---------------------- |
| `KALEIDO_API_URL`  | Maker API base URL     |
| `KALEIDO_NODE_URL` | RGB Lightning Node URL |
| `KALEIDO_API_KEY`  | API key                |

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { KaleidoClient } from 'kaleido-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,
  });
  ```

  ```python Python theme={null}
  import os
  from kaleido_sdk import KaleidoClient

  client = KaleidoClient.create(
      base_url=os.environ.get("KALEIDO_API_URL", "https://api.regtest.kaleidoswap.com"),
      node_url=os.environ.get("KALEIDO_NODE_URL"),
      api_key=os.environ.get("KALEIDO_API_KEY"),
  )
  ```
</CodeGroup>

## Available Environments

Common Maker API endpoints used in this repo:

| Environment      | API URL                               |
| ---------------- | ------------------------------------- |
| Regtest          | `https://api.regtest.kaleidoswap.com` |
| Signet / staging | `https://api.staging.kaleidoswap.com` |
| Signet           | `https://api.signet.kaleidoswap.com`  |

## Sub-Client Architecture

<CodeGroup>
  ```typescript TypeScript theme={null}
  const client = KaleidoClient.create({
    baseUrl: 'https://api.regtest.kaleidoswap.com',
    nodeUrl: 'http://localhost:3001',
  });

  const pairs = await client.maker.listPairs();

  if (client.hasNode()) {
    const nodeInfo = await client.rln.getNodeInfo();
    const channels = await client.rln.listChannels();
  }
  ```

  ```python Python theme={null}
  client = KaleidoClient.create(
      base_url="https://api.regtest.kaleidoswap.com",
      node_url="http://localhost:3001",
  )

  pairs = await client.maker.list_pairs()

  if client.has_node():
      node_info = await client.rln.get_node_info()
      channels = await client.rln.list_channels()
  ```
</CodeGroup>

## Node Configuration Checks

TypeScript exposes `client.hasNode()` and always returns an `rln` client instance. Python exposes `client.has_node()`, and `client.rln` raises `NodeNotConfiguredError` if `node_url` is missing.

<CodeGroup>
  ```typescript TypeScript theme={null}
  if (!client.hasNode()) {
    console.log('Node URL not configured; only maker operations are available');
  } else {
    const nodeInfo = await client.rln.getNodeInfo();
    console.log(nodeInfo.pubkey);
  }
  ```

  ```python Python theme={null}
  if not client.has_node():
      print("Node URL not configured; only maker operations are available")
  else:
      node_info = await client.rln.get_node_info()
      print(node_info.pubkey)
  ```
</CodeGroup>

## First Quote

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { KaleidoClient, Layer } from 'kaleido-sdk';

  const client = KaleidoClient.create();

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

  console.log(quote.rfq_id);
  console.log(quote.price);
  ```

  ```python Python theme={null}
  from kaleido_sdk import KaleidoClient, Layer, PairQuoteRequest, SwapLegInput

  client = KaleidoClient.create()

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

  print(quote.rfq_id)
  print(quote.price)
  ```
</CodeGroup>