# Bitflow SDK

## 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](#rate-limit-request) section to email **<help@bitflow.finance>** with a pre-filled form. You can also reach the team on [Discord](https://discord.gg/DY4yNyHyhT).

## Table of Contents

* [Installation](#installation)
* [Usage](#usage)
  * [Environment Variables](#environment-variables)
* [Available Functions](#available-functions)
  * [Get Available Tokens](#get-available-tokens)
  * [Get Possible Swaps](#get-possible-swaps)
  * [Get All Possible Token Y](#get-all-possible-token-y)
  * [Get All Possible Token Y Routes](#get-all-possible-token-y-routes)
  * [Getting Quote for Route](#getting-quote-for-route)
  * [Getting Swap Parameters](#getting-swap-parameters)
  * [Executing Swap (uses `@stacks/connect`)](#executing-swap-uses-stacks-connect)
* [Types](#types)
* [Troubleshooting](#troubleshooting)
* [Rate Limit Request](#rate-limit-request)
* [License](#license)

## Installation

Install the Bitflow SDK using npm:

```bash
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:

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

2. Initialize the SDK:

If no parameters are provided, the SDK will use the environment variables. See the [Environment Variables](#environment-variables) section for more details.

```ts
// API keys are optional — omit them to use the default public rate limits.
const bitflow = new BitflowSDK({
  BITFLOW_API_HOST: 'https://bitflowsdk-api-test-7owjsmt8.uk.gateway.dev',
  // optional: BITFLOW_API_KEY: string,
  BITFLOW_PROVIDER_ADDRESS: string,
  READONLY_CALL_API_HOST: 'https://node.bitflowapis.finance',
  // optional: READONLY_CALL_API_KEY: string,
  KEEPER_API_HOST: 'https://bitflow-keeper-test-7owjsmt8.uc.gateway.dev',
  // optional: KEEPER_API_KEY: string,
});
```

3. Use the SDK methods to interact with the Bitflow Protocol. See the [Available Functions](#available-functions) section for more details.

### Environment Variables

If no options are provided when initializing the SDK, it will use the environment variables.

Create a `.env` file in your project root with the following variables:

```bash
# Bitflow Core API — publicly accessible, no key required
BITFLOW_API_HOST=https://bitflowsdk-api-test-7owjsmt8.uk.gateway.dev
# Optional: API key for higher rate limits (see Rate Limit Request section below)
BITFLOW_API_KEY=<your_api_key_here>

# Your provider address
BITFLOW_PROVIDER_ADDRESS=<your_provider_address_here>

# Stacks Node — publicly accessible, no key required
READONLY_CALL_API_HOST=https://node.bitflowapis.finance
# Optional: API key for higher rate limits
READONLY_CALL_API_KEY=<your_readonly_api_key_here>

# Keeper API — publicly accessible, no key required
KEEPER_API_HOST=https://bitflow-keeper-test-7owjsmt8.uc.gateway.dev
# Optional: API key for higher rate limits
KEEPER_API_KEY=<your_keeper_api_key_here>
```

## Available Functions

### Get Available Tokens

Retrieve a list of all available tokens:

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

### Get Possible Swaps

Get all possible swap options for a given token:

```ts
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:

```ts
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:

```ts
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:

```ts
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:

```ts
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:

```ts
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.

```ts
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. 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.

## 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**](mailto:help@bitflow.finance?subject=API%20Rate%20Limit%20Increase%20Request%20-%20%5BYour%20Project%20Name%5D\&body=Hi%20Bitflow%20team%2C%0D%0A%0D%0AI%27m%20integrating%20the%20Bitflow%20SDK%20and%20would%20like%20to%20request%20an%20API%20key%20with%20increased%20rate%20limits.%0D%0A%0D%0AProject%20%2F%20Application%20name%3A%20%5Be.g.%20MyDeFi%20App%5D%0D%0ABrief%20description%3A%20%5BWhat%20your%20app%20does%20and%20how%20it%20uses%20the%20Bitflow%20API%5D%0D%0AWebsite%20%2F%20repo%20%28if%20public%29%3A%20%5BURL%20or%20N%2FA%5D%0D%0A%0D%0AAPIs%20I%20need%20higher%20limits%20for%20%28delete%20as%20applicable%29%3A%0D%0A-%20Bitflow%20Core%20API%20%28bitflow-sdk-api-gateway-7owjsmt8.uc.gateway.dev%29%0D%0A-%20Keeper%20API%20%28bitflow-keeper-7owjsmt8.uc.gateway.dev%29%0D%0A-%20Stacks%20Node%20%28node.bitflowapis.finance%29%0D%0A%0D%0AExpected%20request%20volume%3A%20%5Be.g.%20~2%2C000%20requests%2Fminute%20during%20peak%20hours%5D%0D%0A%0D%0AUse%20case%3A%20%5Be.g.%20Server-side%20data%20aggregation%2C%20real-time%20price%20feeds%20for%20N%20users%5D%0D%0A%0D%0AContact%20name%3A%20%5BYour%20name%5D%0D%0ADiscord%20handle%20%28optional%29%3A%20%5Be.g.%20%40yourhandle%5D%0D%0A%0D%0AThanks!)

> If the link doesn't open your mail client, email **<help@bitflow.finance>** 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](https://discord.gg/DY4yNyHyhT).

## License

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