Bluvo TypeScript SDK

Official TypeScript SDK for the Bluvo API - Securely authenticate users via OAuth2 and perform safe, auditable withdrawals from cryptocurrency exchanges.

Features

• OAuth2 Authentication: Connect user CEX accounts securely via OAuth2 flow
• Safe Withdrawals: Request quotations and execute withdrawals with full transparency
• Dual SDK Architecture: Separate browser and server SDKs for security
• Multi-Exchange Support: Coinbase, Kraken, Binance, KuCoin, OKX, Bitmart, Gemini and more
• Type Safety: Full TypeScript support with proper types for all API responses
• QR Code Caching: Persist QR code auth sessions across page refreshes (zero config, localStorage by default)

Installation

# Using npm
npm install @bluvo/sdk-ts

# Using yarn
yarn add @bluvo/sdk-ts

# Using pnpm
pnpm add @bluvo/sdk-ts

Overview: OAuth2 → Withdraw Flow

Bluvo enables a secure flow to authenticate users with their CEX accounts and perform withdrawals:

1. OAuth2 Authentication (Browser): User connects their CEX account via OAuth2 popup
2. Get Withdrawable Balance (Server): Query available assets and supported networks
3. Request Quotation (Server): Get a priced withdrawal instruction
4. Execute Withdrawal (Server): Complete the withdrawal transaction

Quick Start

Web Client SDK (Browser)

Use in React-based UIs to handle OAuth2 flows securely. Never embed server secrets here.

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

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

Server SDK (Backend)

Use on trusted servers for privileged operations. Store API key securely.

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 Authentication

1. Open OAuth2 Popup (Browser)

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. Listen for Completion (Browser)

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

Withdrawal Flow

Once you have a walletId from OAuth2, perform withdrawals in three steps:

1. Get Withdrawable Balance (Server)

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. Request Quotation (Server)

Get a short-lived, priced withdrawal instruction:

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. Execute Withdrawal (Server)

Execute the withdrawal using the quotation:

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 Code Authentication & Caching

Some exchanges (e.g., Binance) use QR code scanning instead of an OAuth2 popup. The SDK handles this automatically — when a QR code flow is detected, you receive qrCodeUrl and qrCodeExpiresAt in the flow state.

Zero-Config Caching

QR code sessions are cached in localStorage by default, so users see their QR code instantly on page refresh without re-requesting it. No setup required.

Cache Options

Pass cache when creating a BluvoFlowClient or via 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
  },
});

To disable caching entirely:

cache: { disabled: true }

Exported types: BluvoCacheOptions, BluvoCacheAdapter, BluvoCache

Security Best Practices

1. API Key Management: Keep BLUVO_API_KEY strictly server-side. Use environment variables or secrets managers.

2. Address Validation: Use the network's addressRegex for client-side validation. The API will also validate.

3. Idempotency: Use unique idem keys for all critical operations to make retries safe.

4. Quote Management:

   • Treat quotes as immutable and short-lived
   • Display expiry time to users
   • Request new quotes if inputs change or quotes expire

5. Error Handling: Surface actionable messages and provide clean retry paths.

6. Data Persistence: Store the walletId securely against your user profile for all future operations.

Operational Recommendations

• OAuth2 Flow: Generate fresh idem for each attempt
• Transparency: Show fee breakdowns and quote expiry times
• Observability: Log walletId, quote id, and idem for traceability
• No Token Management: Bluvo handles access token refresh and balance sync automatically

Supported Exchanges

Currently supported for OAuth2:

• Coinbase
• Kraken
• Gemini
• Binance
• OKX
• Bitmart
• KuCoin

Related Projects

• Home Page - Bluvo Home Page
• API Documentation - Complete API reference
• Admin Dashboard - Get your credentials here

License

MIT © Bluvo Inc.