MoonPay Module

The MoonPay module provides seamless cryptocurrency purchasing capabilities directly within your app. Users can buy crypto using credit cards, debit cards, Apple Pay, and other payment methods through MoonPay’s trusted platform.

Core Functionalities

Crypto On-Ramp

Purchase cryptocurrencies directly using various payment methods with automatic wallet integration

Wallet Integration

Automatically populates the user’s connected wallet address as the destination for purchases

Customizable Widget

Configurable MoonPay widget supporting both sandbox and production environments

Balance Management

View wallet balances and seamlessly navigate to purchase flows when funds are needed

Installation & Setup

Install MoonPay SDK

The module uses the official MoonPay React Native SDK:

npm install @moonpay/react-native-moonpay-sdk

Configure API Key

Add your MoonPay API key to .env.local:

MOONPAY_API_KEY=pk_test_your_api_key_here
# For production: pk_live_your_production_key

Import Components

Import the components you need:

import { 
  MoonPayWidget, 
  OnrampScreen,
  WalletScreen 
} from '@/modules/moonpay';

API Keys: Use pk_test_ prefixed keys for testing and pk_live_ for production. The module automatically detects the environment.

Module Architecture

src/modules/moonpay/
├── components/             # UI components
│   └── MoonPayWidget/     # Core MoonPay WebView wrapper
├── screens/               # Complete screen implementations
├── services/              # MoonPay configuration and utilities
├── types/                 # TypeScript definitions
└── utils/                 # Helper functions

Core Components

MoonPay Widget
Onramp Screen
Wallet Screen

MoonPayWidget - Core component that embeds MoonPay’s purchase flow

import { MoonPayWidget } from '@/modules/moonpay';

function PurchaseCrypto() {
  const handleWidgetOpen = () => {
    console.log('MoonPay widget opened');
  };
  
  const handleError = (error) => {
    console.error('MoonPay error:', error);
  };
  
  return (
    <MoonPayWidget
      apiKey={process.env.MOONPAY_API_KEY}
      environment="sandbox" // or "production"
      height={600}
      onOpen={handleWidgetOpen}
      onError={handleError}
      onRetry={() => console.log('Retrying...')}
    />
  );
}

Props:

apiKey - Your MoonPay API key
environment - ‘sandbox’ or ‘production’
height - Widget height in pixels
onOpen - Callback when widget loads
onError - Error handling callback
onRetry - Retry mechanism callback

OnrampScreen - Complete purchase screen with navigation and wallet integration

import { OnrampScreen } from '@/modules/moonpay';

function AppNavigator() {
  return (
    <Stack.Navigator>
      <Stack.Screen 
        name="OnrampScreen" 
        component={OnrampScreen}
        options={{ 
          title: 'Buy Crypto',
          headerShown: true 
        }}
      />
    </Stack.Navigator>
  );
}

Features:

Automatic wallet address detection
Loading and error states
Navigation header integration
Informational content about the purchase process

WalletScreen - Wallet balance display with on-ramp entry point

import { WalletScreen } from '@/modules/moonpay';
import { useNavigation } from '@react-navigation/native';

function WalletTab() {
  const navigation = useNavigation();
  
  return (
    <WalletScreen
      onAddFunds={() => navigation.navigate('OnrampScreen')}
      showBalance={true}
      showAddFundsButton={true}
    />
  );
}

Features:

SOL balance display
Wallet address with copy functionality
Add funds button integration
Balance refresh capability

Quick Start Example

import { OnrampScreen } from '@/modules/moonpay';
import { useWallet } from '@/modules/wallet-providers';

function BuyCryptoFlow() {
  const { wallet } = useWallet();
  
  if (!wallet) {
    return (
      <View style={styles.container}>
        <Text>Please connect your wallet first</Text>
      </View>
    );
  }
  
  return (
    <View style={styles.container}>
      <Text style={styles.title}>Buy Cryptocurrency</Text>
      <Text style={styles.subtitle}>
        Funds will be sent to: {wallet.address}
      </Text>
      <OnrampScreen />
    </View>
  );
}

