# @bluvo/sdk-ts 中文文档

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

版本：5\.0\.0
npm 元数据更新时间：2026-05-04T19:56:43.412Z
中文译文更新时间：2026-11-08T09:10:31.047Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.8 MB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-04-16T14:16:10.630Z
- 最新版本发布：2026-05-04T19:56:43.289Z
- 近 30 天下载量：133284（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：66（近 12 个月 11 个）

## 中文简介

类型脚本的 Bluvo SDK

## 安装

```sh
npm install @bluvo/sdk-ts
```

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

## README

# Bluvo 类型脚本 SDK

[![npm version](https://img.shields.io/npm/v/@bluvo/sdk-ts.svg)](https://www.npmjs.com/package/@bluvo/sdk-ts) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

正式类型SDK [模糊 API](https://docs.bluvo.co/) - 通过OAuth2对用户进行安全认证,并进行安全、可审计地从加密货币交换中提取.

## 特征

-   **OAuth2 认证**: 通过 OAuth2 流安全连接用户 CEX 账户
-   **安全提取**: 充分透明地请求报价和执行撤回
-   **双 SDK 架构**: 用于安全的分离浏览器和服务器 SDK
-   **多交换支持**:Coinbase、Kraken、Binance、KuCoin、OKX、Bitmart、双子座等
-   **类型安全**: 所有 API 响应的完整类型脚本支持
-   **QR 代码缓存**: Persist QR 代码认证会话跨页面刷新( 0 配置, 默认本地Storage)

## 安装

```bash
# Using npm
npm install @bluvo/sdk-ts

# Using yarn
yarn add @bluvo/sdk-ts

# Using pnpm
pnpm add @bluvo/sdk-ts
```

## 概览:OAuth2 – 撤回流量

Bluvo 允许安全流, 以 CEX 账户认证用户并进行提取:

1.  **OAuth2 认证** (浏览器):用户通过OAuth2弹出连接他们的CEX账户
2.  **获取可撤销余额** (服务器):查询现有资产和支持的网络
3.  **请求引号** (服务员):获得定价取款指示
4.  **执行退出** (服务员):完成提款交易

## 快速启动

### Web 客户端 SDK (浏览器)

在 React-based UIs 中用于安全处理 OAuth2 流. 从不在此嵌入服务器机密.

```typescript
import { createWebClient } from "@bluvo/sdk-ts";

const webClient = createWebClient({ 
  orgId: "your-org-id",      // Get from https://portal.bluvo.co
  projectId: "your-project-id" 
});
```

### 服务器 SDK (备份)

在信任的服务器上使用特权操作 。 安全存储 API 密钥 .

```typescript
import { createClient } from "@bluvo/sdk-ts";

const client = createClient({ 
  orgId: "your-org-id",
  projectId: "your-project-id",
  apiKey: process.env.BLUVO_API_KEY  // Store securely!
});
```

## OAuth2 CEX 认证

### 1\. 打开 OAuth2 弹出(浏览器)

```typescript
import { randomUUID } from 'crypto';

// Open OAuth2 popup for user authentication
await webClient.oauth2.openWindow(
  "coinbase", // or: kraken, gemini, binance, okx, bitmart, kucoin
  {
    walletId: randomUUID(), // Unique identifier for this wallet
    idem: randomUUID(),     // Idempotency key for this auth attempt
  },
  {
    onWindowClose: () => {
      console.log("OAuth2 window was closed by user");
    },
  }
);
```

### 2\. 听取补全 (浏览器)

```typescript
// Subscribe to OAuth2 completion event
await webClient.listen(
  idem, // Same UUID from openWindow
  SUBSCRIBE_ONLY_PUBLIC_TOKEN, // Ask Bluvo team for this token
  {
    onMessage: ({ walletId }) => {
      console.log("CEX account connected with ID:", walletId);
      
      // Store walletId for future operations
      // e.g., saveUserWallet(currentUser, walletId);
    },
    onError: (error) => {
      console.error("OAuth2 failed:", error);
    }
  }
);
```

## 流动

一旦你有一个 `walletId` 从OAuth2中退出,分三个步骤:

### 1\. 获得可收回余额(服务器)

```typescript
const { balances } = await client
  .wallet
  .withdrawals
  .getWithdrawableBalance(walletId);

// Response structure:
// {
//   balances: [{
//     asset: "BTC",
//     amount: 0.05,
//     networks: [{
//       id: "bitcoin",
//       code: "bitcoin",
//       name: "bitcoin",
//       displayName: "Bitcoin",
//       minWithdrawal: "0.0001",
//       maxWithdrawal: "10",
//       assetName: "BTC",
//       addressRegex: "^(bc1|[13])[a-zA-HJ-NP-Z0-9]{25,62}$"
//     }]
//   }]
// }
```

### 2\. 申请引文(公务员)

获得一个寿命短,价格高的取出指令:

```typescript
const quote = await client
  .wallet
  .withdrawals
  .requestQuotation(walletId, {
    asset: "BTC",
    amount: "0.05",
    address: "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
    network: "bitcoin",      // Optional, defaults to address type
    tag: null,              // For assets requiring memo/tag
    includeFee: true        // Include network fee in amount
  });

// Response:
// {
//   id: "quote_01H9X3Z7N5V2KJ4G8P6QR5T3Y2",
//   asset: "BTC",
//   amountWithFee: 0.0502,
//   amountNoFee: 0.05,
//   destinationAddress: "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
//   network: "bitcoin",
//   estimatedFee: 0.0002,
//   estimatedTotal: 0.0502,
//   expiresAt: 1713984000  // UNIX timestamp
// }
```

### 3\. 执行退出(公务员)

使用引文执行撤回:

```typescript
const withdrawal = await client
  .wallet
  .withdrawals
  .executeQuotation(walletId, quote.id, {
    idem: randomUUID() // For safe retries
  });

// Response:
// {
//   transactionId: "tx_01H9X3Z7N5V2KJ4G8P6QR5T3Y2",
//   status: "pending",
//   asset: "BTC",
//   amount: 0.05,
//   network: "bitcoin",
//   destinationAddress: "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
//   fee: 0.0002,
//   total: 0.0502
// }
```

## QR 代码认证和缓存

一些交换机(如Binance)使用QR代码扫描来代替OAuth2弹出. SDK 自动处理此操作——当检测出一个 QR 代码流时, 您会收到 `qrCodeUrl` 财务报告和审定财务报表 `qrCodeExpiresAt` 在流动状态.

### 零配置缓存

QR 代码会话被缓存于 `localStorage` 默认情况下,用户可以在页面刷新时立即看到其QR代码,而无需重新请求. 不需要设置.

### 缓存选项

过 `cache` 创建时 `BluvoFlowClient` 或经由 `useBluvoFlow()`数字 :

```typescript
import { BluvoFlowClient } from "@bluvo/sdk-ts";

const flow = new BluvoFlowClient({
  // ...other options
  cache: {
    adapter: {          // Custom storage adapter (default: localStorage)
      get: (key) => sessionStorage.getItem(key),
      set: (key, val) => sessionStorage.setItem(key, val),
      remove: (key) => sessionStorage.removeItem(key),
    },
    prefix: "myapp:",   // Key prefix (default: "bluvo:")
    minRemainingLifetimeSec: 30, // Ignore cached QR codes expiring within N seconds (default: 15)
    disabled: false,     // Set true to disable caching entirely
  },
});
```

要完全禁用缓存 :

```typescript
cache: { disabled: true }
```

**导出类型 :** `BluvoCacheOptions`, (中文(简体) ), `BluvoCacheAdapter`, (中文(简体) ), `BluvoCache`

## 安保最佳做法

1.  **API 密钥管理**: 保留 `BLUVO_API_KEY` 严格服务器侧。 使用环境变量或机密管理器.
    
2.  **地址验证**: 使用网络 `addressRegex` 用于客户端验证。 API也会验证.
    
3.  **目 录**: 使用独有 `idem` 用于所有关键操作的密钥,以使重试安全.
    
4.  **引用管理**数字 :
    
    -   将引文视为不可改变和短命
    -   向用户显示过期时间
    -   输入更改或引文过期时请求新引文
5.  **处理错误**: 表面可操作信息并提供干净的再试路径.
    
6.  **数据持久性**: 存储 `walletId` 安全地针对您的用户配置文件进行所有未来的操作.
    

## 业务建议

-   **OAuth2 流量**: 生成新鲜 `idem` 每次尝试
-   **透明度**: 显示费用细目并引用过期时间
-   **观察性**页:1 `walletId`引用 `id`,以及 `idem` 用于追踪
-   **无托肯管理**: Bluvo 处理访问令牌刷新并自动平衡同步

## 支持的交换

目前支持 OAuth 2:

-   监狱
-   克劳肯
-   双子座
-   二进制
-   OKX 单曲
-   位点
-   库币

## 相关项目

-   [主页](https://bluvo.co/) - Bluvo主页
-   [API 文档](https://docs.bluvo.co/) - 完整的API参考文献
-   [管理板](https://portal.bluvo.co/) - 把证件拿来

## 许可证

[麻省理工学院](https://npmcn.com/package/%40bluvo/sdk-ts/LICENSE) 布卢沃公司.

## 常见问题

### @bluvo/sdk-ts 是什么？

类型脚本的 Bluvo SDK

### 如何安装 @bluvo/sdk-ts？

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

### @bluvo/sdk-ts 支持 TypeScript 吗？

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

### @bluvo/sdk-ts 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @bluvo/sdk-ts 可以商用吗？

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

### @bluvo/sdk-ts 的下载量有多少？

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

### @bluvo/sdk-ts 还在维护吗？

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