Swap BTC and USDT on RGB

• The Swap SDK handles the Bitcoin side: it checks the maker’s contract and builds the transaction.
• Your rgb-lib wallet handles the asset: it moves it, validates its history, and marks (“colors”) the transaction with the asset. The SDK does not bundle rgb-lib.

​

Which swap to use

​

Setup

import { init, SwapClient, SwapMasterKey, SwapScript, toJson } from "@kaleidorg/swap-sdk";

await init();

const network = "signet";
const makerUrl = "https://maker.signet.kaleidoswap.com/v2";
const bitcoinEsploraUrl = "https://esplora.signet.kaleidoswap.com";
const liquidEsploraUrl = "https://blockstream.info/liquidtestnet/api";

const client = new SwapClient(makerUrl);
const master = SwapMasterKey.fromSwapMnemonic(process.env.SWAP_MNEMONIC!, network);

// Two things your app provides:
//   nextSwapIndex(): Promise<bigint>  a persisted counter, never reused
//   store                             durable storage for swap records

import asyncio, os
import kaleidorg_swap_sdk as sdk

network = sdk.Network.SIGNET
client = sdk.SwapClient("https://maker.signet.kaleidoswap.com/v2", None)
master = sdk.SwapMasterKey.from_swap_mnemonic(os.environ["SWAP_MNEMONIC"], network)

​

HTLC swaps over Lightning

​

Pin the contract

// USDT-RGB -> Lightning
const swap = await client.createSubmarineSwap(
  "signet",
  { from: "USDT-RGB", to: "BTC", invoice, refundPublicKey: refundKey.publicKey, pairHash: card.hash },
  usdtContractId,
  2_000n, // optional cap on the BTC collateral (default 1,000 sats), never sent to the maker
);

// Lightning -> USDT-RGB
const reverse = await client.createReverseSwap(
  "signet",
  { from: "BTC", to: "USDT-RGB", invoiceAmount, preimageHash: preimage.sha256, claimPublicKey: claimKey.publicKey, pairHash },
  usdtContractId,
);

request = sdk.CreateReverseRequest(
    invoice_amount=invoice_amount,
    _from=btc,
    to=usdt_rgb,               # Currency.USDT_RGB on the on-chain side
    preimage_hash=preimage.sha256(),
    claim_public_key=claim_key.public(),
    rgb_contract_id=usdt_contract_id,
)

​

Fund or accept the lock

• Submarine: your rgb-lib wallet funds the HTLC with the asset.
• Reverse: your rgb-lib wallet accepts the maker’s lock consignment and validates the asset proofs. There is no transaction.confirmed event for reverse RGB swaps: enforce lock confirmations through your chain backend and rgb-lib before claiming. Before you pay the invoice, compare the response’s claimFeeRate with current fees and the remaining timeout.

​

Claim or refund

const script = SwapScript.fromReverse("bitcoin", "signet", reverse, claimKey.publicKey);
const spend = await script.prepareRgbClaim({
  outputAddress: rgbWalletReceiveAddress,       // an RGB wallet witness receive
  funding: { kind: "htlcValue", feeRateSatVb: reverse.rgb.claimFeeRate },
  maxFee: 10_000n,
  swapId: reverse.id,
  makerBaseUrl,
  network: "signet",
  bitcoinEsploraUrl,
  lockupTxHex,
});

// 1. Color spend.template() with rgb-lib's psbt_op_prepare_with_expiry,
//    assigning the asset to paymentOutputIndex.
// 2. Return the colored PSBT and its allocations to the SDK:
const finalized = spend.finalizeClaim(coloredPsbt, claimKey.secretKey, preimage.preimage);
// 3. Sign any remaining wallet inputs, broadcast, then complete the rgb-lib
//    operation (psbt_op_mark_broadcast, psbt_op_apply, psbt_op_provide_receive_consignment).

• If the HTLC’s sats cannot cover the fee, preparation fails with rgb_fee_input_required. Use funding: { kind: "callerInputs" }, add BTC inputs and change, and keep the new spend from spend.fund(fundedPsbt). Fund before coloring or signing.
• Refunds use prepareRgbRefund and finalizeRefund after the timeout, with the original colored lock transaction.
• A Bitcoin broadcast alone does not complete the RGB receive. Finish the rgb-lib operation.

​

Cooperative refunds

​

Atomic swaps on L1

import { AtomicSwaps, SwapClient, ATOMIC_BTC_TO_USDT_RGB } from "@kaleidorg/swap-sdk";

const atomic = new AtomicSwaps(new SwapClient(makerUrl));

// 1. Quote. Throws unless the quote, and the rgb-lib offer inside it, match what you asked.
const quote = await atomic.quote(
  { pair: ATOMIC_BTC_TO_USDT_RGB, amount: 100_000n, direction: "from" },
  {
    assetId: usdtContractId,
    bitcoinNetwork: "Signet",       // rgb-lib's network name for your wallet
    maxNetworkFeeSat: 10_000n,
    minToAmount,                    // the least you accept, in base units: this is the price protection
    maxOfferTtlSecs: 3_600n,
  },
);
// Feed quote.offer to rgb-lib's accept_swap_offer.

// 2. Request. Pass every outpoint your wallet holds (rgb-lib's list_unspents).
const { proposal, makerInputs } = await atomic.request(quote.id, rgbLibRequest, walletOutpoints);
// Feed proposal to complete_swap_proposal.

// 3. Complete. The maker signs last and broadcasts.
const done = await atomic.complete(quote.id, rgbLibCompletion);
// Feed done.completion to accept_swap_transfers.

const final = await atomic.track(quote.id, { onStatus: (s) => console.log(s.status) });

• The quote answers your pair, direction, amount, asset, and network, stays within your fee and offer-lifetime limits, and has not passed its deadline. The rgb-lib offer inside it moves the same amounts and asset as the quote, so what your wallet signs is what you were shown.
• The proposal lists none of your own coins as the maker’s, and no coin twice.
• The completion broadcasts the transaction you agreed to.

​

If something goes wrong

• HTLC swap, maker never pays (USDT-RGB → Lightning): refund with prepareRgbRefund and finalizeRefund after the deadline, or earlier through a cooperative refund if the maker offers it.
• HTLC swap, maker never locks (Lightning → USDT-RGB): your Lightning payment is released. Nothing to do.
• Atomic swap stops before complete: the maker signs last and broadcasts, so before that nothing has moved.
• Any RGB spend: a Bitcoin broadcast alone does not finish the RGB transfer. Complete the rgb-lib operation, or the wallet will not show the asset.