Atomic Swap Protocol

KaleidoSwap executes swaps atomically using the client’s RGB Lightning Node:

Model	Used by	Trust required	Settlement
Atomic swap	Desktop App, SDK, node integrations	None — cryptographic guarantee	HTLC on Lightning Network

Atomic Swaps

The Desktop App uses Hash Time-Locked Contracts (HTLCs) to execute swaps atomically over the Lightning Network. Both sides lock their assets simultaneously — either the full swap completes or both sides get their funds back. There is no counterparty risk. This is the same mechanism behind the first ever RGB asset swap on Lightning mainnet.

How It Works

The taker requests live quotes from the maker over WebSocket (each quote_response carries an rfq_id).
The taker calls POST /api/v1/swaps/init — the maker locks the exchange rate and returns a swapstring, a payment_hash, and an access_token. The access_token is returned only once — store it alongside the payment hash, as it is required to poll the swap status later.
The taker’s RGB Lightning Node whitelists the swapstring (authorising it to route through the node).
The taker calls POST /api/v1/swaps/execute — the maker initiates the HTLC.
The Lightning Network routes the HTLC: the maker reveals the preimage to claim BTC, which simultaneously releases the RGB asset to the taker.
If either party fails to complete within the HTLC timeout, both sides’ funds are returned automatically.
The taker polls POST /api/v1/swaps/atomic/status with the payment_hash and the access_token from step 2. A missing or invalid token yields a uniform 404 Swap not found.

Sequence Diagram

Taker Client                         Maker (RGB-LSP)                   Taker RLN Node
     |                                      |                                 |
     |──── WebSocket connect ──────────────>|                                 |
     |──── quote_request (BTC/USDT) ───────>|                                 |
     |<─── quote_response (price, rfq_id) ──|                                 |
     |                                      |                                 |
     |──── POST /api/v1/swaps/init ────────>|                                 |
     |       (rfq_id, from, to, amounts)    |                                 |
     |<─── { swapstring, payment_hash,      |                                 |
     |       access_token } ─────────────── |                                 |
     |                                      |                                 |
     |──── whitelist_swap(swapstring) ──────────────────────────────────────>|
     |<─── swap whitelisted ───────────────────────────────────────────────  |
     |                                      |                                 |
     |──── POST /api/v1/swaps/execute ─────>|                                 |
     |       (swapstring, taker_pubkey,     |                                 |
     |        payment_hash)                 |                                 |
     |<─── 200 OK ──────────────────────── |                                 |
     |          ← HTLC resolves atomically on Lightning Network →             |
     |                                      |                                 |
     |── POST /api/v1/swaps/atomic/status ─>|                                 |
     |       (payment_hash, access_token)   |                                 |
     |<─── { status: "Succeeded" } ─────── |                                 |

Endpoints Used

Step	Endpoint
Request quotes	WebSocket `wss://api.signet.kaleidoswap.com/api/v1/market/ws/{client_id}`
Lock rate	`POST /api/v1/swaps/init`
Execute swap	`POST /api/v1/swaps/execute`
Check status	`POST /api/v1/swaps/atomic/status` (requires `access_token` from init)

WebSocket Environments

Environment	URL
Signet	`wss://api.signet.kaleidoswap.com/api/v1/market/ws/{client_id}`
Mainnet	`wss://api.kaleidoswap.com/api/v1/market/ws/{client_id}` (coming soon)

Replace {client_id} with a unique identifier for your session.

SDK Integration

The SDK handles the WebSocket, init, and execute steps for you:

import { KaleidoClient } from 'kaleido-sdk';

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

// Stream a live quote
client.maker.enableWebSocket('wss://api.signet.kaleidoswap.com/api/v1/market/ws/my-client');

const unsubscribe = await client.maker.streamQuotesByTicker(
  'BTC', 'USDT', 100000,
  async (quote) => {
    // Use the rfq_id from the latest quote to init + execute
    const result = await client.maker.initSwap({
      rfq_id: quote.rfq_id,
      from_asset: 'BTC',
      from_amount: quote.from_amount,
      to_asset: 'USDT',
      to_amount: quote.to_amount,
    });
    // Whitelist on your node, then execute...
  }
);

from kaleido_sdk import KaleidoClient

client = KaleidoClient.create(
    base_url="https://api.signet.kaleidoswap.com",
    node_url="http://localhost:3001",  # required for atomic swaps
)

# Stream a live quote and initiate a swap
client.maker.enable_websocket("wss://api.signet.kaleidoswap.com/api/v1/market/ws/my-client")
# See sdk/examples for full atomic swap flow

Swap APIs

Endpoints for atomic swap init and execute

Market APIs

Endpoints for quotes and market data

SDK Examples

End-to-end code examples for the atomic swap flow

Error Handling

Handle swap failures and edge cases

Introduction

Guides

Endpoints

Atomic Swaps

How It Works

Sequence Diagram

Endpoints Used

WebSocket Environments

SDK Integration

Swap APIs

Market APIs

SDK Examples

Error Handling

​Atomic Swaps

​How It Works

​Sequence Diagram

​Endpoints Used

​WebSocket Environments

​SDK Integration

Swap APIs

Market APIs

SDK Examples

Error Handling

Atomic Swaps

How It Works

Sequence Diagram

Endpoints Used

WebSocket Environments

SDK Integration