import { MoonPayWidget } from '@/modules/moonpay';
import { useWallet } from '@/modules/wallet-providers';
import { useState } from 'react';

function CustomPurchaseScreen() {
  const { wallet } = useWallet();
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  const handleWidgetLoad = () => {
    setLoading(false);
    console.log('MoonPay widget loaded successfully');
  };

  const handleWidgetError = (err) => {
    setLoading(false);
    setError(err.message);
    console.error('MoonPay error:', err);
  };

  const handleRetry = () => {
    setError(null);
    setLoading(true);
  };

  return (
    <View style={styles.container}>
      <View style={styles.header}>
        <Text style={styles.title}>Purchase Crypto</Text>
        <Text style={styles.walletInfo}>
          Destination: {formatWalletAddress(wallet?.address)}
        </Text>
      </View>
      
      {loading && (
        <View style={styles.loadingContainer}>
          <ActivityIndicator size="large" />
          <Text>Loading MoonPay...</Text>
        </View>
      )}
      
      {error && (
        <View style={styles.errorContainer}>
          <Text style={styles.errorText}>{error}</Text>
          <Button title="Retry" onPress={handleRetry} />
        </View>
      )}
      
      <MoonPayWidget
        apiKey={process.env.MOONPAY_API_KEY}
        environment={__DEV__ ? 'sandbox' : 'production'}
        height={500}
        onOpen={handleWidgetLoad}
        onError={handleWidgetError}
        onRetry={handleRetry}
      />
    </View>
  );
}

import { useNavigation } from '@react-navigation/native';
import { WalletScreen } from '@/modules/moonpay';

function MainWalletTab() {
  const navigation = useNavigation();

  const handleAddFunds = () => {
    navigation.navigate('OnrampScreen');
  };

  const handleViewTransactions = () => {
    navigation.navigate('TransactionHistory');
  };

  return (
    <View style={styles.container}>
      <WalletScreen
        onAddFunds={handleAddFunds}
        onViewTransactions={handleViewTransactions}
        showBalance={true}
        showAddFundsButton={true}
        customActions={[
          {
            title: 'Swap Tokens',
            onPress: () => navigation.navigate('SwapScreen')
          }
        ]}
      />
    </View>
  );
}

MoonPay Service Configuration

The moonpayService.ts provides configuration and validation utilities:

import { createMoonPayService } from '@/modules/moonpay';

// Create MoonPay service instance
const moonPayService = createMoonPayService({
  apiKey: process.env.MOONPAY_API_KEY,
  environment: 'sandbox', // or 'production'
});

// Validate configuration
const isValid = moonPayService.validateConfig();
if (!isValid) {
  console.error('MoonPay configuration is invalid');
}

// Get widget URL (if needed for custom implementations)
const widgetUrl = moonPayService.getWidgetUrl({
  walletAddress: userWallet.address,
  currencyCode: 'SOL',
  baseCurrencyCode: 'USD',
});

Utility Functions

object

Show Address Formatting

formatWalletAddress(address) - Shortens wallet addresses for display

import { formatWalletAddress } from '@/modules/moonpay/utils';

const address = '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM';
const formatted = formatWalletAddress(address);
// Returns: "9WzD...AWWM"

object

Show Error Handling

parseErrorMessage(error) - Converts raw errors to user-friendly messages

import { parseErrorMessage } from '@/modules/moonpay/utils';

try {
  // MoonPay operation
} catch (error) {
  const userMessage = parseErrorMessage(error);
  Alert.alert('Purchase Failed', userMessage);
}

object

Show Environment Detection

getEnvironmentFromConfig(apiKey) - Automatically detects sandbox vs production

import { getEnvironmentFromConfig } from '@/modules/moonpay/utils';

const environment = getEnvironmentFromConfig(process.env.MOONPAY_API_KEY);
// Returns: 'sandbox' for pk_test_ keys, 'production' for pk_live_ keys

Advanced Usage Patterns

Custom Purchase Flow

