Rainbow Swap 🌈 SDK

This SDK is designed for building applications on top of Rainbow.ag - Swap Aggregator on TON blockchain 💎.

To receive your partnerId, set custom fees, and enjoy a 50% revenue share, contact us in our Community Chat.

Docs

• SDK guide: https://rainbow-ag.gitbook.io/docs/technical/sdk
• Full docs: https://rainbow-ag.gitbook.io/docs

Quick links

• Support: https://t.me/rainbow_swap_manager

Installation

You can install the Rainbow Swap SDK using either npm or Yarn:

Using npm:

npm install rainbow-swap-sdk

Using Yarn:

yarn add rainbow-swap-sdk

What you get

• Typed API helpers for assets, routes, and swap history.
• Utilities for GRAM amount conversion (toNano, fromNano).
• Enum/type exports to keep your integration strongly typed.

Integrate your dApp

Example: swapping 1.35 GRAM to USDT

import {getAssetsList, getBestRoute, toNano} from 'rainbow-swap-sdk';

// 1. Load the list of available tokens
const assetsList = await getAssetsList({
    userAssets: [] // Array of asset addresses the user holds; see AssetsListParams for more details.
});

// Retrieve specific assets by their address
const inputAsset = assetsList.find(asset => asset.address === 'ton');
const outputAsset = assetsList.find(
    asset =>
        asset.address === 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs'
);

// 2. Load the best swap route and swap messages
const bestRouteResponse = await getBestRoute({
    inputAssetAmount: toNano('1.35', inputAsset.decimals).toString(), // Convert 1.35 GRAM to nano format
    inputAssetAddress: inputAsset.address,
    outputAssetAddress: outputAsset.address,
    senderAddress: 'UQDGGjjuwhikx8ZPJsrLbKXGq7mx26D8pK_l8GqBejzB52Pa', // Optional user wallet address; if set, swap messages will be returned
    partnerId: 'demo-partner' // Optional unique identifier in our App Developer Partnership program
});

// 3. Sign and send messages to the blockchain to execute the swap.
// This example uses the React UI client. For other frameworks, refer to https://docs.ton.org/develop/dapps/ton-connect/overview
import {useTonConnectUI} from '@tonconnect/ui-react';

const [tonConnectUI] = useTonConnectUI();

const result = await tonConnectUI.sendTransaction({
    validUntil: Math.floor(Date.now() / 1000) + 60, // 60 seconds from now
    messages: bestRouteResponse.swapMessages
});

API overview

Assets

import {getAssetsList} from 'rainbow-swap-sdk';

const assets = await getAssetsList({
    userAssets: ['ton'], // optional: user-held assets
    searchValue: 'USDT', // optional: filter by name/symbol/address
    limit: 100 // optional: 10..200
});

Best route

import {getBestRoute, toNano} from 'rainbow-swap-sdk';

const route = await getBestRoute({
    inputAssetAmount: toNano('1.35', 9).toString(),
    inputAssetAddress: 'ton',
    outputAssetAddress: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs',
    senderAddress: 'UQDGGjjuwhikx8ZPJsrLbKXGq7mx26D8pK_l8GqBejzB52Pa',
    maxSlippage: 1.5,
    partnerId: 'demo-partner'
});

Swap history

import {getSwapHistoryData} from 'rainbow-swap-sdk';

const history = await getSwapHistoryData({
    bocHash: '64c1a1c5b7c2f8...'
});

Application Status Check

You may want to check the status of your application to ensure everything is functioning correctly. For example, temporarily disable swaps if block production on TON is disrupted due to an external event like the DOGS listing.

import {getAppStatus} from 'rainbow-swap-sdk';

const {
    isSwapsEnabled, // true if everything is working fine
    message // Explanation of why swaps are disabled, if applicable
} = await getAppStatus();

Notes

• getAssetsRecord is deprecated; use getAssetsList instead.
• getBestRoute returns swapMessages only when senderAddress is provided.
• Requests to getAssetsList and getBestRoute cancel any previous in-flight request.

Live Example

For a live example of using the SDK, visit the Rainbow Swap 🌈 Repository.

Contact

For questions and suggestions, visit Community Chat.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.