# @bitflowlabs/core-sdk 中文文档

规范地址：https://npmcn.com/package/%40bitflowlabs/core-sdk/

版本：4\.2\.0
npm 元数据更新时间：2026-08-19T19:28:13.449Z
中文译文更新时间：2026-11-08T04:30:44.294Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bitflowlabs/core-sdk
原文对照：https://npmcn.com/package/%40bitflowlabs/core-sdk/?lang=original
项目主页：https://github.com/BitflowFinance/bitflow-sdk#readme
源码仓库：https://github.com/BitflowFinance/bitflow-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：672 kB，131 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：4 个
- 首次发布：2024-10-04T16:41:27.715Z
- 最新版本发布：2026-08-19T19:28:13.268Z
- 近 30 天下载量：4880（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 10 个）

## 中文简介

用于与 Bitflow 协议交互的 SDK

## 安装

```sh
npm install @bitflowlabs/core-sdk
```

也可以使用：`pnpm add @bitflowlabs/core-sdk`、`yarn add @bitflowlabs/core-sdk`、`bun add @bitflowlabs/core-sdk`

## README

# 位流 SDK

Bitflow SDK是一个与Bitflow协议互动的强大而易于使用的库. 它为将Bitflow功能无缝地集成到您的应用程序提供了一套工具.

所有 Bitflow API 端点为 **没有 API 密钥可公开访问**. 未认证的请求受默认费率限制: **每个实施伙伴每分钟500个请求**。 。 。 .

