@mimboku/swap-sdk

A comprehensive React SDK for integrating Mimboku DEX Aggregator swap functionality into your DeFi applications.

Features

• 🔄 Complete Swap Widget - Ready-to-use swap interface with full UI/UX
• 🎯 Token Selection - Modal for browsing and selecting tokens
• ⚙️ Advanced Settings - Slippage tolerance, time limits, and protocol selection
• 📊 Route Display - Visual representation of swap routes and price impact
• 📈 Transaction History - View past swap transactions
• 🎨 Customizable Themes - Light and dark theme support
• 📱 Responsive Design - Works on desktop and mobile
• 🔗 Wallet Integration - Seamless connection with popular wallets
• 🛡️ Type Safety - Full TypeScript support

Installation

npm install @mimboku/swap-sdk
# or
yarn add @mimboku/swap-sdk

Quick Start

1. Basic Setup

import React from 'react';
import { SwapProvider, SwapWidget } from '@mimboku/swap-sdk';
import { WagmiProvider } from 'wagmi';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { config as wagmiConfig } from './wagmi-config';

// Import CSS (required)
import '@mimboku/swap-sdk/dist/styles/index.css';

const queryClient = new QueryClient();

const swapConfig = {
  quoteApiUrl: 'https://api.mimboku.com/quote',
  contractAddresses: {
    router: '0x1234567890123456789012345678901234567890',
    permit2: '0x000000000022D473030F116dDEE9F6B43aC78BA3',
  },
  defaultChainId: 1514,
  supportedChains: [1514, 1, 56, 137],
};

function App() {
  return (
    <WagmiProvider config={wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        <SwapProvider config={swapConfig}>
          <div className="max-w-md mx-auto p-4">
            <SwapWidget theme="dark" />
          </div>
        </SwapProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

export default App;

2. Custom Integration

You can also use individual components for a custom integration:

import React from 'react';
import {
  SwapProvider,
  SellingSection,
  BuyingSection,
  SwapButton,
  TokenSelectionModal,
  SlippageSettingsModal,
  useSwapState,
  useSwapSettings
} from '@mimboku/swap-sdk';

function CustomSwapInterface() {
  const {
    tokenIn,
    tokenOut,
    amountIn,
    amountOut,
    setTokenIn,
    setTokenOut,
    setAmountIn,
    swapTokens,
    balanceIn,
    isSwapEnabled,
    isFetchingQuote,
  } = useSwapState();

  const {
    slippage,
    timeLimit,
    protocols,
    setSlippage,
    setTimeLimit,
    setProtocols,
  } = useSwapSettings();

  return (
    <div className="swap-interface">
      <SellingSection
        tokenIn={tokenIn}
        amountIn={amountIn}
        setAmountIn={setAmountIn}
        balanceIn={balanceIn}
        openModal={() => {/* handle modal */}}
        isFetchingQuote={isFetchingQuote}
      />
      
      <button onClick={swapTokens}>
        Swap Tokens
      </button>
      
      <BuyingSection
        tokenOut={tokenOut}
        amountOut={amountOut}
        openModal={() => {/* handle modal */}}
        isFetchingQuote={isFetchingQuote}
      />
      
      <SwapButton
        tokenIn={tokenIn}
        tokenOut={tokenOut}
        amountIn={amountIn}
        isSwapEnabled={isSwapEnabled}
        isFetchingQuote={isFetchingQuote}
      />
    </div>
  );
}

Configuration

SwapConfig

interface SwapConfig {
  quoteApiUrl: string;           // API endpoint for fetching quotes
  contractAddresses: {
    router: string;              // DEX router contract address
    permit2?: string;            // Permit2 contract address (optional)
  };
  defaultChainId: number;        // Default blockchain network
  supportedChains: number[];     // List of supported chain IDs
}

SwapWidget Props

interface SwapWidgetProps {
  className?: string;            // Additional CSS classes
  theme?: 'light' | 'dark';     // Theme selection
  showHistory?: boolean;         // Show transaction history by default
  showChart?: boolean;           // Show chart by default
}

Components

Core Components

• SwapWidget - Complete swap interface
• SwapProvider - Context provider with configuration
• SellingSection - Token input section
• BuyingSection - Token output section
• SwapButton - Swap execution button
• TokenSelectionModal - Token selection interface
• SlippageSettingsModal - Advanced settings modal
• RouteDisplay - Route visualization
• ViewHistory - Transaction history
• LogoToken - Token logo component

Utility Hooks

• useSwapState - Main swap state management
• useSwapSettings - Settings state management
• useFetchQuote - Quote fetching logic
• useTokenApproval - Token approval handling
• useSwap - Swap execution logic

Types

import { IToken, QuoteResponse, SwapConfig } from '@mimboku/swap-sdk';

// Token interface
interface IToken {
  id: string;
  address: string;
  name: string;
  symbol: string;
  decimals: number;
  logoURI: string;
  chainId?: number;
}

// Quote response
interface QuoteResponse {
  amount: string;
  quote: string;
  gasUseEstimate: string;
  gasUseEstimateUSD: string;
  route: Array<Array<RouteStep>>;
  priceImpact: string;
  // ... additional fields
}

Theming

The SDK supports both light and dark themes:

<SwapWidget theme="light" />   // Light theme
<SwapWidget theme="dark" />    // Dark theme (default)

You can also customize the theme by overriding CSS variables:

.mimboku-swap-widget.custom {
  --background: #1a1a1a;
  --foreground: #ffffff;
  --accent: #00ff88;
  --secondary: #2a2a2a;
  --muted: #888888;
}

Examples

Check out the /examples directory for complete implementation examples:

• Basic Integration
• Custom Widget

Requirements

• React 16.8+
• wagmi 2.0+
• viem 2.0+
• @tanstack/react-query 5.0+

Peer Dependencies

The following packages are required as peer dependencies:

{
  "react": ">=16.8.0",
  "react-dom": ">=16.8.0",
  "wagmi": "^2.0.0",
  "viem": "^2.0.0",
  "ethers": "^6.0.0",
  "@tanstack/react-query": "^5.0.0"
}

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, please open an issue on GitHub or contact the Mimboku team.

Built with ❤️ by the Mimboku Team