Skip to main content

​
Interface Overview

KaleidoSwap Trading Interface The KaleidoSwap trading interface is designed for simplicity and efficiency. The main elements are:
  • From Card — select the asset and amount you’re swapping from
  • To Card — select the asset you want to receive
  • Recipient Address — enter the address where the swapped asset will be sent
  • Quote Display — real-time exchange rate and fees
  • Swap Button — create the order and proceed to the order page

​
Swap Cards

​
From Card (Source)

The top card represents what you’re swapping from:
ElementDescription
Asset SelectorClick to choose the source asset
Network BadgeShows the protocol layer (RGB Lightning, etc.)
Amount InputEnter how much you want to swap
USD EquivalentApproximate USD value
Min/MaxAmount limits for this pair

​
To Card (Destination)

The bottom card shows what you’ll receive:
ElementDescription
Asset SelectorClick to choose the destination asset
Network BadgeShows the protocol layer
Amount DisplayCalculated output amount (read-only)
USD EquivalentApproximate USD value

​
Recipient Address

Below the To card, enter the address where you want to receive the swapped asset. The format depends on the destination layer:
Destination LayerAddress FormatExample
LightningBOLT11 invoicelnbc1...
Bitcoin on-chainBitcoin addressbc1q...
RGBRGB invoicergb:...
Make sure the recipient address matches the destination asset and layer. An incorrect address may result in lost funds.

​
Creating a Swap Order

1

Select Source Asset

Click the asset selector on the From card and choose the asset you want to trade.
2

Select Destination Asset

Click the asset selector on the To card and choose the asset you want to receive.
3

Enter Amount

Type the amount you want to swap in the From field. The To amount updates automatically based on the live quote.
4

Enter Recipient Address

Enter the address where you want to receive the swapped asset. This is where the maker will send your funds after the swap is executed.
5

Review Quote

Check:
  • Exchange rate
  • Fee amount
  • Output amount matches expectations
6

Open Confirmation Modal

Click the Swap button. A confirmation modal appears with a summary of the order.
7

Confirm the Order

Review the final details in the modal and click Confirm Swap. This creates the order and redirects you to the order page.

​
Confirmation Modal

Before the order is created, the modal shows:
  1. Assets - From and To assets with amounts
  2. Rate - The exchange rate for this order
  3. Fees - Breakdown of all fees
  4. Recipient Address - Where the swapped asset will be sent
  5. Confirm / Cancel - Final action buttons
After confirming, the order is created and you are redirected to the order page. This does not execute the swap yet — you still need to pay the deposit.

​
Order Page

After creating an order, you are redirected to the Order Page (/[orderId]). This is where you pay and track your order.

​
Deposit Instructions

The order page displays:
ElementDescription
QR CodeScannable QR code with the deposit address or invoice
Deposit Address / InvoiceThe exact address or invoice to pay (copyable)
Amount to PayThe exact amount you need to send
Expiry CountdownTime remaining before the order expires
Pay with WalletButton to pay directly from your connected wallet (if supported)

​
Payment Methods

You can pay the deposit in several ways:
If your wallet supports the payment type (e.g., Lightning via WebLN), a Pay with Wallet button appears on the order page. Click it to pay directly without leaving the browser.
Click the Copy button next to the deposit address or invoice. Paste it into your wallet app and send the exact amount shown.
Use a mobile wallet to scan the QR code displayed on the order page.

​
Order Status Timeline

The order page shows a visual timeline of your order’s progress: 
  Awaiting Deposit  →  Confirming  →  Exchanging  →  Completed
       ●                  ○              ○              ○
StatusWhat It Means
Awaiting DepositThe order is created. Pay the deposit to proceed.
Payment ConfirmedYour payment has been received and confirmed.
Executing SwapThe maker is processing the swap.
Swap CompletedThe swapped asset has been sent to your recipient address.
The order page polls for status updates every 10 seconds. You do not need to refresh manually.

​
Special Scenarios

Rate Decision: If the exchange rate changes significantly while your order is being processed, you may be asked to accept or reject the new rate. See Advanced Features for details. Payment Issues: If you overpay or underpay, the order page will display the discrepancy and instructions for resolution. See Advanced Features for details.

​
Asset Selection

​
Choosing Assets

  1. Click the asset selector button
  2. Browse available assets or search
  3. Select an asset to populate the card

​
Network/Protocol Selection

Each asset may support multiple protocols:
ProtocolDescriptionSpeed
RGB on LightningRGB assets via LightningFast
RGB On-chainRGB assets on Bitcoin10+ min
BTC LightningNative Bitcoin LightningFast
The network badge shows which protocol is active.

​
Valid Trading Pairs

Not all assets can be traded with each other. Invalid pairs are automatically filtered out. Common pairs include:
  • BTC / USDT
  • BTC / XAUT

​
Amount Handling

​
Input Methods

From Amount (Exact Input):
  • Enter the exact amount you want to spend
  • The To amount is calculated based on the quote
To Amount (Exact Output):
  • Click on the To card’s input
  • Enter the exact amount you want to receive
  • The From amount is calculated

​
Display Units

For BTC, you can choose to display amounts in:
  • BTC - Standard Bitcoin notation (e.g., 0.00021)
  • sats - Satoshi notation (e.g., 21,000)
Change this in Settings (gear icon).

​
Min/Max Limits

Each trading pair has limits:
  • Minimum - Smallest tradeable amount
  • Maximum - Largest tradeable amount
Amounts outside these limits show a validation error.

​
Quote Information

The quote section displays:
InfoDescription
RateCurrent exchange rate (e.g., 1 BTC = 95,000 USDT)
FeeNetwork and protocol fees
ExpiresQuote validity countdown
Quotes refresh automatically via WebSocket. The rate shown at the time you click Swap is used for the order.

​
Swap Arrow

Click the swap arrow to:
  • Reverse the trade direction
  • Swap From and To assets
  • Amounts are also swapped

​
Real-Time Updates

The interface provides live updates:
  • Quote Refresh - Rates update via WebSocket
  • Price Changes - Highlighted when price moves
  • Validation - Instant feedback on amounts
  • Connection Status - Wallet connectivity shown

​
Tips for Best Results

Complete your order promptly. Quotes expire after a short period, and the rate may change.
Verify the recipient address carefully before confirming. The maker will send the swapped asset to this address and it cannot be changed after order creation.
RGB on Lightning offers faster settlement. Prefer Lightning routes when available.
Pay the exact deposit amount shown on the order page. Overpaying or underpaying may cause issues with your order.

​
Common Issues

IssueSolution
Quote loading slowlyCheck internet, refresh page
Amount validation errorAdjust to within min/max limits
Wallet not respondingEnsure wallet is unlocked
Order expiredCreate a new order with a fresh quote
Payment not detectedWait for confirmation, check transaction status in your wallet