name: bluvo description: | Crypto exchange connectivity API for securely connecting user wallets to exchanges (Binance, Kraken, Coinbase), executing withdrawals, and managing credentials. Use when building exchange integrations, withdrawal UIs with 2FA/SMS/KYC, or multi-tenant crypto applications. SDKs: TypeScript state machine and React hooks. license: MIT compatibility: "TypeScript 4.7+. React 16.8+ (optional). Next.js 13+ App Router (optional). Node.js 18+ for server-side." metadata: mintlify-proj: bluvo author: Bluvo Inc version: "3.1.0" docs: "https://docs.bluvo.dev" sdk-repo: "https://github.com/bluvoinc/sdk"

Bluvo Skill Reference

Product Overview

Bluvo is a crypto exchange connectivity API that securely manages exchange API credentials and enables wallet connections without exposing raw keys. It is not a REST wrapper — a state machine orchestrates the entire flow from OAuth authentication through wallet loading, quote generation, withdrawal execution, and 2FA challenge handling.

Security: AES-256-CBC encryption, tenant-specific encryption keys, dedicated database per organization.

Programming Model

Three Client Tiers

The SDK uses a state machine paradigm: you send events and the machine transitions through states. You do not call REST APIs directly — the BluvoFlowClient orchestrates all API calls internally and emits state changes you subscribe to.

The React SDK (@bluvo/react) wraps the state machine into hooks — useBluvoFlow is the primary hook for most use cases. No context providers needed.

State Diagram

idle ──→ exchanges:loading ──→ exchanges:ready ──→ oauth:waiting / qrcode:waiting
              │                                         │
        exchanges:error                          oauth:processing / qrcode:displaying
                                                        │
                                            oauth:completed ←─ qrcode:scanning
                                                        │
                                                 wallet:loading
                                                        │
                                                 wallet:ready
                                                        │
                                                quote:requesting
                                                        │
                                                 quote:ready ←─ (auto-refresh)
                                                        │
                                               withdraw:processing
                                                  │    │    │
                                        error2FA  │  errorSMS  errorKYC
                                        error2FAMultiStep │ errorBalance
                                                  │
                                  readyToConfirm  │  retrying
                                                  │
                                        withdraw:completed / fatal / blocked

                      CANCEL_FLOW → flow:cancelled (from ANY state)

What You Can Build

• Exchange wallet connection flows (OAuth popup or QR code for Binance Web)
• Withdrawal UIs with real-time quote refresh and fee display
• Multi-step 2FA verification (TOTP, Email, SMS, Face recognition, Security Key/FIDO)
• Wallet dashboards with balance previews
• Server-side credential management and bulk wallet operations
• Multi-tenant SaaS with isolated crypto operations per customer

Choose Your Integration Path

Decision tree:

• React or Next.js? → @bluvo/react (~24 hours)
• Custom UI framework? → BluvoFlowClient from @bluvo/sdk-ts (~5 days)
• Server-only / backend? → BluvoClient from @bluvo/sdk-ts
• Pre-built widget? → @bluvo/widget-react, @bluvo/widget-vanjs, @bluvo/widget-svelte

# React + Next.js
pnpm add @bluvo/react

# TypeScript only
pnpm add @bluvo/sdk-ts

Quickstart — React + Next.js

Server Actions

// app/actions/flowActions.ts
'use server'

import { createClient, createSandboxClient, createDevClient } from "@bluvo/sdk-ts";

function loadBluvoClient() {
    const env = process.env.NEXT_PUBLIC_BLUVO_ENV;
    if (env === 'production') {
        return createClient({
            orgId: process.env.BLUVO_ORG_ID!,
            projectId: process.env.BLUVO_PROJECT_ID!,
            apiKey: process.env.BLUVO_API_KEY!,
        });
    } else if (env === 'staging') {
        return createSandboxClient({
            orgId: process.env.BLUVO_ORG_ID!,
            projectId: process.env.BLUVO_PROJECT_ID!,
            apiKey: process.env.BLUVO_API_KEY!,
        });
    } else {
        return createDevClient({
            orgId: process.env.BLUVO_ORG_ID!,
            projectId: process.env.BLUVO_PROJECT_ID!,
            apiKey: process.env.BLUVO_API_KEY!,
        });
    }
}

// CRITICAL: toPlain() required for Next.js server action serialization
function toPlain<T extends object>(o: T): T {
    return JSON.parse(JSON.stringify(o)) as T;
}

export async function listExchanges(status?: string) {
    return toPlain(await loadBluvoClient().oauth2.listExchanges(status as any));
}

export async function fetchWithdrawableBalances(walletId: string) {
    return toPlain(await loadBluvoClient().wallet.withdrawals.getWithdrawableBalance(walletId));
}

export async function executeWithdrawal(
    walletId: string, idem: string, quoteId: string,
    params?: { twofa?: string | null; emailCode?: string | null; smsCode?: string | null;
               bizNo?: string | null; tag?: string | null; params?: { dryRun?: boolean } | null; }
) {
    return toPlain(await loadBluvoClient().wallet.withdrawals.executeWithdrawal(walletId, idem, quoteId, params ?? {}));
}

For the complete server actions file (including requestQuotation, getWalletById, pingWalletById), load the nextjs-patterns.md sub-skill referenced in the SDK Skill Files section below.

Page Component

// app/home/page.tsx
"use client";  // REQUIRED — hooks are browser-only

import { useBluvoFlow } from "@bluvo/react";
import {
    fetchWithdrawableBalances, listExchanges, executeWithdrawal,
    requestQuotation, getWalletById, pingWalletById
} from '../actions/flowActions';