function CustomPurchaseFlow() {
  const { wallet } = useWallet();
  const [purchaseAmount, setPurchaseAmount] = useState('');
  const [selectedCurrency, setSelectedCurrency] = useState('SOL');

  const initiateCustomPurchase = () => {
    // Custom logic before showing MoonPay widget
    analytics.track('purchase_initiated', {
      amount: purchaseAmount,
      currency: selectedCurrency,
      wallet: wallet.address
    });
    
    // Show MoonPay widget with pre-filled values
    navigation.navigate('OnrampScreen', {
      defaultAmount: purchaseAmount,
      defaultCurrency: selectedCurrency
    });
  };

  return (
    <View>
      <TextInput
        value={purchaseAmount}
        onChangeText={setPurchaseAmount}
        placeholder="Amount to purchase"
        keyboardType="numeric"
      />
      
      <Picker
        selectedValue={selectedCurrency}
        onValueChange={setSelectedCurrency}
      >
        <Picker.Item label="Solana (SOL)" value="SOL" />
        <Picker.Item label="USD Coin (USDC)" value="USDC" />
      </Picker>
      
      <Button
        title="Buy Crypto"
        onPress={initiateCustomPurchase}
      />
    </View>
  );
}

Transaction Status Tracking

function useMoonPayTransactionStatus() {
  const [transactions, setTransactions] = useState([]);
  const [loading, setLoading] = useState(false);

  const trackTransaction = async (transactionId) => {
    setLoading(true);
    try {
      // Note: This would require backend integration with MoonPay's API
      const status = await fetch(`/api/moonpay/transaction/${transactionId}`);
      const data = await status.json();
      
      setTransactions(prev => 
        prev.map(tx => 
          tx.id === transactionId 
            ? { ...tx, status: data.status }
            : tx
        )
      );
    } catch (error) {
      console.error('Failed to track transaction:', error);
    } finally {
      setLoading(false);
    }
  };

  return { transactions, trackTransaction, loading };
}

Balance-Based Recommendations

function BalanceBasedOnramp() {
  const { wallet } = useWallet();
  const { balance } = useBalance(wallet?.address);
  const [showRecommendation, setShowRecommendation] = useState(false);

  useEffect(() => {
    // Show purchase recommendation if balance is low
    if (balance < 0.1) { // Less than 0.1 SOL
      setShowRecommendation(true);
    }
  }, [balance]);

  if (!showRecommendation) return null;

  return (
    <Card style={styles.recommendationCard}>
      <Text style={styles.recommendationTitle}>Low Balance Detected</Text>
      <Text style={styles.recommendationText}>
        Your SOL balance is low ({balance.toFixed(4)} SOL). 
        Consider adding funds to cover transaction fees.
      </Text>
      <Button
        title="Add Funds"
        onPress={() => navigation.navigate('OnrampScreen')}
      />
      <TouchableOpacity onPress={() => setShowRecommendation(false)}>
        <Text style={styles.dismissText}>Dismiss</Text>
      </TouchableOpacity>
    </Card>
  );
}

Integration with Other Modules

Embedded Wallets

Automatic wallet address detection and integration

Data Module

Real-time balance updates and transaction history

Swap Module

Purchase crypto then immediately swap to desired tokens

Thread Module

Share purchase milestones and achievements

Combined Workflow Example

import { useWallet } from '@/modules/wallet-providers';
import { useFetchTokens } from '@/modules/data-module';
import { useSwap } from '@/modules/swap';
import { MoonPayWidget } from '@/modules/moonpay';

function BuyAndSwapFlow() {
  const { wallet } = useWallet();
  const { refetch: refetchBalance } = useFetchTokens(wallet?.address);
  const { executeSwap } = useSwap();
  const [purchaseComplete, setPurchaseComplete] = useState(false);

  const handlePurchaseComplete = async () => {
    setPurchaseComplete(true);
    
    // Refresh balance after purchase
    await refetchBalance();
    
    // Optional: Auto-swap purchased SOL to another token
    const shouldSwap = await askUserForSwap();
    if (shouldSwap) {
      navigation.navigate('SwapScreen', {
        inputToken: 'SOL',
        outputToken: 'USDC'
      });
    }
  };

  return (
    <View>
      {!purchaseComplete ? (
        <MoonPayWidget
          apiKey={process.env.MOONPAY_API_KEY}
          environment="production"
          onOpen={handlePurchaseComplete}
        />
      ) : (
        <PurchaseSuccessScreen onContinue={() => navigation.goBack()} />
      )}
    </View>
  );
}

