Configuration

Introduction＃

Wormhole Connect is a flexible React widget that streamlines cross-chain asset transfers and enables seamless interoperability by leveraging Wormhole's powerful infrastructure. Designed for easy integration into decentralized applications (dApps), Wormhole Connect abstracts the complexities of cross-chain communication, providing a user-friendly experience for both developers and end users.

This guide provides detailed instructions on configuring Wormhole Connect and highlights the many ways it can be customized to fit your specific needs, from integrating supported blockchains and tokens to tailoring the user interface.

Note

To upgrade from Wormhole Connect v0 to v1, please refer to the migration guide for instructions.

If you're using an older version of Wormhole Connect (v0.x), please refer to the v0.x configuration documentation.

Get Started＃

Configure Wormhole Connect by passing a WormholeConnectConfig object as the config prop.

React integrationHosted integration

import WormholeConnect, {
  WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';

const config: WormholeConnectConfig = {
  chains: ['Ethereum', 'Polygon', 'Solana'],
  tokens: ['ETH', 'WETH', 'MATIC', 'WMATIC'],
  rpcs: {
    Ethereum: 'https://rpc.ankr.com/eth',
    Solana: 'https://rpc.ankr.com/solana',
  }
}

<WormholeConnect config={config} />

import WormholeConnect, {
  wormholeConnectHosted,
  WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';

const config: WormholeConnectConfig = {
  chains: ['Ethereum', 'Polygon', 'Solana'],
  tokens: ['ETH', 'WETH', 'MATIC', 'WMATIC'],
  rpcs: {
    Ethereum: 'https://rpc.ankr.com/eth',
    Solana: 'https://rpc.ankr.com/solana',
  },
};

const container = document.getElementById('bridge-container');

wormholeConnectHosted(container, {
  config,
});

Note

The complete type definition of WormholeConnectConfig is available in the Wormhole Connect repository.

Examples＃

Configuring Chains and RPC Endpoints＃

Connect lets you customize the available chains to match your project's needs. It is recommended that you provide your own RPC endpoints, as the default public ones may not support essential functions like balance fetching.

MainnetTestnet

import WormholeConnect, {
  WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';

const config: WormholeConnectConfig = {
  chains: ['Ethereum', 'Polygon', 'Solana'],
  rpcs: {
    Ethereum: 'https://rpc.ankr.com/eth',
    Solana: 'https://rpc.ankr.com/solana',
  },
};

function App() {
  return <WormholeConnect config={config} />;
}

import WormholeConnect, {
  WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';

const config: WormholeConnectConfig = {
  // You can use Connect with testnet chains by specifying "network":
  network: 'Testnet',
  chains: ['Sepolia', 'ArbitrumSepolia', 'BaseSepolia', 'Avalanche'],
  rpcs: {
    Avalanche: 'https://rpc.ankr.com/avalanche_fuji',
    BaseSepolia: 'https://base-sepolia-rpc.publicnode.com',
  },
};

function App() {
  return <WormholeConnect config={config} />;
}

Note

For a complete list of available chain names, see the Wormhole TypeScript SDK.

Configuring Routes＃

By default, Connect offers two bridging protocols: Token Bridge (for Wormhole wrapped tokens) and Circle's CCTP (for native USDC). For most use cases, integrators require more than these default routes. The routes property allows you to specify which protocols to include and exclude any routes unnecessary for your application, including default and third-party routes.

Available Route Plugins＃

The @wormhole-foundation/wormhole-connect package offers a variety of route plugins to give you flexibility in handling different protocols. You can choose from the following route exports for your integration:

TokenBridgeRoute - manually redeemed Wormhole Token Bridge route
AutomaticTokenBridgeRoute - automatically redeemed (relayed) Token Bridge route
CCTPRoute - manually redeemed CCTP route
AutomaticCCTPRoute - automatically redeemed (relayed) CCTP route
DEFAULT_ROUTES - array containing the four preceding routes (TokenBridgeRoute, AutomaticTokenBridgeRoute, CCTPRoute, AutomaticCCTPRoute)
nttAutomaticRoute(nttConfig) - function that returns the automatically-redeemed (relayed) Native Token Transfer (NTT) route
nttManualRoute(nttConfig) - function that returns the manually-redeemed NTT route
nttRoutes(nttConfig) - function that returns both NTT routes as an array
MayanRoute - route that offers multiple Mayan protocols
MayanRouteSWIFT - route for Mayan’s Swift protocol only
MayanRouteMCTP - route for Mayan’s MCTP protocol only
MayanRouteWH - route for Mayan’s original Wormhole transfer protocol

In addition to these routes, developers can create custom routes for their Wormhole-based protocols. For examples, refer to the NTT and the Mayan example GitHub repositories.

For further details on the route plugin interface, refer to the Wormhole TypeScript SDK route code.

Example: Offer Only CCTP Transfers＃

To configure Wormhole Connect to offer only USDC transfers via the CCTP route, use the following configuration:

import {
  AutomaticCCTPRoute,
  WormholeConnectConfig,
  WormholeConnect,
} from '@wormhole-foundation/wormhole-connect';

const config: WormholeConnectConfig = {
  routes: [AutomaticCCTPRoute],
};

<WormholeConnect config={config} />;

Example: Offer All Default Routes and Third-Party Plugins＃

In this example, Wormhole Connect is configured with routes for both default protocols (Token Bridge and CCTP), as well as third-party protocols like Native Token Transfers (NTT) and Mayan Swap.

import {
  DEFAULT_ROUTES,
  nttRoutes,
  MayanRouteSWIFT,
  WormholeConnectConfig,
  WormholeConnect,
} from '@wormhole-foundation/wormhole-connect';

import { myNttConfig } from './consts'; // Custom NTT configuration

const config: WormholeConnectConfig = {
  routes: [...DEFAULT_ROUTES, ...nttRoutes(myNttConfig), MayanRouteSWIFT],
};

<WormholeConnect config={config} />;

This flexible plugin allows you to combine default routes (such as Token Bridge and CCTP) with third-party protocols, offering complete control over which routes are available in your application.

Adding Custom Tokens＃

The following section shows how to add an arbitrary token to your deployment of Connect.

Note

You will need to register your token with the Token Bridge to get the contract addresses necessary for it to work with that protocol.

This example configuration adds the BONK token to Connect. Note the wrappedTokens property, which is required for use with the Token Bridge.

See src/config/types.ts for the type definition of TokensConfig.

import WormholeConnect, {
  WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';

const config: WormholeConnectConfig = {
  tokensConfig: {
    BONK: {
      key: 'BONK',
      symbol: 'BONK',
      nativeChain: 'Ethereum',
      icon: Icon.ETH,
      tokenId: {
        chain: 'Ethereum',
        address: '0x1151CB3d861920e07a38e03eEAd12C32178567F6',
      },
      coinGeckoId: 'bonk',
      decimals: 18,
    },
  },
  wrappedTokens: {
    BONK: {
      Solana: 'DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263',
    },
  },
};

Whitelisting Tokens＃

Connect offers a list of built-in tokens by default. You can see it below:

Using the tokens property, you can customize the tokens shown in the UI. In the following example, we add a custom token and restrict Connect from displaying only that token, along with the native gas tokens ETH and SOL.

import WormholeConnect, {
  WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';

const config: WormholeConnectConfig = {
  chains: ['Ethereum', 'Solana'],
  tokens: ['ETH', 'SOL', 'BONK'],
  rpcs: {
    Ethereum: 'https://rpc.ankr.com/eth',
    Solana: 'https://rpc.ankr.com/solana',
  },
  tokensConfig: {
    BONK: {
      key: 'BONK',
      symbol: 'BONK',
      nativeChain: 'Ethereum',
      icon: Icon.ETH,
      tokenId: {
        chain: 'Ethereum',
        address: '0x1151CB3d861920e07a38e03eEAd12C32178567F6',
      },
      coinGeckoId: 'bonk',
      decimals: 18,
    },
  },
  wrappedTokens: {
    BONK: {
      Solana: 'DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263',
    },
  },
};

function App() {
  return <WormholeConnect config={config} />;
}

Changing the Color Scheme＃

You can customize Connect's color scheme by providing a theme prop.

React integrationHosted integration

import WormholeConnect, {
  WormholeConnectConfig,
  WormholeConnectTheme,
} from '@wormhole-foundation/wormhole-connect';

const config: WormholeConnectConfig = {
  /* Your config... */
};

const theme: WormholeConnectTheme = {
  mode: 'dark',
  primary: '#78c4b6',
  font: 'Comic Sans; sans-serif',
};

function App() {
  return <WormholeConnect config={config} theme={theme} />;
}

import WormholeConnect, {
  WormholeConnectConfig,
  WormholeConnectTheme,
  wormholeConnectHosted,
} from '@wormhole-foundation/wormhole-connect';

const config: WormholeConnectConfig = {
  /* Your config... */
};

const theme: WormholeConnectTheme = {
  mode: 'dark',
  primary: '#78c4b6',
  font: 'Comic Sans; sans-serif',
};

const container = document.getElementById('bridge-container');

wormholeConnectHosted(container, {
  config,
  theme,
});

The WormholeConnectTheme type supports the following properties:

Property	Description	Example
`mode`	Dark mode or light mode. Required	`"dark"` or `"light"`
`input`	Color used for input fields, dropdowns	`"#AABBCC"`
`primary`	Primary color used for buttons	`"#AABBCC"`
`secondary`	Secondary color used for some UI elements	`"#AABBCC"`
`text`	Primary color used for text	`"#AABBCC"`
`textSecondary`	Secondary color used for dimmer text	`"#AABBCC"`
`error`	Color to display errors in, usually some shade of red	`"#AABBCC"`
`success`	Color to display success messages in	`"#AABBCC"`
`badge`	Background color used for chain logos	`"#AABBCC"`
`font`	Font used in the UI, can be custom font available in your application	`"Arial; sans-serif"`

More Configuration Options＃

Wallet Set Up＃

Your selected blockchain network determines the available wallet options when using Wormhole Connect.

For EVM chains, wallets like MetaMask and WalletConnect are supported
For Solana, you'll see options such as Phantom, Torus, and Coin98

The wallet options automatically adjust based on the selected chain, providing a seamless user experience without additional configuration.

If you would like to offer WalletConnect as a supported wallet option, you'll need to obtain a project ID on the WalletConnect cloud dashboard.

By setting the showHamburgerMenu option to false, you can deactivate the hamburger menu, which will position the links at the bottom.

By setting the showHamburgerMenu option to false, you can add extra links. The following properties are accessed through the menu[] property (e.g., menu[].label):

Property	Description
`label`	Link name to show up
`href`	Target URL or URN
`target`	Anchor standard target, by default `_blank`
`order`	Order where the new item should be injected

import WormholeConnect, {
  WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';

const config: WormholeConnectConfig = {
  ui: {
    showHamburgerMenu: false,
    menu: [
      {
        label: 'Advance Tools',
        href: 'https://portalbridge.com',
        target: '_self',
        order: 1,
      },
    ],
  },
};

function App() {
  return <WormholeConnect config={config} />;
}

CoinGecko API Key＃

The CoinGecko API can be used to fetch token price data. If you have a CoinGecko API Plan, you can include the API key in the configuration.

import WormholeConnect, {
  WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';

const config: WormholeConnectConfig = {
  coinGeckoApiKey: 'INSERT_API_KEY',
};

function App() {
  return <WormholeConnect config={config} />;
}

Configuration

Introduction＃

Get Started＃

Examples＃

Configuring Chains and RPC Endpoints＃

Configuring Routes＃

Available Route Plugins＃

Example: Offer Only CCTP Transfers＃

Example: Offer All Default Routes and Third-Party Plugins＃

Adding Custom Tokens＃

Whitelisting Tokens＃

Changing the Color Scheme＃

More Configuration Options＃

Wallet Set Up＃

Toggle Hamburger Menu＃

Add Extra Menu Entry＃

CoinGecko API Key＃