Overview

The RGB Lightning DEX API allows interaction with an RGB Lightning Service Provider (RGB-LSP) that provides liquidity on request and enables swap functionalities. The swap protocol operates on a taker-maker model, where clients request live quotes for trading pairs and initiate swaps against them. The API also supports the RGB LSPS1 (Lightning Service Provider Specification) for managing channels and liquidity services.

Key Features

RGB LSPS1 (Lightning Service Provider Specification) Support: Liquidity services and swap functionalities.
Real-time Market Data: WebSocket request/response quote streaming (quote_request/quote_response).
Swap Protocol: Taker-maker model for initiating and executing swaps.
Asset and Trading Pair Management: Comprehensive API for fetching supported assets and pairs.

Proceed to Getting Started to begin.

Two Sub-APIs

The KaleidoSwap API is split into two distinct services:

Sub-API	Base Path	Purpose
Maker API	`/api/v1/`	Market data, quotes, swap orders, and LSPS1 channel operations
RLN API	node root (e.g. `http://<node>:3001/`)	RGB Lightning Node operations — wallet, channels, and payments

The Maker API is publicly accessible and handles all trading and liquidity operations. The RLN API is the REST API served directly at the root of your own RGB Lightning Node (e.g. http://<node>:3001/nodeinfo) and requires a running node instance.

Which API do I need?

Goal	API	Endpoint group
Get available assets or trading pairs	Maker API	Market APIs
Get a price quote for a swap	Maker API	Market APIs
Initiate or track an atomic swap	Maker API	Swap APIs
Order a Lightning channel from an LSP	Maker API	RGB LSPS1 APIs
Request live quotes over WebSocket	Maker API (WebSocket)	Swap Protocol
Check wallet balance or node info	RLN API	Requires your own node
Send/receive BTC or RGB assets	RLN API	Requires your own node
Open or close Lightning channels	RLN API	Requires your own node

The interactive API playground below runs against the Signet environment (https://api.signet.kaleidoswap.com). Use it for exploration and testing. For production, use the mainnet URL once available.

Authentication

Current state: Anonymous access works for all Maker API endpoints. Bearer API keys (Authorization: Bearer <token>) are already accepted and attributed today — keys carry scopes such as quote:read (market data and quotes) and swap:execute (swap init/execute) — but enforcement is rolling out gradually, so requests without a key are still served. The API playground is pre-configured with bearer auth. Rolling out: Once enforcement is enabled, requests with a missing or invalid key will receive 401 responses. Integrations should start sending an API key now to be ready.

Base Response Format

All API responses follow a consistent JSON structure. Successful responses return the requested data directly as a JSON object or array. Errors use one of three envelopes. Application errors (invalid parameters, missing resources, conflicts, rate limits, server errors) return a structured envelope:

{
  "error_code": "PAIR_NOT_FOUND",
  "message": "Trading pair not found: BTC/USDT",
  "details": {},
  "request_id": "req_01HV8Q9X7G0Q7Y3Z"
}

Request-validation errors (schema validation failures, HTTP 422) return FastAPI’s validation envelope:

{
  "detail": [
    {
      "loc": ["body", "rfq_id"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Legacy errors: a few endpoints still return some 400 responses as a bare detail object, without error_code or request_id — for example an unsupported route on /market/quote or a malformed pair_ticker filter on /market/pairs:

{
  "detail": "Route not supported for this pair. From: BTC_LN, To: RGB_LN"
}

HTTP status codes follow standard conventions:

Status	Meaning
`200`	Success
`400`	Bad request — invalid parameters
`401`	Unauthorized — missing or invalid API key (once enforcement is enabled)
`403`	Forbidden — key not allowed from this origin
`404`	Resource not found
`422`	Unprocessable entity — validation error
`429`	Too many requests — rate limit exceeded
`500`	Internal server error
`503`	Service unavailable — maker or LSP node temporarily unreachable

See Error Handling for a complete list of error codes.

Rate Limits

Rate limits apply to all API endpoints. Requests that exceed the limit receive a 429 Too Many Requests response. Specific limits vary by endpoint and environment. When building integrations, implement exponential backoff for retries and cache static data (assets, pairs) locally where possible.

Using the SDK

Instead of calling the REST API directly, you can use the official KaleidoSDK libraries that wrap these endpoints with type safety and convenience methods:

TypeScript SDK

Auto-generated typed client from the OpenAPI spec with client.maker.* and client.rln.* sub-clients

Python SDK

Synchronous Python client with Pydantic models, using the same sub-client architecture

Introduction

Guides

Endpoints

Key Features

Two Sub-APIs

Which API do I need?

Authentication

Base Response Format

Rate Limits

Using the SDK

TypeScript SDK

Python SDK

​Key Features

​Two Sub-APIs

​Which API do I need?

​Authentication

​Base Response Format

​Rate Limits

​Using the SDK

TypeScript SDK

Python SDK

Key Features

Two Sub-APIs

Which API do I need?

Authentication

Base Response Format

Rate Limits

Using the SDK