anyswap-ts-sdk

TypeScript SDK for atomic swaps between Lightning and on-chain Bitcoin or Liquid.

Full documentation: https://lightning.gl-page.blockstream.io/anyswap-ts-sdk

Install

npm install @blockstream/anyswap-sdk

Build from source

The SDK depends on a sibling wasm crate built from anyswap. Clone it next to this repo so the layout is:

your-workspace/
  anyswap/
  anyswap-ts-sdk/

Prerequisites: Node.js 22+, Rust with the wasm32-unknown-unknown target, wasm-pack, and a working clang/LLVM toolchain.

On macOS:

rustup target add wasm32-unknown-unknown
brew install wasm-pack llvm

Build the wasm crate, then this repo:

cd ../anyswap
make generate-wasm

The workspace package.json points @blockstream/anyswap-wasm at the freshly-built local pkg directory. Finish the installation from this repo:

cd ../anyswap-ts-sdk
npm install ../anyswap/crates/sdk-wasm/pkg
npm run build

npm install <path> reads the target's name field and overwrites the existing @blockstream/anyswap-wasm entry with a file: reference.

Run the examples

The examples talk to a local swap service from anyswap. From its repo root:

make run-local
make setup-nodes-network

That brings up the swap service on http://localhost:8083, an Esplora API on http://localhost:8080/regtest/api, and the Liquid stack (Esplora on http://localhost:8081/liquidregtest/api). Then, from this repo:

npm run example:btc-swap-in
npm run example:btc-swap-out

npm run example:lbtc-swap-in
npm run example:lbtc-swap-out

Those drive the protocol by hand from poll responses. The driver examples let the SDK run the swaps instead: driver-swaps drives any mix of swaps on both chains in the background, driver-advance drives one swap by hand over a file store and resumes it after a restart.

npm run example:driver-swaps -- bcrt1q... 50000 lnbcrt1...
npm run example:driver-advance -- out 50000 bcrt1q...

A regtest Elements chain mints its own L-BTC at genesis, so set POLICY_ASSET at the top of the Liquid examples to that chain's asset id before running them. make run-local writes it into the service's config.toml, or read it straight from the node:

elements-cli -chain=liquidregtest dumpassetlabels

Documentation

Docs are built with MkDocs Material. To serve them locally you need Python 3.12+ and uv:

uv sync --all-extras
uv run mkdocs serve

Troubleshooting

• @blockstream/anyswap-wasm cannot be resolved: build the sibling wasm crate first (see Build from source).
• Examples fail with fetch failed: the local services are not running. Check curl http://localhost:8083/info and curl http://localhost:8080/regtest/api/blocks/tip/height.