@swapper-finance/deposit-sdk

Easy iframe embedding SDK for the Swapper Finance deposit widget with full TypeScript support.

The SDK provides two integration options: iframe embedding for seamless integration into your application, and modal popup for a focused user experience. Both options support full customization and TypeScript types.

Installation

npm install @swapper-finance/deposit-sdk

Quick Start

Option 1: Embed in Container

import { SwapperIframe } from '@swapper-finance/deposit-sdk';

// Create and mount the iframe
const swapper = new SwapperIframe({
  container: '#swapper-container', // or pass an HTMLElement
  integratorId: 'your-integrator-id',
  dstChainId: '8453',
  dstTokenAddr: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
  depositWalletAddress: '0x2A018F2506acaEEE2C10632514Fc5DCa9eE2c28A',
});

Option 2: Open in Modal Popup

import { openSwapperModal } from '@swapper-finance/deposit-sdk';

// Open in a centered modal with backdrop
const modal = openSwapperModal({
  integratorId: 'your-integrator-id',
  dstChainId: '8453',
  dstTokenAddr: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
  depositWalletAddress: '0x2A018F2506acaEEE2C10632514Fc5DCa9eE2c28A',
});

// Close programmatically if needed
// modal.close();

Configuration Options

Required Parameters

• integratorId - Your integrator identifier
• dstChainId - Destination chain ID
• dstTokenAddr - Destination token address
• depositWalletAddress - Wallet address for deposits

Optional Parameters

Styling

The SDK supports a three-tier styling system:

const swapper = new SwapperIframe({
  // ... required params
  styles: {
    // Level 1: Theme mode (light or dark)
    themeMode: 'dark',
    
    // Level 2: Brand colors
    brandTheme: {
      primaryColor: '#FF6B35',
      secondaryColor: '#004E89',
    },
    
    // Level 3: Component-specific overrides (highest priority)
    componentStyles: {
      backgroundColor: '#1A1A1A',
      textColor: '#E8E8E8',
      borderRadius: '12px',
      width: '100%',
      primaryButtonBackground: '#FF6B35',
      primaryButtonText: '#FFFFFF',
      // ... more style options
    },
  },
});

Custom Contract Calls

import { ContractCallType } from '@swapper-finance/deposit-sdk';

const swapper = new SwapperIframe({
  // ... required params
  customContractCalls: [
    {
      callType: ContractCallType.CALL,
      target: '0x...',
      value: '0',
      callData: '0x...',
      payload: '0x...'
    },
  ],
});

API Reference

Constructor

new SwapperIframe(options: SwapperIframeOptions)

Methods

mount(container: HTMLElement | string): void

Mounts the iframe to a container element.

swapper.mount('#my-container');
// or
swapper.mount(document.getElementById('my-container'));

updateConfig(config: Partial<SwapperConfig>): void

Updates the configuration dynamically via postMessage.

swapper.updateConfig({
  depositWalletAddress: '0xNewAddress...',
  dstChainId: '1',
});

updateStyles(styles: SwapperStyles): void

Updates only the styles.

swapper.updateStyles({
  themeMode: 'light',
  brandTheme: {
    primaryColor: '#836FFF',
  },
});

updateCustomContractCalls(calls: ContractCall[]): void

Updates custom contract calls.

swapper.updateCustomContractCalls([
  {
    callType: ContractCallType.CALL,
    target: '0x...',
    value: '0',
    callData: '0x...',
    payload: '0x...',
  },
]);

getConfig(): SwapperConfig

Returns the current configuration.

const config = swapper.getConfig();
console.log(config.depositWalletAddress);

destroy(): void

Removes the iframe and cleans up event listeners.

swapper.destroy();

Modal API Reference

Opening a Modal

Quick Function: openSwapperModal(options)

import { openSwapperModal } from '@swapper-finance/deposit-sdk';

