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 .
Table of Contents
Bitflow SDK
Table of Contents
Installation
Configuration
Usage
Available Functions
Get Available Tokens
Get Possible Swaps
Get All Possible Token Y
Get All Possible Token Y Routes
Getting Quote for Route
Getting Swap Parameters
Executing Swap (uses @stacks/connect)
Bitflow SDK - Keeper Functions
Get or Create Keeper Contract
Create Order
Get Order
Get User
Get Quote
Create Group Order
Get Group Order
Cancel Order
Cancel Group Order
Get Keeper Tokens
Get Keeper Possible Swaps
Get All Keeper Possible Token Y
Get All Keeper Possible Token Y Routes
Get Keeper Quote For Route
Example of BTC to sBTC
Types
Outline of Optional Parameters
Troubleshooting
License
Installation
Install the Bitflow SDK using npm:
npm install @bitflowlabs/core-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:
# will be provided by Bitflow
BITFLOW_API_HOST=https://example-api-host.com
# will be provided by Bitflow
BITFLOW_API_KEY=<your_api_key_here>
# will be provided by Bitflow
READONLY_CALL_API_HOST=https://example-readonly-api.com
# will be provided by Bitflow
KEEPER_API_KEY=<your_api_key_here>
# will be provided by Bitflow
KEEPER_API_HOST=https://your-keeper-api-host.com
Usage
Here's a step-by-step guide to implement the Bitflow SDK in your project:
Import the SDK:
import { BitflowSDK } from '@bitflowlabs/core-sdk';
Initialize the SDK:
// if no parameters are provided, the SDK will try to use the environment variables
const bitflow = new BitflowSDK({
BITFLOW_API_HOST: string,
BITFLOW_API_KEY: string,
READONLY_CALL_API_HOST: string,
KEEPER_API_KEY: string,
KEEPER_API_HOST: string
});
Use the SDK methods to interact with the Bitflow Protocol. Here are some common operations:
The Bitflow SDK also provides a set of Keeper functions that enable automated token swaps and order management on the Stacks blockchain. These functions allow your application to interact with the Keeper service for executing various types of token operations.
Available Keeper Functions
Get or Create Keeper Contract
Get an existing keeper contract or create a new one for a Stacks address:
const groupId = 'your-group-id';
const includeOrders = true; // set to true to include detailed order information
const groupOrder = await bitflow.getGroupOrder(groupId, includeOrders);
console.log(groupOrder);
Call the Pontis SDKβs createSendBTC function as follows. This function takes the scaled BTC amount, fee information, and the keeperβs (recipient) address, and it uses a callback (that internally calls doSignAndBroadcastPsbt) to sign and broadcast the transaction. Once broadcast, it returns a claim (the transaction id):
After you have the txId (claim) from createSendBTC, you create the onβchain order to bridge BTC to sBTC. Use the claim as the bitcoinTxId in your order parameters. For example:
If a parameter is listed in this list, we consider it as an optional parameter needed to be passed along for the specified endpoint. createGroupOrder:
bitcoinTxId or stacksTxId optinal, can be provided for most actions -- depending on the actionType, no transaction needs to be provided (but providing one is still recommended)
fundingTokens: optional, should be used for most actions
minReceived: optional, should be used in most cases
bitcoinAddress: optional
actionFunctionArgs, actionPostConditions, and actionAggregatorTokens: optional -- actionAggregatorTokens is used for almost all swap-related actions. actionFunctionArgs and actionPostConditions are mostly used for actions such as adding liquidity
nextExecutionAfter: optional
priceRange: optional
feeRecipient: optional
createOrder:
Same as above, but includes cancelOrderAfter, which is optional
getGroupOrder:
includeOrders: optional
getOrCreateKeeperContract: Depending on the keeperType, bitcoinAddress is optional but providing it is still recommended
deployContract: optional
allActionsApproved: optional
Troubleshooting
If you encounter any issues while using the Bitflow SDK, please check the following:
Ensure all environment variables are correctly set in your .env file.
Make sure you have the latest version of the SDK installed.
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.