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-rust-sdk. Clone it next to this repo so the layout is:

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

Prerequisites: Node.js 18+, 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-rust-sdk/wasm
CC_wasm32_unknown_unknown="/opt/homebrew/opt/llvm/bin/clang" wasm-pack build --target web --scope blockstream

The --scope blockstream flag is required: the SDK imports @blockstream/anyswap-wasm, so the generated pkg/package.json must declare that scoped name. Without it, wasm-pack produces a package called anyswap-wasm and npm install will land it at node_modules/anyswap-wasm where the SDK's imports cannot find it.

By default package.json pins @blockstream/anyswap-wasm to the published version. To use the local build, point the dep at the freshly-built pkg directory and finish the install:

cd ../../anyswap-ts-sdk
npm install ../anyswap-rust-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, so the registry version is no longer resolved.

Run the examples

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

make run_local
make setup_nodes_network

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

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

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). Make sure wasm-pack was invoked with --scope blockstream, otherwise the output is named anyswap-wasm and will not satisfy the SDK's import.
• wasm-pack build fails: pass the Homebrew clang explicitly via CC_wasm32_unknown_unknown (see the build command above).
• Examples fail with fetch failed: the local services are not running. Check curl http://localhost:8083/v1/info and curl http://localhost:8080/regtest/api/blocks/tip/height.