Bluvo 类型脚本 SDK

正式类型SDK 模糊 API - 通过OAuth2对用户进行安全认证,并进行安全、可审计地从加密货币交换中提取.

特征

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

安装

# 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 流. 从不在此嵌入服务器机密.

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 密钥 .

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 弹出(浏览器)

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. 听取补全 (浏览器)

// 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. 获得可收回余额(服务器)

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. 申请引文(公务员)

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

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. 执行退出(公务员)

使用引文执行撤回:

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()数字 :

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

要完全禁用缓存 :

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 单曲
• 位点
• 库币

相关项目

• 主页 - Bluvo主页
• API 文档 - 完整的API参考文献
• 管理板 - 把证件拿来

许可证

麻省理工学院 布卢沃公司.