Errors
Every rejection that reaches the Rust engine is anError with a stable code. Narrow it with isKaleidoSwapError:
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
ClaimFallbackFailedorrgb_fee_input_required: the swap engine refused the operation. Internal: a failure inside the binding.
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
init() fails or the WebAssembly binary is not found
init() fails or the WebAssembly binary is not found
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)).React Native: native module missing at first import
React Native: native module missing at first import
@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.Python: no wheel for my platform
Python: no wheel for my platform
Networks
forNetwork('mainnet') throws
forNetwork('mainnet') throws
signet, or pass an explicit maker URL.The lockup never shows up, or a claim cannot find the output
The lockup never shows up, or a claim cannot find the output
https://esplora.signet.kaleidoswap.com); a testnet3 endpoint encodes addresses the same way and fails silently. See Networks.Creating swaps
TypeError: Cannot convert 0 to a BigInt
TypeError: Cannot convert 0 to a BigInt
bigint got a number. Use 0n, or BigInt(value).Create fails with a validation error
Create fails with a validation error
An L-USDT create is refused before any request is sent
An L-USDT create is refused before any request is sent
lusdtAssetId (lusdt_asset_id in Python). See Move funds between chains.PayThroughClient throws on construction
PayThroughClient throws on construction
lightningNetwork is required: "bitcoin", "testnet", "signet", or "regtest".Chain swap: 'needs claimPublicKey and refundPublicKey'
Chain swap: 'needs claimPublicKey and refundPublicKey'
Reverse swap to ARKD is refused
Reverse swap to ARKD is refused
IntentsCorridor and the Arkade venue. See Lightning ↔ Arkade.Organization key or API key rejected locally
Organization key or API key rejected locally
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
acceptQuote fails with 401 invalid_swap_auth
acceptQuote fails with 401 invalid_swap_auth
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.A swap stays in awaiting_funding or locked and never ends
A swap stays in awaiting_funding or locked and never ends
resume() on start and follow each swap in resumed with settled() or phases().constructClaim refuses an unconfirmed lockup
constructClaim refuses an unconfirmed lockup
allowZeroConf: true. See Claims and refunds.A helper returns not-yet
A helper returns not-yet
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.Cooperative refund refused
Cooperative refund refused
mode: "cooperative" never falls back. Wait for timeoutBlockHeight and refund through the script path, or use mode: "auto".ClaimFallbackFailed
ClaimFallbackFailed
rgb_fee_input_required
rgb_fee_input_required
funding: { kind: "callerInputs" } and add BTC inputs from your wallet.Status updates
No updates arrive
No updates arrive
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).The Node process does not exit
The Node process does not exit
ws.close() (TypeScript) or ws.shutdown() (Python) when you are done with a status stream.