Swap APIs - KaleidoSwap Documentation

Overview

The Swap APIs implement the atomic swap protocol used by the KaleidoSwap Desktop App. Swaps execute via Hash Time-Locked Contracts (HTLCs) on the Lightning Network — both sides lock assets simultaneously, so either the full exchange completes or funds are returned. There is no counterparty risk. To use these endpoints you need:

A running RGB Lightning Node (RLN) to whitelist and route the HTLC.
A WebSocket connection to the maker (or the REST /market/quote endpoint) for live quotes and rfq_id generation.

See the Market APIs for quotes and asset data, and the Swap Protocol for a full walkthrough of the atomic swap flow. Base URL: https://api.signet.kaleidoswap.com/api/v1 (Signet)

Get Node Information

Endpoint

GET /api/v1/swaps/nodeinfo

Description

Retrieve the public identity of the maker’s RGB Lightning Node — its pubkey, the network it runs on, and the current block height. This endpoint is safe to poll.

Response Structure

pubkey: The public key of the maker node.
network: The Bitcoin network the node runs on (e.g., Signet, Regtest, Mainnet).
block_height: Current blockchain height the node is synced to.

Example Response

{
  "pubkey": "034eedc97802d7e2766704bd06d6bfded8aa2d35a1a007e277fd7278f3dc962706",
  "network": "Signet",
  "block_height": 805434
}

Real-time Quotes over WebSocket

WebSocket Endpoint

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)

Description

Establish a WebSocket connection to request live quotes from the maker. The protocol is request/response: the client sends a message and the server replies to that message. There is no subscription mechanism — to keep a price fresh, send a new quote_request whenever you need an updated quote.

Connection

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

Message Format

Only two actions are supported:

ping — heartbeat; the server replies with a pong.
quote_request — request a quote for a swap between two assets.

To request a quote, send a JSON message with the following format:

{
  "action": "quote_request",
  "from_asset": "BTC",
  "to_asset": "rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB",
  "from_amount": 1500000
}

from_asset / to_asset (required): Asset identifiers — a ticker like BTC or an RGB contract ID.
from_amount / to_amount: Amount in the asset’s raw smallest unit. Provide exactly one of the two — from_amount for a forward quote, to_amount for a reverse quote.
from_layer / to_layer (optional): Explicit settlement layers (e.g., BTC_LN, RGB_LN). If omitted, the pair’s default route is used.

Response Format

The server replies to each quote_request with a quote_response message carrying the full quote (the same shape as the REST POST /api/v1/market/quote response) in data:

{
  "action": "quote_response",
  "data": {
    "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
  }
}

Field Descriptions

rfq_id: The request_for_quotation_id, a unique identifier generated by the maker for this quote. This ID is crucial for initiating swaps and must be passed to the init endpoint before expires_at.
from_asset / to_asset: Complete leg specifications with asset_id, name, ticker, layer, amount (smallest unit), and precision.
price: Price of 1 whole unit of from_asset expressed in the smallest unit of to_asset.
fee: Fee breakdown — base_fee, variable_fee, fee_rate, final_fee, plus the asset (fee_asset) and precision (fee_asset_precision) the fee is denominated in.
timestamp: When the quote was generated (unix time).
expires_at: When the rfq_id expires (unix time).

Additional Notes:

Failed requests (unknown pair, unsupported route, invalid amounts) return a message with an error field instead of a quote_response.
The WebSocket connection remains open until the client disconnects or a network error occurs; send periodic ping messages to keep it healthy.

Initiate Swap

Endpoint

POST /api/v1/swaps/init

Description

Initiate a swap based on a fresh quote. This endpoint locks the price and prepares the swap for execution.

Request Body

Field	Type	Description
`rfq_id`	String	The quote ID from a WebSocket `quote_response` message or the REST `POST /api/v1/market/quote` endpoint.
`from_asset`	String	The RGB asset ID to swap from.
`from_amount`	Integer	The amount of the asset to swap from.*
`to_asset`	String	The RGB asset ID to swap to.
`to_amount`	Integer	The amount of the asset to swap to.*

*If the asset is BTC, the amount should be specified in millisatoshis (msat). For other assets, the amount should be provided in the asset’s native unit without considering precision.

Example Request

{
  "rfq_id": "8e6635fb-ab37-4aed-89f4-bc9c98fb8b49",
  "from_asset": "btc", 
  "from_amount": 1000000, 
  "to_asset": "rgb:2V2f58W-Tabtk3J4j-qGVQQwPWt-ksbujLNxx-x1BMTNBEf-KVsg2j3",
  "to_amount": 587770
}

Response Structure

swapstring: A string representation of the swap to be executed.
payment_hash: The payment hash associated with the swap.
access_token: Per-swap token required to poll /swaps/atomic/status. It is returned only once here at initiation — store it alongside the payment hash.

Example Response

{
  "swapstring": "1000000/btc/587770/rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB/be35403fcd85722cb0373db0527a452ce9c2eb23d3ec489af8e33ffb57d5271e",
  "payment_hash": "be35403fcd85722cb0373db0527a452ce9c2eb23d3ec489af8e33ffb57d5271e",
  "access_token": "ord_live_3rCkP9dG7mN4"
}

Additional Notes

The precision for an RGB asset can be obtained using the /assets API on the maker’s node. If the client has the same asset, the precision can also be retrieved via the node API.
The swapstring returned by this endpoint needs to be whitelisted using the /taker API of the RGB Lightning Node (RLN) of the client before executing the swap.
In this example, the user is selling 1,000 sats for 0.5877 USDT (using the RGB asset rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB).

