@bluvo/react

React hooks for the Bluvo SDK - providing a framework-agnostic, event-driven state machine for cryptocurrency withdrawal flows.

Installation

npm install @bluvo/react @bluvo/sdk-ts
# or
pnpm add @bluvo/react @bluvo/sdk-ts
# or
yarn add @bluvo/react @bluvo/sdk-ts

Quick Start

import React from 'react';
import { useBluvoFlow } from '@bluvo/react';

function WithdrawalComponent() {
    const flow = useBluvoFlow({
        orgId: "bluvo-org-id",
        projectId: "bluvo-project-id", // <- deprecated soon to be removed

        fetchWithdrawableBalanceFn: fetchWithdrawableBalances,
        requestQuotationFn: requestQuotation,
        executeWithdrawalFn: executeWithdrawal,

        onWalletConnectedFn: (walletId, exchange) => {
            // call server action store this walletId for the currently-logged in user
        }
    });

  const handleStart = () => {
    flow.startWithdrawalFlow({
      exchange: 'coinbase',
      walletId: 'wallet-123',
      asset: 'BTC',
      amount: '0.001',
      destinationAddress: 'bc1q...'
    });
  };

  if (flow.requires2FA) {
    return (
      <div>
        <input 
          placeholder="Enter 2FA code"
          onKeyPress={(e) => {
            if (e.key === 'Enter') {
              flow.submit2FA(e.target.value);
            }
          }}
        />
      </div>
    );
  }

  return (
    <div>
      <button onClick={handleStart}>Start Withdrawal</button>
      <p>State: {flow.state?.type}</p>
    </div>
  );
}

Available Hooks

useBluvoFlow(options)

The main hook that manages the entire withdrawal flow state machine.

Options:

• orgId - Your Bluvo organization ID
• projectId - Your Bluvo project ID
• fetchWithdrawableBalanceFn - Function to fetch wallet balances
• requestQuotationFn - Function to request withdrawal quotes
• executeWithdrawalFn - Function to execute withdrawals
• maxRetryAttempts? - Maximum retry attempts (default: 3)
• topicToken? - WebSocket topic token for real-time updates
• cacheName? - Cache name for WebSocket subscriptions
• cache? - QR code caching options (zero config with localStorage, see core SDK docs)
• mkUUIDFn? - Custom UUID generator function

Returns:

{
  // State
  state: FlowState | null,
  error: Error | null,
  context: FlowContext,
  
  // Actions  
  startWithdrawalFlow: (options) => Promise<void>,
  executeWithdrawal: (quoteId) => Promise<void>,
  submit2FA: (code) => Promise<void>,
  submitSMS: (code) => Promise<void>,
  retryWithdrawal: () => Promise<void>,
  cancel: () => void,
  
  // State Helpers
  isOAuthPending: boolean,
  isWalletReady: boolean,
  isQuoteReady: boolean,
  requires2FA: boolean,
  requiresSMS: boolean,
  requiresKYC: boolean,
  isWithdrawalComplete: boolean,
  canRetry: boolean,
  
  // Data
  walletBalances: Array<{asset: string, balance: string}>,
  quote: Quote | null,
  withdrawal: Withdrawal | null
}

QR Code Caching

QR code sessions are cached in localStorage by default — no setup needed. Users see their QR code instantly on page refresh.

const flow = useBluvoFlow({
  // ...other options
  cache: { prefix: "myapp:" }, // Optional: customize caching
});

Pass cache: { disabled: true } to disable. See core SDK docs for the full BluvoCacheOptions API.

useFlowMachine(machine)

Lower-level hook for direct state machine interaction.

useWithdrawMachine(machine)

Hook for managing the withdrawal sub-state machine.

Security

This library follows security best practices:

• No API keys in browser: Uses callback functions that call your secure server endpoints
• Server-side operations: All sensitive operations happen on your server
• Type safety: Full TypeScript support with proper error handling

State Flow

idle → oauth:waiting → wallet:loading → quote:ready → withdraw:processing → completed
  ↓         ↓               ↓             ↓              ↓
cancel   cancel        error states    2FA/SMS/KYC    success/retry

Framework Integration

Works seamlessly with:

• Next.js - Use with Server Actions
• Remix - Use with action functions
• SvelteKit - Use with form actions
• Any React app - Use with your API layer

Examples

See the examples directory for complete implementations with different frameworks.

License

MIT © Bluvo Inc.