const modal = openSwapperModal({
  // Required configuration
  integratorId: 'your-id',
  dstChainId: '8453',
  dstTokenAddr: '0x...',
  depositWalletAddress: '0x...',
  
  // Optional: Widget styling
  styles: {
    themeMode: 'light',
  },
  
  // Optional: Modal styling
  modalStyle: {
    overlayColor: 'rgba(0, 0, 0, 0.8)',
    borderRadius: '16px'
  },
  
  // Optional: Callback when closed
  onClose: () => {
    console.log('Modal was closed');
  },
});

// Close programmatically
modal.close();

Modal Options

modalStyle Configuration

interface ModalStyle {
  /**
   * Modal width (default: '450px')
   */
  width?: string;
  
  /**
   * Modal height (default: '560px')
   */
  height?: string;
  
  /**
   * Background overlay color (default: 'rgba(0, 0, 0, 0.7)')
   */
  overlayColor?: string;
  
  /**
   * Modal border radius (default: '16px')
   */
  borderRadius?: string;
  
  /**
   * Z-index for modal (default: 10000)
   */
  zIndex?: number;
  
  /**
   * Show close button (default: false)
   * Set to true to show a close button
   */
  showCloseButton?: boolean;
}

Modal Class Methods

SwapperModal Class

For more control, use the SwapperModal class directly:

import { SwapperModal } from '@swapper-finance/deposit-sdk';

// Create modal instance
const modal = new SwapperModal({
  integratorId: 'your-id',
  dstChainId: '8453',
  dstTokenAddr: '0x...',
  depositWalletAddress: '0x...',
  modalStyle: {
    showCloseButton: true, // Optional: show close button
  },
  onClose: () => {
    console.log('Modal closed');
  },
});

// Open modal
modal.open();

// Close modal
modal.close();

// Check if open
if (modal.isModalOpen()) {
  console.log('Modal is open');
}

// Get iframe instance
const iframe = modal.getIframe();

// Destroy completely
modal.destroy();

Available Style Properties

ComponentStyles

interface ComponentStyles {
  // Layout
  backgroundColor?: string;
  borderRadius?: string;
  width?: string;

  // Typography
  textColor?: string;

  // Buttons
  primaryButtonBackground?: string;
  primaryButtonText?: string;
  secondaryButtonBackground?: string;
  secondaryButtonText?: string;
  disabledButtonBackground?: string;
  disabledButtonText?: string;

  // Status colors
  successColor?: string;
  warningColor?: string;
  errorColor?: string;

  // Brand colors
  primaryColor?: string;
  secondaryColor?: string;

  // Additional UI elements
  inputBackground?: string;
  inputBorder?: string;
  cardBackground?: string;
  borderColor?: string;
}

Examples

Modal Popup Usage

<!DOCTYPE html>
<html>
<head>
  <title>Swapper Modal</title>
</head>
<body>
  <button id="open-modal">Open Swapper</button>
  
  <script type="module">
    import { openSwapperModal } from '@swapper-finance/deposit-sdk';
    
    document.getElementById('open-modal').onclick = () => {
      openSwapperModal({
        integratorId: 'your-integrator-id',
        dstChainId: '8453',
        dstTokenAddr: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
        depositWalletAddress: '0x2A018F2506acaEEE2C10632514Fc5DCa9eE2c28A',
        modalStyle: {
          width: '600px',
          height: '800px',
        },
        onClose: () => {
          console.log('Modal closed');
        },
      });
    };
  </script>
</body>
</html>

React Example (Embedded)

import { useEffect, useRef } from 'react';
import { SwapperIframe } from '@swapper-finance/deposit-sdk';

function SwapperWidget() {
  const containerRef = useRef<HTMLDivElement>(null);
  const swapperRef = useRef<SwapperIframe | null>(null);

  useEffect(() => {
    if (containerRef.current && !swapperRef.current) {
      swapperRef.current = new SwapperIframe({
        container: containerRef.current,
        integratorId: 'your-integrator-id',
        dstChainId: '8453',
        dstTokenAddr: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
        depositWalletAddress: '0x2A018F2506acaEEE2C10632514Fc5DCa9eE2c28A',
      });
    }

    return () => {
      swapperRef.current?.destroy();
      swapperRef.current = null;
    };
  }, []);

  return <div ref={containerRef} />;
}