Rsk Swap SDK

Rsk Swap SDK acts eases the integration between client applications and the RSK Swap API. Which is an aggregator that providers several ways to perform swaps to obtain RBTC through different 3rd party providers.

Installation

For most users, simply install the SDK from npm:

npm install @rsksmart/rsk-swap-sdk

For installing private packages from the GitHub registry (requires authentication), see the Building from Source section below.

Quickstart guide (integrating into a dApp)

Now that you have installed the SDK in your project, you can start using it as shown in the Usage section.

Usage

Create RskSwapSDK client instance. For this SDK, the blockchain connection is mandatory. There are 3 ways to create an RSK connection, you can check them in [BlockchainConnection class](TODO url) documentation.

    const blockchainConnection: BlockchainConnection = await BlockchainConnection.createUsingStandard(window.ethereum)
    const sdk: RskSwapSDK = new RskSwapSDK('Local', blockchainConnection)

To know which providers can facilitate a specific swap you should perform an estimation. The amount must be in the lowest unit for the origin currency. For example, if you're swapping BTC -> RBTC the amount must be in sats and if you're swapping RBTC -> USDT the amount must be in wei.

    const amount = 250_000_000
    const estimations = await sdk.estimateSwap({
        fromChainId: '1',
        toChainId: '30',
        fromToken: 'ETH',
        toToken: 'RBTC',
        fromAmount: amount
    })

🚧 Important

Notice that to identify the networks we use the Chain ID, currently there are two special cases where we don't use it. These are Bitcoin and the Lightning Network. For Bitcoin it must be passed BTC as Chain ID and for the Lightning Network LN. The differentiation between testnet and mainnet is done through the token (BTC or tBTC).

You can also fetch the limits of a specific pair to know what is the minimum and maximum amounts you can swap for a specific pair.

    const args: SwapLimitsArgs = {
      fromToken: 'ETH',
      toToken: 'RBTC',
      toNetwork: '30',
      fromNetwork: '1',
    }
    const limits = await sdk.getSwapLimits(args)

Then, once you know which provider to use, you can start doing operations with the client by indicating the providerId

    const args: CreateSwapArgs = {
      fromAmount: amount,
      fromToken: 'ETH',
      toToken: 'RBTC',
      toNetwork: '30',
      fromNetwork: '1',
      providerId: estimations[1].providerId,
      address: '<your address in the destination network>',
      refundAddress: '<your address in the origin network>'
    }
    const result = await sdk.createNewSwap(args)

Finally, the created swap will contain a [SwapAction](TODO url) indicating the SDK the required actions to perform your swap. In some cases, like EVM transactions, the RskSwapSDK executes the transaction by using the connected provider. But in cases like Bitcoin or Lightning the executeSwap function will just return the proper BIP21 or BOLT11 string so the consumer application can present it for the user.

    const txHash = await sdk.executeSwap(result.action)
    const receipt = await blockchainConnection.getTransactionReceipt(txHash)

Depending on your provider, the swap might not arrive automatically to your wallet. In that case a claim transaction is required, this information will be available in the [SwapAction](TODO url) object. This doesn't necessarily mean that a EVM transaction will be produced, as the claim might happen in a non EVM chain, for the current integrations that RskSwap has, there is not action required from the consumer besides executing claimSwap when the claim is not in a EVM chain.

    if (result.action.requiresClaim) {
        const claimTxHash = await sdk.claimSwap(result)
    }

⚠️

The [swap object](TODO url) contains a context field with all the information specific to the provider performing the swap. It's very important that the SDK consumer stores this object securely as it might contain private information used to claim or refund swaps. E.g. private keys for atomic swaps. It's also important to remark that when this is the case, the private information is always securely generated by the SDK in client side and is not sent to the server.

Configuration

This SDK only requires the [BlockchainConnection class](TODO url) instance and the environment name to be used. Regarding the BlockchainConnection it mustn't be readonly as the SDK will try to broadcast transactions during the execute step.

Local Development

If you want to contribute to the SDK or build it from source, you'll need to set up your local development environment.

Development Prerequisites

Before setting up the project locally, ensure you have the following requirements:

Node.js Version

This project uses the Node.js version pinned in the .nvmrc file (currently v24.14.1). To install and use the correct version:

1. If you're using nvm (Node Version Manager), run:

   nvm use

   This will automatically switch to the version specified in .nvmrc.

2. Alternatively, you can manually install the matching Node.js version from nodejs.org.

Python 3

The prepare script requires Python 3 to install and configure pre-commit hooks. Ensure Python 3 is installed on your system:

• Check if Python 3 is installed: python3 --version or python --version
• Install Python 3 from python.org if needed

GitHub Token (for private packages)

If you need to install private versions of this package from the GitHub registry, you'll need a GitHub personal access token with the following configuration:

1. Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Generate a new classic token with the read:packages scope
3. Use this token when prompted for authentication when running npm login

⚠️ Important: The token must be a classic token with the read:packages permission. Fine-grained tokens are not supported.

Building from Source

To build the SDK locally:

1. Clone the repository:

   git clone git@github.com:rsksmart/rsk-swap-sdk.git
   cd rsk-swap-sdk

2. Install dependencies (this will trigger the prepare script which requires Python 3):

   npm i

3. Build the SDK:

   npm run build:clean

Installing Private Packages from GitHub Registry

If you need to install private versions from the GitHub registry, authenticate first:

npm login --scope=@rsksmart --auth-type=legacy --registry=https://npm.pkg.github.com

You'll need to provide your GitHub username and the classic token with read:packages scope mentioned in the Development Prerequisites section above.

Application Programming Interface

This SDK's public surface is the RskSwapSDK class. See docs/api.md for the full table of exports.

Testing

Command	Purpose
npm test	Build the SDK, then run the Jest unit test suite
npm run test:coverage	Same, with coverage collected from ./src/**
npm run test:integration	Run the integration test suite in integration-test/ against a real Boltz submarine swap

Documentation

See docs/ for more:

• docs/setup.md — prerequisites, build/test commands, and the SDK's external dependencies (the RSK Swap API per environment, and BlockchainConnection)
• docs/api.md — full table of the package's public exports
• docs/providers.md — the SwapProviderClient extension point, its bundled implementations (Boltz, Changelly, Symbiosis, LI.FI), and how to add a new one

Contributing

See CONTRIBUTING.md for how to contribute to this project.