如果您的整合需要更高的限制,请查看 [限速请求](https://npmcn.com/package/%40bitflowlabs/core-sdk/#readme-rate-limit-request) 区域改为电子邮件 **[帮助@ bitflow. finance](mailto:help@bitflow.finance)** 带有预填表. 你也可以联系团队 [解析器](https://discord.gg/DY4yNyHyhT)。 。 。 .

# 目录

-   [安装](https://npmcn.com/package/%40bitflowlabs/core-sdk/#readme-installation)
-   [使用量](https://npmcn.com/package/%40bitflowlabs/core-sdk/#readme-usage)
    -   [环境变量](https://npmcn.com/package/%40bitflowlabs/core-sdk/#readme-environment-variables)
-   [可用函数](https://npmcn.com/package/%40bitflowlabs/core-sdk/#readme-available-functions)
    -   [获取可用的托肯](https://npmcn.com/package/%40bitflowlabs/core-sdk/#readme-get-available-tokens)
    -   [获取可能的交换](https://npmcn.com/package/%40bitflowlabs/core-sdk/#readme-get-possible-swaps)
    -   [获取全部可能的托肯 Y](https://npmcn.com/package/%40bitflowlabs/core-sdk/#readme-get-all-possible-token-y)
    -   [获取所有可能的托肯 Y 路由](https://npmcn.com/package/%40bitflowlabs/core-sdk/#readme-get-all-possible-token-y-routes)
    -   [获取路由引用](https://npmcn.com/package/%40bitflowlabs/core-sdk/#readme-getting-quote-for-route)
    -   [获取交换参数](https://npmcn.com/package/%40bitflowlabs/core-sdk/#readme-getting-swap-parameters)
    -   [执行交换( 使用) `@stacks/connect`(中文(简体) )](https://npmcn.com/package/%40bitflowlabs/core-sdk/#readme-executing-swap-uses-stacksconnect)
-   [类型](https://npmcn.com/package/%40bitflowlabs/core-sdk/#readme-types)
-   [解决问题](https://npmcn.com/package/%40bitflowlabs/core-sdk/#readme-troubleshooting)
-   [限速请求](https://npmcn.com/package/%40bitflowlabs/core-sdk/#readme-rate-limit-request)
-   [许可证](https://npmcn.com/package/%40bitflowlabs/core-sdk/#readme-license)

# 安装

使用 npm 安装 Bitflow SDK :

```bash
npm install @bitflowlabs/core-sdk
```

# 使用量

以下是在您项目中执行 Bitflow SDK 的分步指南 :

1.  导入 SDK :

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

2.  初始化 SDK :

SDK可以在没有论据的情况下被即时化. 内建默认用于所有主机URL,因此仅在必要时提供覆盖. 见 [环境变量](https://npmcn.com/package/%40bitflowlabs/core-sdk/#readme-environment-variables) 用于所有可用选项的段落.

```ts
// 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.  使用 SDK 方法与 Bitflow 协议交互. 见 [可用函数](https://npmcn.com/package/%40bitflowlabs/core-sdk/#readme-available-functions) 详细情况.

## 环境变量

所有配置都有内置默认——不需要环境变量启动.

当设定环境变量时,它优先于内置默认值。 直接传递到 `new BitflowSDK({ ... })` 以最高优先.

| 变量 | 默认 |
| --- | --- |
| `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` |
| `BITFLOW_API_KEY` | _(无——适用公共费率限额)_ |
| `READONLY_CALL_API_KEY` | _(无——适用公共费率限额)_ |
| `KEEPER_API_KEY` | _(无——适用公共费率限额)_ |
| `BITFLOW_PROVIDER_ADDRESS` | _(无)_ |

要通过环境变量覆盖,请创建 `.env` 在工程根中的文件 :

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

下一个.js `NEXT_PUBLIC_` 对以上所有变量(如:. `NEXT_PUBLIC_BITFLOW_API_HOST`) (中文(简体) ).

# 可用函数

## 获取可用的托肯

获取所有可用的令牌列表 :

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

## 获取可能的交换

为给定的符号获取所有可能的交换选项 :

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

## 获取全部可能的托肯 Y

获取所有可以交换给给定的符号 :

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

## 获取所有可能的托肯 Y 路由

获得所有可能的路由, 在两个符号之间互换:

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

## 获取路由引用

取出引文来交换两个符号:

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

## 获取交换参数

获取签署互换交易的必要参数 :

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

## 执行交换( 使用) `@stacks/connect`(中文(简体) )

此函数使用 `@stacks/connect` 执行互换交易的库 :

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

# 类型

SDK 导出几种可以在应用程序中使用的类型脚本 :

-   **位流SDKconfig :** 代表 Bitflow SDK 的配置对象.
-   **键 :** 代表着它的属性.
-   **交换选项 :** 表示一个符号的可能交换选项 .
-   **附加条件类型 :** 表示交易中使用的后条件类型.
-   **选中的分页路由 :** 代表带有其细节的选定互换路径 .
-   **路由引用 :** 代表一个互换路线的引文.
-   **出引经曰:** 引用请求的结果,包括 `RouteQuote` 以及所有可能的路线.
-   **换出数据 :** 表示执行互换所需的数据.
-   **交换DataParamsAnd 条件 :** 表示执行/签署互换交易所需的参数和条件.

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

# 解决问题

如果您在使用 Bitflow SDK 时遇到任何问题, 请检查以下 :

1.  确保您安装了 SDK 的最新版本 .
2.  请检查date=中的日期值 (帮助) 发送方Address参数使用有效的 Stacks 地址.
3.  如果您通过环境变量压倒了主机URL, 请确保它们正确设置在您的 `.env` 文档.

# 限速请求

如果您的整合需求超过 **每个实施伙伴每分钟500个请求**,单击下面的链接在您的邮件客户端中打开一个预填邮件:

**[要求提高费率限额](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!)**

> 如果链接不打开您的邮件客户端, 电子邮件 **[帮助@ bitflow. finance](mailto:help@bitflow.finance)** 主题 `API Rate Limit Increase Request` 并包括以下内容:

-   **项目/ 应用程序名称** -例如 MyDeFi 应用程序
-   **简要说明** ——您的应用程序做什么以及如何使用 Bitflow API
-   **网站/检索(如果公开)** —— URL或无编号/A
-   **API 需要更高的限制** — Core API, 守护者 API, Stacks 节点( 或全部)
-   **预期请求量** - 例如,高峰时段2 000个请求/分钟
-   **使用大小写** ——例如服务器侧数据汇总,为N用户提供实时价格信息
-   **联系人名称**
-   **Discord 手柄** (可选)

我们的目标是在两个工作日内作出反应。 对于紧急请求,请联系 [解析器](https://discord.gg/DY4yNyHyhT)。 。 。 .

# 许可证

这个项目根据麻省理工学院许可证获得许可----详情见LICENSE文件.

## 常见问题

### @bitflowlabs/core-sdk 是什么？

用于与 Bitflow 协议交互的 SDK

### 如何安装 @bitflowlabs/core-sdk？

在项目目录运行 npm install @bitflowlabs/core-sdk，或使用 pnpm add / yarn add / bun add。

### @bitflowlabs/core-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bitflowlabs/core-sdk 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @bitflowlabs/core-sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @bitflowlabs/core-sdk 可以商用吗？

@bitflowlabs/core-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bitflowlabs/core-sdk 的下载量有多少？

根据 npm 官方下载统计，@bitflowlabs/core-sdk 在 2026/10/08 – 2026/11/06 这 30 天内被下载 4,880 次，日均约 163 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bitflowlabs/core-sdk 还在维护吗？

最新版本 4\.2\.0 发布于 2026/08/20（2 个月前）；至今共发布 26 个版本，其中过去 12 个月发布了 10 个；首次发布于 2024/10/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。