⚙️Customization

Rango Widget Config

Overview

The WidgetConfig object allows you to customize your widget to fit your application's needs. The following sections provide a detailed breakdown of all available properties, organized by category.

You can customize your widget in the Playground and use the "Export Code" button at the top to obtain the final configuration.

---

1. Core Configuration

• apiKey (string) - Required

  • Your API key for accessing the Rango API. This key is required to make widget requests.

• apiUrl (string) - Optional

  • The base API URL for custom API endpoints.

• walletConnectProjectId (string) - Optional

  • The Wallet Connect Project ID used for integrating WalletConnect. Obtain it from WalletConnect Cloud.

• title (string) - Optional

  • The title that appears on top of the widget.

• variant (WidgetVariant) - Optional

  • The layout variant of the widget.

    • 'default': Standard view.

    • 'expanded': Expanded view showing multiple routes.

    • 'full-expanded': Full route information visible on the homepage.

• amount (number) - Optional

  • The default value to be displayed in the swap input field.

---

2. Blockchain & Token Configuration

• from (BlockchainAndTokenConfig) - Optional

  • Configuration for the source blockchain and token.

    • blockchains (string[]): A list of allowed source blockchains.

    • blockchain (string): The default blockchain.

    • token (Asset): The default token configuration.

• to (BlockchainAndTokenConfig) - Optional

  • Configuration for the destination blockchain and token.

    • blockchains (string[]): A list of allowed destination blockchains.

    • blockchain (string): The default blockchain.

    • token (Asset): The default token configuration.

• liquiditySources (string[]) - Optional

  • A list of allowed DEXes and bridges used for routing liquidity.

• excludeLiquiditySources (boolean) - Optional

  • If set to true, the liquidity sources defined in liquiditySources will be excluded instead of included.

• customDestination (boolean) - Optional

  • Enables the user to enter a custom blockchain address as the destination.

---

3. Theme Configuration

• theme (WidgetTheme) - Optional

  • Customize the visual appearance of the widget.

    • mode ('auto' | 'light' | 'dark'): Defines the theme mode.

    • fontFamily (string): Sets the font for the widget. To do this, please also include your preferred font in your HTML file.

    • colors (object): Customize colors for both light and dark modes. (Please check playground to play with different colors and presets.)

      • dark: Color configuration for dark mode.

      • light: Color configuration for light mode.

    • borderRadius (number): The border radius for the widget container.

    • secondaryBorderRadius (number): The border radius for buttons within the widget.

    • singleTheme (boolean): If set to true, limits the widget to one theme (dark or light) based on the mode value.

---

4. Routing Configuration

• routing (Routing) - Optional

  • maxLength (number): limit the maximum acceptable length of a route

  • avoidNativeFee ('enabled' | 'disabled'): Enable/disable avoid native fee.

  • experimental ('enabled' | 'disabled'): Enable/disable experimental routing.

  • enableCentralizedSwappers ('enabled' | 'disabled'): Enable/disable centralized swappers.

---

5. Wallet & Signers Configuration

• wallets (string[]) - Optional

  • A list of supported wallet types for connecting to the widget. Example: ['metamask', 'phantom'].

• multiWallets (boolean) - Optional

  • If set to true, the user can connect multiple wallets. Otherwise, he could only connect one wallet at the same time. (Not recommended)

• externalWallets (boolean) - Optional

  • Allows external wallet integration.

• signers (SignersConfig) - Optional

  • Custom RPC configuration for specific blockchains.

    • customSolanaRPC (string): Custom Solana RPC endpoint URL.

• trezorManifest (TrezorManifest) - Optional

  • Required for integrating Trezor wallets. Provide your app's URL and a contact email.

    • email (string): your email address

    • appUrl (string): your application URL

• tonConnect (TonConnectConfig) - Optional

  • Required for integrating Ton wallets.

    • manifestUrl (string): The link to your app URL containing your app URL, name and iconUrl. Sample: https://app.rango.exchange/tonconnect-manifest.json

---

6. Affiliate Configuration

• affiliate (WidgetAffiliate) - Optional

  • Configuration for charging affiliate fees. Please check widget monetization guide.

    • ref (string): Your affiliate referral code.

    • percent (number): The percentage of fees charged per transaction.

    • wallets (object): A map of blockchain names to affiliate wallet addresses.

---

7. Feature Toggles

• features (Features) - Optional

  • Controls the visibility of various features. For example, you could hide the theme or language settings in widget if you want to control it from your dApp.

    • theme ('visible' | 'hidden'): Show/hide the theme feature.

    • language ('visible' | 'hidden'): Show/hide the language selector.

    • connectWalletButton ('visible' | 'hidden'): Show/hide the connect wallet button.

    • notification ('visible' | 'hidden'): Show/hide the notification icon.

    • liquiditySource ('visible' | 'hidden'): Show/hide liquidity source information.

    • customTokens ('visible' | 'hidden'): Show/hide the custom token feature.

---

Sample Configuration Code

javascriptCopy codeconst config = {
  apiKey: 'c6381a79-2817-4602-83bf-6a641a409e32',
  walletConnectProjectId: 'e24844c5deb5193c1c14840a7af6a40b',
  title: 'My Custom Widget',
  amount: 1,
  from: {
    blockchains: ['BTC', 'LTC', 'BCH'],
    blockchain: 'BTC',
    token: {
      blockchain: 'BTC',
      symbol: 'BTC'
    }
  },
  to: {
    blockchains: ['ETH'],
    blockchain: 'ETH',
    token: {
      blockchain: 'ETH',
      symbol: 'ETH'
    }
  },
  theme: {
    mode: 'dark',
    colors: {
      dark: {
        background: '#000',
        primary: '#1C3CF1'
      },
      light: {
        background: '#FFF',
        primary: '#1C3CF1'
      }
    },
    borderRadius: 10
  },
  wallets: ['metamask', 'wallet-connect-2'],
  affiliate: {
    ref: 'your-affiliate-code',
    percent: 1,
    wallets: { 'ETH': '0x123...', 'BSC': '0xabc...' }
  },
  liquiditySources: ['Uniswap', 'SushiSwap'],
  excludeLiquiditySources: false,
  language: 'en',
  multiWallets: true,
  customDestination: true
};