Bitflow SDK

An overview of the Bitflow SDK, including installation, configuration, and usage in your project.

Bitflow SDK

Bitflow SDK is a powerful and easy-to-use library for interacting with the Bitflow Protocol. It provides a set of tools to seamlessly integrate Bitflow functionality into your applications. Currently, the SDK is available by request only. If you are interested in integrating with the BitFlow SDK please reach out to the team on Discord.

Table of Contents

  1. Installation

  2. Configuration

  3. Usage

  4. Troubleshooting

  5. License

Installation

Install the Bitflow SDK using npm:

npm install bitflow-sdk

Latest Stable Version is 1.6.1

Configuration

Before using the Bitflow SDK, you need to set up your environment variables. Create a .env file in your project root with the following variables:

API_HOST=your_api_host_here (will be provided by Bitflow)

API_KEY=your_api_key_here (will be provided by Bitflow)

STACKS_API_HOST="https://api.hiro.so"

READONLY_CALL_API_HOST=your_readonly_call_api_host_here (will be provided by Bitflow)

Usage

Here's a step-by-step guide to implement the Bitflow SDK in your project:

  1. Import the SDK:

import { BitflowSDK } from 'bitflow-sdk';

  1. Initialize the SDK:

const bitflow = new BitflowSDK({
  API_HOST: 'your_api_host',
  API_KEY: 'your_api_key',
  STACKS_API_HOST: 'your_stacks_api_host',
  READONLY_CALL_API_HOST: 'your_readonly_call_api_host'
});

  1. Use the SDK methods to interact with the Bitflow Protocol. Here are some common operations:

Available Functions

1. Get Available Tokens

Retrieve a list of all available tokens:

const tokens = await bitflow.getAvailableTokens();
console.log(tokens);

2. Get Possible Swaps

Get all possible swap options for a given token:

const tokenXId = 'token-stx'; // the `tokenId` prop from `Token` interface
const swapOptions = await bitflow.getPossibleSwaps(tokenXId);
console.log(swapOptions);

Sample Response

3. Get All Possible Token Y

Retrieve all possible tokens that can be swapped for a given token:

const tokenXId = 'token-stx';
const possibleTokens = await bitflow.getAllPossibleTokenY(tokenXId);
console.log(possibleTokens);

Sample Response

4. Get All Possible Token Y Routes

Get all possible routes for swapping between two tokens:

const tokenXId = 'token-usda';
const tokenYId = 'token-stx';
const routes = await bitflow.getAllPossibleTokenYRoutes(tokenXId, tokenYId);
console.log(routes);

5. Getting Quote for Route

Get the quotes for a swap between two tokens:

const tokenXId = 'token-usda';
const tokenYId = 'token-stx';
const amount = 100; // Amount of tokenX to swap
const quoteResult = await bitflow.getQuoteForRoute(tokenXId, tokenYId, amount);
console.log(quoteResult);

Sample Response

6. Getting Swap Parameters

Get the necessary parameters for executing a swap:

const swapExecutionData = {
  route: selectedRoute,
  amount: 100,
  tokenXDecimals: selectedRoute.tokenXDecimals,
  tokenYDecimals: selectedRoute.tokenYDecimals
};
const senderAddress = 'your_stacks_address';
const slippageTolerance = 0.01; // 1%

const swapParams = await bitflow.getSwapParams(swapExecutionData, senderAddress, slippageTolerance);
console.log(swapParams);

Sample Response

7. Execute Swap

Execute a swap transaction:

const swapExecutionData = {
  route: selectedRoute,
  amount: 100,
  tokenXDecimals: selectedRoute.tokenXDecimals,
  tokenYDecimals: selectedRoute.tokenYDecimals
};
const senderAddress = 'your_stacks_address';
const slippageTolerance = 0.01; // 1%

await bitflow.executeSwap(
  swapExecutionData,
  senderAddress,
  slippageTolerance,
  stacksProvider, // a valid object of type `StacksProvider` from `@stacks/connect`
  (data) => console.log('Swap executed:', data),
  () => console.log('Swap cancelled')
);

The executeSwap receives the same params as getSwapParams, with 3 more additional params: stacksProvider?: StacksProvider, onFinish?: (data: any) => void, onCancel?: () => void.

The only difference between those function is that getSwapParams will return the params you need to open a contract call and executeSwap will try to open the contract call with the openContractCall function from '@stacks/connect' lib.

Types

The SDK exports several TypeScript types that you can use in your application:

  • Token: Represents a token with its properties.

  • SwapOptions: Represents possible swap options for a token.

  • SelectedSwapRoute: Represents a selected swap route with its details.

  • QuoteResult: Represents the result of a quote request.

  • SwapExecutionData: Represents the data needed to execute a swap.

  • SwapDataParamsAndPostConditions: Represents the parameters and post-conditions for a swap.

import { Token, SwapOptions, SelectedSwapRoute, QuoteResult, SwapExecutionData, SwapDataParamsAndPostConditions } from 'bitflow-sdk';

Troubleshooting

If you encounter any issues while using the Bitflow SDK, please check the following:

  1. Ensure all environment variables are correctly set in your .env file.

  2. Make sure you have the latest version of the SDK installed.

  3. Check that you're using a valid Stacks address for the senderAddress parameter.

License

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

PreviousOverviewNextSmart Contracts

Last updated