@unifold/connect-react-native

React Native/Expo SDK for crypto deposits and onramp with Unifold.

Installation

# npm
npm install @unifold/connect-react-native react-native-svg react-native-webview

# yarn
yarn add @unifold/connect-react-native react-native-svg react-native-webview

# Expo (recommended)
npx expo install @unifold/connect-react-native react-native-svg react-native-webview

iOS (bare React Native only)

cd ios && pod install

Quick Start

1. Wrap your app with UnifoldProvider

import { UnifoldProvider } from '@unifold/connect-react-native';

export default function App() {
  return (
    <UnifoldProvider
      publishableKey="pk_live_your_key"
      config={{
        appearance: 'dark', // 'light' | 'dark' | 'auto'
      }}
    >
      <YourApp />
    </UnifoldProvider>
  );
}

2. Launch the deposit flow

import { useUnifold } from '@unifold/connect-react-native';
import { Button, View } from 'react-native';

function DepositScreen() {
  const { beginDeposit } = useUnifold();

  const handleDeposit = async () => {
    try {
      const result = await beginDeposit({
        externalUserId: 'user_123',
        destinationChainType: 'ethereum',
        destinationChainId: '137', // Polygon
        destinationTokenAddress: '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359',
        destinationTokenSymbol: 'USDC',
        recipientAddress: '0x...user_wallet_address',
        onSuccess: (data) => {
          console.log('Deposit successful:', data);
        },
        onError: (error) => {
          console.error('Deposit error:', error);
        },
      });
      
      console.log('Deposit completed:', result);
    } catch (error) {
      // User cancelled the deposit flow
      console.log('Deposit cancelled');
    }
  };

  return (
    <View>
      <Button title="Deposit Crypto" onPress={handleDeposit} />
    </View>
  );
}

Theming & Customization

The SDK provides comprehensive theming options. For full documentation, see docs/theming.mdx.

Quick Theme Setup

<UnifoldProvider
  publishableKey="pk_live_..."
  config={{
    appearance: "dark",        // 'light' | 'dark' | 'auto'
    accentColor: "#8B5CF6",    // Brand color
    
    // Custom fonts (must be loaded by your app)
    fonts: {
      regular: "Inter-Regular",
      medium: "Inter-Medium",
      semibold: "Inter-SemiBold",
    },
    
    // Full color customization
    theme: {
      dark: {
        primary: "#8B5CF6",
        background: "#0F0F10",
        card: "#1A1A1D",
      }
    },
    
    // Granular component overrides
    components: {
      header: { titleColor: "#FFFFFF" },
      card: { backgroundColor: "#1A1A1D" },
    },
    
    // Bottom sheet corner radius
    sheetBorderRadius: {
      globalBorderTopLeftRadius: 24,   // Default for all sheets
      globalBorderTopRightRadius: 24,
      main: { borderTopLeftRadius: 0, borderTopRightRadius: 0 },
      buyWithCard: { borderTopLeftRadius: 16, borderTopRightRadius: 16 },
    },
  }}
>

Pre-selecting Source Token

await beginDeposit({
  externalUserId: "user_123",
  // ... destination params
  
  // Pre-select USDC on Polygon as the source token
  defaultChainType: "ethereum",
  defaultChainId: "137",
  defaultTokenAddress: "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
});

API Reference

UnifoldProvider

| Prop | Type | Required | Description | |------|------|----------|-------------| | publishableKey | string | Yes | Your Unifold publishable key | | config.appearance | 'light' \| 'dark' \| 'auto' | No | Theme mode (default: 'dark') | | config.modalTitle | string | No | Custom modal title | | config.hideDepositTracker | boolean | No | Hide the deposit tracker button | | config.transferInputVariant | 'single_input' \| 'double_input' | No | Token selector style (default: 'double_input') | | config.accentColor | string | No | Primary brand color | | config.theme | ThemeConfig | No | Full color customization | | config.fontFamily | string | No | Single font family for all text | | config.fonts | FontConfig | No | Granular font weight configuration | | config.components | ComponentConfig | No | Component-specific token overrides | | config.sheetBorderRadius | SheetBorderRadius | No | Border radius configuration for all bottom sheets (see below) |

