@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();

Widget Events

The widget emits structured events via postMessage that you can listen to through the SDK. This lets you react to user actions like completed transactions.

Event Envelope

Every event posted from the iframe follows this shape:

interface SwapperWidgetEvent {
  type: "SWAPPER_EVENT";       // discriminator
  version: "1.0";              // protocol version
  name: WidgetEventName;       // e.g. "transaction_success"
  timestamp: string;           // ISO 8601
  payload: WidgetEventPayload; // event-specific data
}

Listening with onEvent (recommended)

The simplest way to listen for widget events is to pass an onEvent callback in the config. It receives every event (equivalent to .on("*", ...)):

import { SwapperIframe, WidgetEventName } from '@swapper-finance/deposit-sdk';
import type { TransactionSuccessPayload } from '@swapper-finance/deposit-sdk';

const swapper = new SwapperIframe({
  container: '#swapper-container',
  integratorId: 'your-integrator-id',
  dstChainId: '8453',
  dstTokenAddr: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
  depositWalletAddress: '0x2A018F2506acaEEE2C10632514Fc5DCa9eE2c28A',
  onEvent: (event) => {
    if (event.type === WidgetEventName.TRANSACTION_SUCCESS) {
      const payload = event.data as TransactionSuccessPayload;
      console.log('Transaction succeeded:', payload.txHash);
    }
  },
});

This also works with openSwapperModal:

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

openSwapperModal({
  integratorId: 'your-integrator-id',
  dstChainId: '8453',
  dstTokenAddr: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
  depositWalletAddress: '0x2A018F2506acaEEE2C10632514Fc5DCa9eE2c28A',
  onEvent: (event) => {
    console.log('Widget event:', event.type, event.data);
  },
});

Listening with on() / off()

For more granular control, you can register handlers on the iframe instance directly:

import { SwapperIframe, WidgetEventName } from '@swapper-finance/deposit-sdk';
import type { TransactionSuccessPayload } from '@swapper-finance/deposit-sdk';

const swapper = new SwapperIframe({
  container: '#swapper-container',
  integratorId: 'your-integrator-id',
  dstChainId: '8453',
  dstTokenAddr: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
  depositWalletAddress: '0x2A018F2506acaEEE2C10632514Fc5DCa9eE2c28A',
});

// Listen for a specific event
swapper.on(WidgetEventName.TRANSACTION_SUCCESS, (event) => {
  const payload = event.data as TransactionSuccessPayload;
  console.log('Transaction succeeded:', payload.txHash);
  console.log('Deposit option:', payload.depositOption); // "walletDeposit" | "transferCrypto" | "depositWithCash"
});

// Listen for all events with wildcard
swapper.on('*', (event) => {
  console.log('Widget event:', event.type, event.data);
});

// Remove a specific handler
const handler = (event) => { /* ... */ };
swapper.on(WidgetEventName.TRANSACTION_SUCCESS, handler);
swapper.off(WidgetEventName.TRANSACTION_SUCCESS, handler);

Listening with window.addEventListener

You can also listen for events directly on the window. Each event is a MessageEvent containing a SwapperWidgetEvent envelope:

import { WIDGET_EVENT_PROTOCOL_VERSION, WidgetEventName } from '@swapper-finance/deposit-sdk';
import type { SwapperWidgetEvent, TransactionSuccessPayload } from '@swapper-finance/deposit-sdk';

window.addEventListener('message', (event: MessageEvent) => {
  if (event.data?.type !== 'SWAPPER_EVENT') return;

  const message = event.data as SwapperWidgetEvent;

  if (message.version !== WIDGET_EVENT_PROTOCOL_VERSION) return;

  if (message.name === WidgetEventName.TRANSACTION_SUCCESS) {
    const payload = message.payload as TransactionSuccessPayload;
    console.log('Tx hash:', payload.txHash);
    console.log('Explorer:', payload.explorerUrl);
  }
});

TransactionSuccessPayload

| Field | Type | Required | Description | |------------------|-------------------|----------|---------------------------------------| | depositOption | DepositFlowType | Yes | "walletDeposit", "transferCrypto", or "depositWithCash" | | txHash | string | No | Transaction hash | | explorerUrl | string | No | Link to block explorer | | tokenSymbol | string | No | Token symbol (e.g. "USDC") | | tokenAddress | string | No | Token contract address | | chainId | string | No | Chain ID of the transaction | | amountReceived | string | No | Amount received |

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} />;
}