Execute Swap

Endpoint

POST /api/v1/swaps/execute

Description

Execute the swap after it has been initiated and validated.

Request Body

Field	Type	Description
`swapstring`	String	The swap string generated by `init` endpoint.
`taker_pubkey`	String	The public key of the taker.
`payment_hash`	String	The payment hash associated with the swap.

Example Request

{
  "swapstring": "1000000/btc/587770/rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB/be35403fcd85722cb0373db0527a452ce9c2eb23d3ec489af8e33ffb57d5271e",
  "taker_pubkey": "03e7156ae33b0a208d0744199163177e909e80176e55d97a2f221ede0f934dd9ad",
  "payment_hash": "be35403fcd85722cb0373db0527a452ce9c2eb23d3ec489af8e33ffb57d5271e"
}

Response Structure

status: Status code of the swap execution.
message: Additional details about the execution.

Example Response

{
  "status": 200,
  "message": "Swap executed successfully"
}

Get Swap Status

Endpoint

POST /api/v1/swaps/atomic/status

Description

Retrieve the current status of an atomic swap using the associated payment_hash and the per-swap access_token returned by /swaps/init.

Request Body

Field	Type	Description
`payment_hash`	String	The payment hash of the swap whose status to retrieve.
`access_token`	String	The per-swap access token returned by `/swaps/init`.

Example Request

{
  "payment_hash": "7c2c95b9c2aa0a7d140495b664de7973b76561de833f0dd84def3efa08941664",
  "access_token": "ord_live_3rCkP9dG7mN4"
}

Response

swap: An object containing detailed information about the swap.

Example Response

{
  "swap": {
    "qty_from": 1000000,
    "qty_to": 587770,
    "from_asset": "btc",
    "to_asset": "rgb:2V2f58W-Tabtk3J4j-qGVQQwPWt-ksbujLNxx-x1BMTNBEf-KVsg2j3",
    "payment_hash": "7c2c95b9c2aa0a7d140495b664de7973b76561de833f0dd84def3efa08941664",
    "status": "Pending",
    "requested_at": 1691160765,
    "initiated_at": 1691168512,
    "expires_at": 1691172703,
    "completed_at": 1691171075
  }
}

Swap Object Schema

qty_from (integer): The quantity of the asset being swapped from. Example: 30
qty_to (integer): The quantity of the asset being swapped to. Example: 10
from_asset (string): The RGB asset ID being swapped from. Example: rgb:2dkSTbr-jFhznbPmo-TQafzswCN-av4gTsJjX-ttx6CNou5-M98k8Zd
to_asset (string): The RGB asset ID being swapped to. Example: rgb:2eVw8uw-8G88LQ2tQ-kexM12SoD-nCX8DmQrw-yLMu6JDfK-xx1SCfc
payment_hash (string): The unique payment hash associated with the swap. Example: 7c2c95b9c2aa0a7d140495b664de7973b76561de833f0dd84def3efa08941664
status (SwapStatus): The current status of the swap. Possible values:
- Waiting
- Pending
- Succeeded
- Expired
- Failed
requested_at (integer): Unix timestamp when the swap was requested. Example: 1691160765
initiated_at (integer): Unix timestamp when the swap was initiated. Example: 1691168512
expires_at (integer): Unix timestamp when the swap expires. Example: 1691172703
completed_at (integer): Unix timestamp when the swap was completed. Example: 1691171075

Additional Notes

The status field provides real-time updates on the swap’s progress.
Ensure that the payment_hash provided is accurate to retrieve the correct swap status.
A missing or invalid access_token returns a uniform 404 Swap not found, so the endpoint cannot be used to probe for existing payment hashes.
Time-related fields are in Unix timestamp format.
The SwapStatus field in the Swap object can have one of the following values:
- Waiting: The swap is awaiting initiation.
- Pending: The swap has been initiated and is currently in progress.
- Succeeded: The swap has been successfully completed.
- Expired: The swap was not completed within the required timeframe.
- Failed: The swap encountered an error and did not complete successfully.

For error details, refer to Error Handling.

​Overview

​Get Node Information

​Endpoint

​Description

​Response Structure

​Example Response

​Real-time Quotes over WebSocket

​WebSocket Endpoint

​Description

​Connection

​Message Format

​Response Format

​Field Descriptions

​Additional Notes:

​Initiate Swap

​Endpoint

​Description

​Request Body

​Example Request

​Response Structure

​Example Response

​Additional Notes

​Execute Swap

​Endpoint

​Description

​Request Body

​Example Request

​Response Structure

​Example Response

​Get Swap Status

​Endpoint

​Description

​Request Body

​Example Request

​Response

​Example Response

​Swap Object Schema

​Additional Notes

Overview

Get Node Information

Endpoint

Description

Response Structure

Example Response

Real-time Quotes over WebSocket

WebSocket Endpoint

Description

Connection

Message Format

Response Format

Field Descriptions

Additional Notes:

Initiate Swap

Endpoint

Description

Request Body

Example Request

Response Structure

Example Response

Additional Notes

Execute Swap

Endpoint

Description

Request Body

Example Request

Response Structure

Example Response

Get Swap Status

Endpoint

Description

Request Body

Example Request

Response

Example Response

Swap Object Schema

Additional Notes