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.

All Bitflow API endpoints are publicly accessible without an API key. Unauthenticated requests are subject to a default rate limit of 500 requests per minute per IP.

If your integration requires higher limits, see the Rate Limit Request section to email [email protected] with a pre-filled form. You can also reach the team on Discord.

Table of Contents

• Installation
• Usage
  • Environment Variables
• 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)
• Types
• Troubleshooting
• Rate Limit Request
• License

Installation

Install the Bitflow SDK using npm:

npm install @bitflowlabs/core-sdk

Usage

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

1. Import the SDK:

import { BitflowSDK } from '@bitflowlabs/core-sdk';

2. Initialize the SDK:

The SDK can be instantiated with no arguments. Built-in defaults are used for all host URLs, so only provide overrides when necessary. See the Environment Variables section for all available options.

// Zero-config — uses built-in defaults for all host URLs.
const bitflow = new BitflowSDK();

// Override individual values as needed.
const bitflow = new BitflowSDK({
  BITFLOW_PROVIDER_ADDRESS: string, // optional
  BITFLOW_API_KEY: string, // optional
  BITFLOW_API_HOST: string,     // optional, default: https://bitflowsdk-api-test-7owjsmt8.uk.gateway.dev
  READONLY_CALL_API_HOST: string, // optional, default: https://node.bitflowapis.finance
  READONLY_CALL_API_KEY: string, // optional
  KEEPER_API_HOST: string,      // optional, default: https://bitflow-keeper-test-7owjsmt8.uc.gateway.dev
  KEEPER_API_KEY: string, // optional
});

3. Use the SDK methods to interact with the Bitflow Protocol. See the Available Functions section for more details.

Environment Variables

All configuration has built-in defaults — no environment variables are required to get started.

When an environment variable is set it takes precedence over the built-in default. Constructor options passed directly to new BitflowSDK({ ... }) take the highest precedence.

To override via environment variables, create a .env file in your project root:

# Override host URLs only if you need to point at a different environment
BITFLOW_API_HOST=https://bitflowsdk-api-test-7owjsmt8.uk.gateway.dev
READONLY_CALL_API_HOST=https://node.bitflowapis.finance
KEEPER_API_HOST=https://bitflow-keeper-test-7owjsmt8.uc.gateway.dev

# Optional: API keys for higher rate limits (see Rate Limit Request section below)
BITFLOW_API_KEY=<your_api_key_here>
READONLY_CALL_API_KEY=<your_readonly_api_key_here>
KEEPER_API_KEY=<your_keeper_api_key_here>

# Optional: your Stacks provider address
BITFLOW_PROVIDER_ADDRESS=<your_provider_address_here>

Next.js NEXT_PUBLIC_ prefixed variants are also supported for all variables above (e.g. NEXT_PUBLIC_BITFLOW_API_HOST).

Available Functions

Get Available Tokens

Retrieve a list of all available tokens:

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

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);

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);

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);

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);

Getting Swap Parameters

Get the necessary parameters for signing 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%

const swapParams = await bitflow.getSwapParams(
  swapExecutionData,
  senderAddress,
  slippageTolerance
);
console.log(swapParams); // Use this parameters to build your swap transaction

Executing Swap (uses @stacks/connect)

This function uses the @stacks/connect library to 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')
);

Types

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

• BitflowSDKConfig: Represents the configuration object for the Bitflow SDK.
• Token: Represents a token with its properties.
• SwapOptions: Represents possible swap options for a token.
• PostConditionType: Represents the type of a post-condition used in transactions.
• SelectedSwapRoute: Represents a selected swap route with its details.
• RouteQuote: Represents the quote for a swap route.
• QuoteResult: Represents the result of a quote request, including the best RouteQuote and all possible routes.
• SwapExecutionData: Represents the data needed to execute a swap.
• SwapDataParamsAndPostConditions: Represents the parameters and post-conditions needed to execute/sign a swap transaction.

import {
  Token,
  SwapOptions,
  SelectedSwapRoute,
  QuoteResult,
  SwapExecutionData,
  SwapDataParamsAndPostConditions,
} from '@bitflowlabs/core-sdk';

Troubleshooting

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

1. Make sure you have the latest version of the SDK installed.
2. Check that you're using a valid Stacks address for the senderAddress parameter.
3. If you're overriding host URLs via environment variables, ensure they are correctly set in your .env file.

Rate Limit Request

If your integration needs more than 500 requests per minute per IP, click the link below to open a pre-filled email in your mail client:

Request higher rate limits

If the link doesn't open your mail client, email [email protected] with the subject API Rate Limit Increase Request and include the following:

• Project / Application name — e.g. MyDeFi App
• Brief description — What your app does and how it uses the Bitflow API
• Website / repo (if public) — URL or N/A
• APIs you need higher limits for — Core API, Keeper API, Stacks Node (or all)
• Expected request volume — e.g. ~2,000 requests/minute during peak hours
• Use case — e.g. Server-side data aggregation, real-time price feeds for N users
• Contact name
• Discord handle (optional)

We aim to respond within 2 business days. For urgent requests, reach out on Discord.

License

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