Skip to main content

Errors

Every rejection that reaches the Rust engine is an Error with a stable code. Narrow it with isKaleidoSwapError:
TypeScript
  • InvalidArgument: the binding rejected an input, such as a malformed key or a request missing a field. The message names the field.
  • Engine codes, such as ClaimFallbackFailed or rgb_fee_input_required: the swap engine refused the operation.
  • Internal: a failure inside the binding.
Values rejected by the generated WebAssembly glue before Rust sees them stay plain JavaScript errors. The common one is a TypeError from passing a number where a bigint is declared. In Python, errors are raised as kaleidorg_swap_sdk.Error variants. The KaleidoSwap API reports its own failures as a SwapError, narrowed with isSwapError. Its codes are listed in The KaleidoSwap API.

Installation and loading

Your bundler must emit vendor/bindings_wasm_bg.wasm. If you bundled the Node entry into a single file, copy the binary next to your output and pass it to init(). To serve it yourself, pass its URL: await init(new URL("/assets/bindings_wasm_bg.wasm", location.origin)).
With pnpm 10+, add @kaleidorg/swap-sdk-react-native to onlyBuiltDependencies so its install script fetches the binaries. If the release archive could not be downloaded, reinstall once GitHub is reachable. Expo Go is not supported; use a development build.
Prebuilt wheels cover Linux x86_64/aarch64, macOS x86_64/arm64, and Windows x86_64. Elsewhere pip builds the source distribution, which needs Rust 1.88+.

Networks

There is no KaleidoSwap mainnet maker yet. The SDK errors instead of falling back to a third party. Use signet, or pass an explicit maker URL.
Check that the chain endpoint matches the network. The signet maker settles on Mutinynet (https://esplora.signet.kaleidoswap.com); a testnet3 endpoint encodes addresses the same way and fails silently. See Networks.

Creating swaps

A parameter declared bigint got a number. Use 0n, or BigInt(value).
The SDK refused the maker’s response because it does not match your request or keys: script, lockup address, timeout, or invoice hash. Do not fund it. Check that you passed the right public key and preimage hash, and that you are talking to the maker you expect.
Either the maker does not offer the route right now, or the KaleidoSwap API does not serve it yet: chain swaps, L-USDT, USDT-RGB, Arkade, and pay-through go through the swap engine. The refusal’s message says which. See The KaleidoSwap API.
On testnet and regtest, pass the L-USDT asset id you trust as lusdtAssetId (lusdt_asset_id in Python). See Move funds between chains.
lightningNetwork is required: "bitcoin", "testnet", "signet", or "regtest".
Chain swaps require both keys so both lockup scripts can be verified. Derive them from two indexes.
Arkade is not a Boltz route. Use IntentsCorridor and the Arkade venue. See Lightning ↔ Arkade.
The value is malformed: an organization key must be a valid 64-hex x-only point, and an API key must look like kld_test_… or kld_live_…. The maker URL must be https unless it is a loopback address. A client cannot carry both credentials.

Claims and refunds

Pass the swap’s swapAuth from the create response. If you lost it, recover it with recoverSwapAuth(id, secretKey). Without it, the re-quote cannot be accepted and the swap expires into its refund path.
Nothing is following it. Call resume() on start and follow each swap in resumed with settled() or phases().
A claim needs a lockup your chain backend shows confirmed and unspent. Wait for the confirmation, or opt in with allowZeroConf: true. See Claims and refunds.
Read reason. For claims: the lockup lacks your required confirmations, or the deadline is inside the safety margin. For refunds: the timeout has not been reached and the maker did not co-sign.
mode: "cooperative" never falls back. Wait for timeoutBlockHeight and refund through the script path, or use mode: "auto".
Both the cooperative and the script-path claim failed. The error carries both causes. Recover through the script path urgently, before the timeout.
The HTLC’s sats cannot pay the fee and keep the minimum payout. Prepare the spend with funding: { kind: "callerInputs" } and add BTC inputs from your wallet.

Status updates

Make sure runWsLoop() is running and you called subscribeSwap(id). A dead socket reports no error, notably after a mobile app is backgrounded: check isConnected() and fall back to swap(id).
Call ws.close() (TypeScript) or ws.shutdown() (Python) when you are done with a status stream.