SheetBorderRadius

Configure the border radius of all bottom sheets. Set global defaults and optionally override individual sheets. Per-component values accept { borderTopLeftRadius?: number, borderTopRightRadius?: number } and fall back to the global values, then to the default of 24.

| Key | Type | Description | |-----|------|-------------| | globalBorderTopLeftRadius | number | Default top-left radius for all sheets (default: 24) | | globalBorderTopRightRadius | number | Default top-right radius for all sheets (default: 24) | | main | BorderRadiusConfig | The main deposit modal | | transferCrypto | BorderRadiusConfig | Transfer crypto wrapper sheet | | buyWithCard | BorderRadiusConfig | Buy with card wrapper sheet | | depositsTracker | BorderRadiusConfig | Deposits tracker modal | | tokenSelector | BorderRadiusConfig | Token selector (inside transfer crypto) | | chainSelector | BorderRadiusConfig | Chain selector (inside transfer crypto, double_input variant) | | currencyModal | BorderRadiusConfig | Currency selector (inside buy with card) | | providerModal | BorderRadiusConfig | Provider selection (inside buy with card) | | depositStatus | BorderRadiusConfig | Deposit status sheet | | infoSheet | BorderRadiusConfig | Price impact & slippage info sheet | | webView | BorderRadiusConfig | WebView sheet (inside buy with card) |

// Example: sharp top corners everywhere, except currency modal gets rounded
<UnifoldProvider
  publishableKey="pk_live_..."
  config={{
    sheetBorderRadius: {
      globalBorderTopLeftRadius: 0,
      globalBorderTopRightRadius: 0,
      currencyModal: { borderTopLeftRadius: 16, borderTopRightRadius: 16 },
    },
  }}
>

useUnifold Hook

const { beginDeposit, closeDeposit, publishableKey } = useUnifold();

| Method | Type | Description | |--------|------|-------------| | beginDeposit | (config: DepositConfig) => Promise<DepositResult> | Opens the deposit modal and returns a promise | | closeDeposit | () => void | Programmatically close the deposit modal | | publishableKey | string | The configured publishable key |

DepositConfig

| Option | Type | Required | Description | |--------|------|----------|-------------| | externalUserId | string | Yes | Your user's unique identifier | | destinationChainType | 'ethereum' \| 'solana' \| 'bitcoin' | No | Target blockchain type | | destinationChainId | string | No | Target chain ID (e.g., '137' for Polygon) | | destinationTokenAddress | string | No | Target token contract address | | destinationTokenSymbol | string | No | Target token symbol (e.g., 'USDC') | | recipientAddress | string | No | Wallet address to receive funds | | defaultChainType | 'ethereum' \| 'solana' \| 'bitcoin' | No | Pre-select source network type | | defaultChainId | string | No | Pre-select source chain ID | | defaultTokenAddress | string | No | Pre-select source token address | | onSuccess | (data: DepositResult) => void | No | Called when deposit succeeds | | onError | (error: DepositError) => void | No | Called when an error occurs |

DepositResult

interface DepositResult {
  message: string;
  transaction?: unknown;
  executionId?: string;
}

DepositError

interface DepositError {
  message: string;
  error?: unknown;
  code?: string;  // e.g., 'DEPOSIT_CANCELLED' when user closes modal
}

TypeScript

Full TypeScript support is included. Import types as needed:

import type { 
  DepositConfig, 
  DepositResult, 
  DepositError,
  ThemeMode,
  ThemeConfig,
  FontConfig,
  ComponentConfig,
  BorderRadiusConfig,
  UnifoldProviderProps,
} from '@unifold/connect-react-native';

Requirements

| Dependency | Version | |------------|---------| | React Native | >= 0.72.0 | | Expo (optional) | >= 49.0.0 | | react-native-svg | >= 13.0.0 | | react-native-webview | >= 11.0.0 |

Support

• Documentation: https://docs.unifold.io
• Issues: GitHub Issues

License

MIT © Unifold