export default function Home() {
    const flow = useBluvoFlow({
        orgId: process.env.NEXT_PUBLIC_BLUVO_ORG_ID!,
        projectId: process.env.NEXT_PUBLIC_BLUVO_PROJECT_ID!,
        listExchangesFn: listExchanges,
        fetchWithdrawableBalanceFn: fetchWithdrawableBalances,
        requestQuotationFn: requestQuotation,
        executeWithdrawalFn: executeWithdrawal,
        getWalletByIdFn: getWalletById,
        pingWalletByIdFn: pingWalletById,
        options: {
            sandbox: process.env.NEXT_PUBLIC_BLUVO_ENV === 'staging',
            dev: process.env.NEXT_PUBLIC_BLUVO_ENV === 'development',
        },
    });

    // State booleans: flow.isOAuthPending, flow.isWalletReady, flow.isQuoteReady, etc.
    // Actions: flow.startWithdrawalFlow(), flow.requestQuote(), flow.executeWithdrawal()
    // Challenges: flow.requires2FA, flow.requires2FAMultiStep, flow.requiresSMS
    // Terminal: flow.isWithdrawalComplete, flow.isFlowCancelled, flow.hasFatalError
}

Required Setup

Environment Variables

Authentication

Obtain orgId, projectId, and apiKey from the Bluvo Portal API Keys section.

API key scopes must match the operations your server actions perform.

Constraints

• Supported exchanges: Binance, Kraken, Coinbase, and others — verify current list via API or contact help@bluvo.co
• React hooks are browser-only — no SSR support. They use useState, useEffect, WebSocket, and localStorage.
• useBluvoFlow captures options at mount — the client is created in a useState initializer. Changing options after mount has no effect; remount the component to reinitialize.
• API key scopes must match the operation — e.g., withdrawal scope required for executeWithdrawal
• Withdrawal quotes expire — always get a fresh quote before executing. autoRefreshQuotation defaults to true.

Common Workflows

1. OAuth → Withdrawal (happy path)

idle → exchanges:ready → oauth:completed → wallet:ready → quote:ready → withdraw:completed

Call listExchanges() → user selects exchange → startWithdrawalFlow({ exchange, walletId }) → OAuth popup → wallet loads → requestQuote({...}) → executeWithdrawal(quoteId) → done.

2. QR Code (binance-web)

Auto-detected by startWithdrawalFlow() when exchange === 'binance-web'. No manual routing needed.

qrcode:waiting → qrcode:displaying → qrcode:scanning → oauth:completed → wallet:ready → ...

Display flow.qrCodeUrl as a QR image. Monitor flow.isQRCodeScanning and flow.isOAuthComplete.

3. Wallet Resume

Skip OAuth if wallet already connected:

• resumeWithdrawalFlow({ exchange, walletId }) — skips OAuth, loads wallet balance
• silentResumeWithdrawalFlow({ walletId, exchange, preloadedBalances? }) — jumps directly to wallet:ready

startWithdrawalFlow automatically detects existing wallets via getWalletByIdFn and routes to resume.

4. 2FA Handling

Single-step: flow.requires2FA → flow.submit2FA(code) → withdraw:completed

Multi-step (e.g., Binance GOOGLE + EMAIL + FACE + SMS + ROAMING_FIDO):

1. flow.requires2FAMultiStep — check flow.multiStep2FASteps for required steps
2. flow.submit2FAMultiStep('GOOGLE', code) — submit each code-based step
3. flow.pollFaceVerification() — for FACE steps (10s delay, then 5s polling)
4. flow.pollRoamingFidoVerification() — for ROAMING_FIDO steps (immediate 5s polling)
5. When flow.isReadyToConfirm → flow.confirmWithdrawal() → withdraw:completed

Use flow.mfaVerified (not step.status) as the primary source of truth for verification state.

When Things Go Wrong

1. toPlain() required for every Next.js server action return — without it: "Classes or null prototypes are not supported" serialization error.
2. Invalid state transitions are silent no-ops — check getState().type to verify a transition happened.
3. WITHDRAWAL_DRY_RUN_COMPLETE is a success signal, not an error — it means all multi-step 2FA steps are verified. The SDK transitions to withdraw:readyToConfirm.
4. mfa.verified is primary truth for multi-step 2FA — not step.status. The backend updates mfa.verified.
5. "use client" required on all components using hooks — Next.js App Router requirement.
6. QR code flow auto-detected for binance-web — don't route manually; startWithdrawalFlow handles it.
7. autoRefreshQuotation defaults to true — set false if you want a manual "expired" UI with flow.isQuoteExpired.
8. Never log API keys — Bluvo never logs key material; ensure your code doesn't either.
9. OAuth window close detection has ~500ms polling delay — slight lag between popup close and oauth:window_closed_by_user.

SDK Skill Files — Conditional Loading Triggers

The SDK has detailed skill files for deep implementation guidance. Load these on demand based on what you're building.

@bluvo/react (React Hooks)

Load when: Building React or Next.js withdrawal UIs.

Main skill: https://raw.githubusercontent.com/bluvoinc/sdk/main/packages/react/skill/SKILL.md

@bluvo/sdk-ts (Core TypeScript)

Load when: Building non-React frontends, server-side integrations, or need state machine internals.

Main skill: https://raw.githubusercontent.com/bluvoinc/sdk/main/packages/ts/skill/SKILL.md

Documentation Index

Verification Checklist

Before submitting work with Bluvo:

• useBluvoFlow or BluvoFlowClient initialized with all 6 callback functions
• Server actions wrapped with toPlain()
• Client components marked with "use client"
• Error/challenge states handled (oauth:error, withdraw:error2FA, withdraw:fatal, etc.)
• Terminal states handled (withdraw:completed, flow:cancelled, withdraw:blocked)
• API key has correct scopes for the operation
• Sensitive credentials never logged or exposed