Environment Configuration

Development
Production

# .env.local for development
MOONPAY_API_KEY=pk_test_your_sandbox_key_here

Uses sandbox environment automatically
Test transactions don’t involve real money
Full widget functionality for testing

# .env.local for production
MOONPAY_API_KEY=pk_live_your_production_key_here

Uses live MoonPay environment
Real transactions with actual payment processing
Requires KYC compliance and full verification

Error Handling & Troubleshooting

object

Show Common Issues

Widget Not Loading

Verify MOONPAY_API_KEY is correctly set
Check internet connectivity
Ensure API key has proper permissions

Payment Failures

Card verification issues
Insufficient funds
Geographic restrictions
KYC requirements not met

Network Errors

Backend connectivity issues
Solana network congestion
Invalid wallet addresses

function RobustMoonPayWidget() {
  const [error, setError] = useState(null);
  const [retryCount, setRetryCount] = useState(0);
  const maxRetries = 3;

  const handleError = (err) => {
    console.error('MoonPay error:', err);
    setError(parseErrorMessage(err));
  };

  const handleRetry = () => {
    if (retryCount < maxRetries) {
      setRetryCount(prev => prev + 1);
      setError(null);
    } else {
      Alert.alert(
        'Connection Failed',
        'Please check your internet connection and try again later.'
      );
    }
  };

  return (
    <View>
      {error ? (
        <ErrorDisplay 
          message={error}
          onRetry={retryCount < maxRetries ? handleRetry : null}
        />
      ) : (
        <MoonPayWidget
          apiKey={process.env.MOONPAY_API_KEY}
          environment="production"
          onError={handleError}
          onRetry={handleRetry}
        />
      )}
    </View>
  );
}

Security Considerations

API Key Security: Never expose production API keys in client-side code. Consider using a backend proxy for additional security.

User Verification: MoonPay handles KYC/AML compliance, but ensure your app provides clear information about verification requirements.

API Reference

For detailed API documentation, see:

The MoonPay module provides a seamless bridge between traditional finance and crypto, enabling users to easily onboard into the Solana ecosystem with familiar payment methods.

Introduction

Getting Started

Using LLMs

Modules

Server

Core Functionalities

Crypto On-Ramp

Wallet Integration

Customizable Widget

Balance Management

Installation & Setup

Module Architecture

Core Components

Quick Start Example

MoonPay Service Configuration

Utility Functions

Advanced Usage Patterns

Custom Purchase Flow

Transaction Status Tracking

Balance-Based Recommendations

Integration with Other Modules

Embedded Wallets

Data Module

Swap Module

Thread Module

Combined Workflow Example

Environment Configuration

Error Handling & Troubleshooting

Security Considerations

API Reference

​Core Functionalities

Crypto On-Ramp

Wallet Integration

Customizable Widget

Balance Management

​Installation & Setup

​Module Architecture

​Core Components

​Quick Start Example

​MoonPay Service Configuration

​Utility Functions

​Advanced Usage Patterns

​Custom Purchase Flow

​Transaction Status Tracking

​Balance-Based Recommendations

​Integration with Other Modules

Embedded Wallets

Data Module

Swap Module

Thread Module

​Combined Workflow Example

​Environment Configuration

​Error Handling & Troubleshooting

​Security Considerations

​API Reference

Core Functionalities

Installation & Setup

Module Architecture

Core Components

Quick Start Example

MoonPay Service Configuration

Utility Functions

Advanced Usage Patterns

Custom Purchase Flow

Transaction Status Tracking

Balance-Based Recommendations

Integration with Other Modules

Combined Workflow Example

Environment Configuration

Error Handling & Troubleshooting

Security Considerations

API Reference