Bitcoin Swap API: Getting Started

Welcome to the KaleidoSwap API! This guide will help you set up and start using the API quickly and effectively.

Base URL

The KaleidoSwap API is accessible via HTTPS for secure communication. Here are the available environments:

Signet (MutinyNet)

A public testnet with realistic network conditions, recommended for integration testing before mainnet. This environment is currently live. All API requests in this environment should be directed to the following base URL:

Base URL: https://api.signet.kaleidoswap.com/api/v1

Bitcoin Mainnet (Coming Soon)

The mainnet environment is the production-ready endpoint for live transactions. Stay tuned for updates about its release.

Base URL: https://api.kaleidoswap.com/api/v1

Authentication

Current State

Anonymous requests are still served, so you can start testing and integrating with the API immediately. Bearer API keys (Authorization: Bearer <token>) are already accepted and attributed today.

Enforcement Rollout

API-key enforcement is being rolled out gradually. Once enabled, requests without a valid key will receive 401 responses — integrations should start sending an API key now. See the Overview for details.

Request Format

HTTP Methods

The API uses the following HTTP methods:

GET: Retrieve data.
POST: Submit data or perform an action.

Real-time quote streaming uses a WebSocket endpoint — see the Swap Protocol.

Headers

Ensure that your POST HTTP requests include the following headers:

Content-Type: application/json (for requests with JSON payloads)

Example Request

Here’s a sample POST request to the testnet environment:

curl -X 'POST' \
  'https://api.signet.kaleidoswap.com/api/v1/market/quote' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "from_asset": {
    "asset_id": "BTC",
    "layer": "BTC_LN",
    "amount": 1500000
  },
  "to_asset": {
    "asset_id": "rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB",
    "layer": "RGB_LN"
  }
}'

Each leg specifies an `asset_id`, a settlement `layer` (e.g. `BTC_LN`, `RGB_LN`, `BTC_L1`, `RGB_L1`), and optionally an `amount` in the asset’s smallest unit — exactly one of the two legs must carry the amount.

Response Format

All responses from the KaleidoSwap API are in JSON format for ease of parsing. A typical response includes:

A response value structured according to the corresponding schema.
detail: Details about any errors encountered.

Example Response

{
  "rfq_id": "13d4777c-ae96-4858-9c7c-3ca730c5039a",
  "from_asset": {
    "asset_id": "BTC",
    "name": "Bitcoin",
    "ticker": "BTC",
    "layer": "BTC_LN",
    "amount": 1500000,
    "precision": 8
  },
  "to_asset": {
    "asset_id": "rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB",
    "name": "Tether USD",
    "ticker": "USDT",
    "layer": "RGB_LN",
    "amount": 875000,
    "precision": 6
  },
  "price": 59507000000,
  "fee": {
    "base_fee": 1000,
    "variable_fee": 250,
    "fee_rate": 0.0001,
    "final_fee": 1250,
    "fee_asset": "BTC",
    "fee_asset_precision": 8
  },
  "timestamp": 1715896356,
  "expires_at": 1715896416
}

API Versioning

KaleidoSwap uses versioning to ensure backward compatibility. The current API version is: Version: v1 The version number is reflected in the base URL, as in https://api.signet.kaleidoswap.com/api/v1.

Rate Limiting

To ensure a fair usage policy, the API enforces rate limits. The defaults are:

Per IP: 600 requests per minute
Per endpoint: 300 requests per minute
Global: 1000 requests per minute

These limits are configurable per deployment, so they may vary between environments. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers; requests over the limit receive a 429 Too Many Requests response.

Errors and Debugging

The API returns standard HTTP status codes to indicate the outcome of a request:

200: Success
400: Bad Request (e.g., invalid parameters)
404: Resource Not Found
500: Internal Server Error For more information on error handling, see Error Handling.

Next Steps

Swap Protocol

Understand the full taker-maker swap lifecycle before calling swap endpoints

Market APIs

Fetch assets, pairs, and quotes

Swap APIs

Create and track swap orders

RGB LSPS1 APIs

Order channels and manage liquidity

Introduction

Guides

Endpoints

Base URL

Signet (MutinyNet)

Bitcoin Mainnet (Coming Soon)

Authentication

Current State

Enforcement Rollout

Request Format

HTTP Methods

Headers

Example Request

Each leg specifies an `asset_id`, a settlement `layer` (e.g. `BTC_LN`, `RGB_LN`, `BTC_L1`, `RGB_L1`), and optionally an `amount` in the asset’s smallest unit — exactly one of the two legs must carry the amount.

Response Format

Example Response

API Versioning

Rate Limiting

Errors and Debugging

Next Steps

Swap Protocol

Market APIs

Swap APIs

RGB LSPS1 APIs

​Base URL

​Signet (MutinyNet)

​Bitcoin Mainnet (Coming Soon)

​Authentication

​Current State

​Enforcement Rollout

​Request Format

​HTTP Methods

​Headers

​Example Request

​Each leg specifies an asset_id, a settlement layer (e.g. BTC_LN, RGB_LN, BTC_L1, RGB_L1), and optionally an amount in the asset’s smallest unit — exactly one of the two legs must carry the amount.

​Response Format

​Example Response

​API Versioning

​Rate Limiting

​Errors and Debugging

​Next Steps

Swap Protocol

Market APIs

Swap APIs

RGB LSPS1 APIs

Base URL

Signet (MutinyNet)

Bitcoin Mainnet (Coming Soon)

Authentication

Current State

Enforcement Rollout

Request Format

HTTP Methods

Headers

Example Request

Each leg specifies an `asset_id`, a settlement `layer` (e.g. `BTC_LN`, `RGB_LN`, `BTC_L1`, `RGB_L1`), and optionally an `amount` in the asset’s smallest unit — exactly one of the two legs must carry the amount.

Response Format

Example Response

API Versioning

Rate Limiting

Errors and Debugging

Next Steps